Prep for v0.4.1

These changes accommodate for some difference in the HTML structure AsciiDoc produces for source code listings:

 * proper padding for source code listings
 * proper vertical margin after source code listings
 * proper placement of the copy button if enabled

Closes #1163

.github/workflows/ci.yml

@@ -5,23 +5,25 @@ on:
   pull_request:
     branches:
       - main
-      - 'v**'
 
 name: CI
 
 jobs:
   jekyll-build:
-    name: Build Jekyll site
-    runs-on: ubuntu-latest
+    name: Build (jekyll gem)
     strategy:
+      fail-fast: false
       matrix:
         jekyll-version: [3.9, 4.3]
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        ruby-version: [2.7, 3.1]
+    runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v3
-    - name: Setup Ruby
+    - name: Setup Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
       with:
-        ruby-version: '3.1' # Not needed with a .ruby-version file
+        ruby-version: ${{ matrix.ruby-version }}
         bundler-cache: false
     - name: Bundle Install
       run: bundle install
@@ -32,6 +34,21 @@ jobs:
     - name: Build Site
       run: bundle exec jekyll build
 
+  github-pages-build:
+    name: Build (github-pages gem)
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Setup Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.1'
+        bundler-cache: false
+    - name: Bundle Install
+      run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle install
+    - name: Build Site
+      run: BUNDLE_GEMFILE=fixtures/Gemfile-github-pages bundle exec jekyll build
+
   assets:
     name: Test CSS and JS
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -16,11 +16,66 @@ The project underwent a major maintenance shift in March 2022.
 This website is built from the `HEAD` of the `main` branch of the theme repository.
 
 {: .warning }
-This website includes docs for some new features that are not available in `v0.4.0`!
+This website includes docs for some new features that are not available in `v0.4.1`!
 
-Changes to `main` that are *not* in the latest release:
+Code changes to `main` that are *not* in the latest release:
 
-- n/a
+- N/A
+
+Docs changes in `main` that are *not* in the latest release:
+
+- N/A
+
+## Release v0.4.1
+
+Hello! We hope you've been enjoying the new `v0.4.0`; we appreciate all the feedback we've gotten already! As promised, future releases will be small with simple steps to upgrade. This is one of them! `v0.4.1` is a [semver patch](https://semver.org/): it only includes bugfixes, and is fully backwards-compatible.
+
+As always, we'd love your feedback. [Open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) for bug reports, feature requests, and any other feedback. Thanks for continuing to use Just the Docs!
+
+### Using Release `v0.4.1`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.4.1` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.4.1
+```
+
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
+
+```ruby
+gem "just-the-docs", "0.4.1"
+```
+
+To use and pin a previous version of the theme, replace the `0.4.1` with the desired release tag.
+
+### Bugfixes
+
+- Fixed: allow later versions of `bundler` by [@mattxwang] in [#1165]
+- Fixed: AsciiDoc code block styling by [@flyx] in [#1168]
+- Fixed: main content negative margin for viewports in `[$md, $nav-width + $content-width]` by [@Dima-369] in [#1177]
+- Removed: unused `OneDarkJekyll` files by [@mattxwang] in [#1167]
+
+### Documentation
+
+- Fixed: re-add `jekyll-github-metadata` to docs site by [@mattxwang] in [#1108]
+
+### New Contributors
+
+- [@flyx] made their first contribution in [#1168]
+- [@Dima-369] made their first contribution in [#1177]
+
+[#1108]: https://github.com/just-the-docs/just-the-docs/pull/1108
+[#1165]: https://github.com/just-the-docs/just-the-docs/pull/1165
+[#1167]: https://github.com/just-the-docs/just-the-docs/pull/1167
+[#1168]: https://github.com/just-the-docs/just-the-docs/pull/1168
+[#1177]: https://github.com/just-the-docs/just-the-docs/pull/1177
+
+[@flyx]: https://github.com/flyx
+[@Dima-369]: https://github.com/Dima-369
+
+**Full Changelog**: [https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1](https://github.com/just-the-docs/just-the-docs/compare/v0.4.0...v0.4.1)
 
 ## Release v0.4.0
 

Gemfile

@@ -1,4 +1,6 @@
 source "https://rubygems.org"
 gemspec
 
+gem "jekyll-github-metadata", ">= 2.15"
+
 gem "webrick", "~> 1.7"

_config.yml

@@ -17,6 +17,7 @@ title: Just the Docs
 description: A Jekyll theme for documentation
 baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
 url: "https://just-the-docs.github.io" # the base hostname & protocol for your site, e.g. http://example.com
+repository: just-the-docs/just-the-docs # for github-metadata
 
 permalink: pretty
 
@@ -42,6 +43,8 @@ exclude:
    - package-lock.json
    - Rakefile
    - README.md
+ # theme test code
+   - fixtures/
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
@@ -159,6 +162,7 @@ callouts:
 
 plugins:
   - jekyll-seo-tag
+  - jekyll-github-metadata
 
 kramdown:
   syntax_highlighter_opts:

_sass/code.scss

@@ -50,6 +50,11 @@ a:visited code {
 // Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
 
 // ```[LANG]...```
+// or in AsciiDoc:
+//
+//     ----
+//     ...
+//     ----
 
 // the code may appear with 3 different types:
 // container \ case:  default case,          code with line number,   code with html rendering
@@ -59,6 +64,7 @@ a:visited code {
 // last level:        code,                  pre,                     code (optionality)
 // highlighter level: span,                  span,                    span
 // the spacing are only in the second level for case 1, 3 and in the third level for case 2
+// in AsciiDoc, there is a parent container that contains optionally a title and the content.
 
 // select top level container
 div.highlighter-rouge,
@@ -111,17 +117,17 @@ figure.highlight {
 }
 
 // setting the spacing and scrollbar on the second level for the first case
-// remove all space on the second and thirt level
-div.highlighter-rouge,
-div.listingblock {
-  div.highlight {
+// remove all space on the second and third level
+// this is a mixin to accommodate for the slightly different structures generated via Markdown vs AsciiDoc
+@mixin scroll-and-spacing($code-div, $pre-select) {
+  #{$code-div} {
     overflow-x: auto;
     padding: $sp-3;
     margin: 0;
     border: 0;
   }
 
-  pre.highlight,
+  #{$pre-select},
   code {
     padding: 0;
     margin: 0;
@@ -129,6 +135,19 @@ div.listingblock {
   }
 }
 
+// for Markdown
+div.highlighter-rouge {
+  @include scroll-and-spacing("div.highlight", "pre.highlight");
+}
+
+// for AsciiDoc. we also need to fix the margins for its parent container.
+div.listingblock {
+  @include scroll-and-spacing("div.content", "div.content > pre");
+
+  margin-top: 0;
+  margin-bottom: $sp-3;
+}
+
 // {% highlight LANG %}...{% endhighlight %},
 // {% highlight LANG linenos %}...{% endhighlight %}:
 

_sass/layout.scss

@@ -29,9 +29,13 @@
   }
 
   @include mq(lg) {
-    margin-left: calc(
-      (100% - #{$nav-width + $content-width}) / 2 + #{$nav-width}
+    // stylelint-disable function-name-case
+    // disable for Max(), we want to use the CSS max() function
+    margin-left: Max(
+      #{$nav-width},
+      calc((100% - #{$nav-width + $content-width}) / 2 + #{$nav-width})
     );
+    // stylelint-enable function-name-case
   }
 }
 

_sass/vendor/OneDarkJekyll/README.md

@@ -1,25 +0,0 @@
-# OneDarkJekyll
-
-*Use Atom's One Dark syntax colors in your Jekyll powered blog!*
-
-It's LESS file which can be compiled to a - Pygments, Rouge compatible - stylesheet from Atom editor's One Dark syntax theme (and any theme based on it, for example One Dark Vivid, Firewatch, etc.).
-
-Download the stylesheet files or compile a new one from any Atom syntax theme which based on One Dark (the variable names in `colors.less` must match with One Dark's)
-
-## Create a new syntax stylesheet
-
-1. `npm install -g less less-plugin-clean-css`
-2. Clone this repository
-3. Download the `colors.css` file from the syntax theme's repository (for example https://github.com/atom/one-dark-syntax/blob/master/styles/colors.less in case of One-Dark)
-4. Put the previously downloaded file next to `syntax.less`
-5. Run `lessc syntax.less syntax.css --clean-css`
-6. Use the `syntax.css`
-
-It's not final and in case you find any error/improvement feel free to create a PR. :)
-
-----
-
-# UPDATES FOR USE IN JUST-THE-DOCS:
-
-1. Layout added in `*.css`
-2. Renamed `*.css` to `*.scss`

_sass/vendor/OneDarkJekyll/colors.less

@@ -1,30 +0,0 @@
-// Config -----------------------------------
-@syntax-hue:          220;
-@syntax-saturation:   13%;
-@syntax-brightness:   18%;
-
-
-// Monochrome -----------------------------------
-@mono-1: hsl(@syntax-hue, 14%, 71%); // default text
-@mono-2: hsl(@syntax-hue,  9%, 55%);
-@mono-3: hsl(@syntax-hue, 10%, 40%);
-
-// Colors -----------------------------------
-@hue-1:   hsl(187, 47%, 55%); // <-cyan
-@hue-2:   hsl(207, 82%, 66%); // <-blue
-@hue-3:   hsl(286, 60%, 67%); // <-purple
-@hue-4:   hsl( 95, 38%, 62%); // <-green
-
-@hue-5:   hsl(355, 65%, 65%); // <-red 1
-@hue-5-2: hsl(  5, 48%, 51%); // <-red 2
-
-@hue-6:   hsl( 29, 54%, 61%); // <-orange 1
-@hue-6-2: hsl( 39, 67%, 69%); // <-orange 2
-
-
-// Base colors -----------------------------------
-@syntax-fg:     @mono-1;
-@syntax-bg:     hsl(@syntax-hue, @syntax-saturation, @syntax-brightness);
-@syntax-gutter: darken(@syntax-fg, 26%);
-@syntax-guide:  fade(@syntax-fg, 15%);
-@syntax-accent: hsl(@syntax-hue, 100%, 66% );

_sass/vendor/OneDarkJekyll/syntax-variables.less

@@ -1,56 +0,0 @@
-@import "colors.less";
-
-// Official Syntax Variables -----------------------------------
-
-// General colors
-@syntax-text-color:            @syntax-fg;
-@syntax-cursor-color:          @syntax-accent;
-@syntax-selection-color:       lighten(@syntax-background-color, 10%);
-@syntax-selection-flash-color: @syntax-accent;
-@syntax-background-color:      @syntax-bg;
-
-// Guide colors
-@syntax-wrap-guide-color:          @syntax-guide;
-@syntax-indent-guide-color:        @syntax-guide;
-@syntax-invisible-character-color: @syntax-guide;
-
-// For find and replace markers
-@syntax-result-marker-color:          fade(@syntax-accent, 24%);
-@syntax-result-marker-color-selected: @syntax-accent;
-
-// Gutter colors
-@syntax-gutter-text-color:                @syntax-gutter;
-@syntax-gutter-text-color-selected:       @syntax-fg;
-@syntax-gutter-background-color:          @syntax-bg; // unused
-@syntax-gutter-background-color-selected: lighten(@syntax-bg, 2%);
-
-// Git colors - For git diff info. i.e. in the gutter
-@syntax-color-renamed:  hsl(208, 100%, 60%);
-@syntax-color-added:    hsl(150,  60%, 54%);
-@syntax-color-modified: hsl(40,   60%, 70%);
-@syntax-color-removed:  hsl(0,    70%, 60%);
-
-// For language entity colors
-@syntax-color-variable:   @hue-5;
-@syntax-color-constant:   @hue-6;
-@syntax-color-property:   @syntax-fg;
-@syntax-color-value:      @syntax-fg;
-@syntax-color-function:   @hue-2;
-@syntax-color-method:     @hue-2;
-@syntax-color-class:      @hue-6-2;
-@syntax-color-keyword:    @hue-3;
-@syntax-color-tag:        @hue-5;
-@syntax-color-attribute:  @hue-6;
-@syntax-color-import:     @hue-3;
-@syntax-color-snippet:    @hue-4;
-
-
-// Custom Syntax Variables -----------------------------------
-// Don't use in packages
-
-@syntax-cursor-line: hsla(@syntax-hue, 100%,  80%, .04); // needs to be semi-transparent to show search results
-
-@syntax-deprecated-fg: darken(@syntax-color-modified, 50%);
-@syntax-deprecated-bg: @syntax-color-modified;
-@syntax-illegal-fg:    white;
-@syntax-illegal-bg:    @syntax-color-removed;

_sass/vendor/OneDarkJekyll/syntax.less

@@ -1,93 +0,0 @@
-/*
-  LESS for Pygments
-*/
-
-@import "syntax-variables.less";
-
-pre.highlight,
-.highlight {
-  background: @syntax-bg;
-	color: @mono-1;
-}
-.highlight {
- pre { background: @syntax-bg; }
- .hll { background: @syntax-bg; }
- .c {  color: @mono-3; font-style: italic;  } /* Comment */
- .err { color: @syntax-illegal-fg; background-color: @syntax-illegal-bg; } /* Error */
- .k { color: @hue-3;  } /* Keyword */
- .l { color: @hue-4; } /* Literal */
- .n { color: @mono-1; } /* Name */
- .o { color: @mono-1; } /* Operator */
- .p { color: @mono-1; } /* Punctuation */
- .cm { color: @mono-3; font-style: italic; } /* Comment.Multiline */
- .cp { color: @mono-3; font-style: italic; } /* Comment.Preproc */
- .c1 { color: @mono-3; font-style: italic; } /* Comment.Single */
- .cs { color: @mono-3; font-style: italic; } /* Comment.Special */
- .ge { font-style: italic } /* Generic.Emph */
- .gs { font-weight: bold } /* Generic.Strong */
- .kc { color: @hue-3;  } /* Keyword.Constant */
- .kd { color: @hue-3;  } /* Keyword.Declaration */
- .kn { color: @hue-3;  } /* Keyword.Namespace */
- .kp { color: @hue-3;  } /* Keyword.Pseudo */
- .kr { color: @hue-3;  } /* Keyword.Reserved */
- .kt { color: @hue-3;  } /* Keyword.Type */
- .ld { color: @hue-4; } /* Literal.Date */
- .m { color: @hue-6; } /* Literal.Number */
- .s { color: @hue-4; } /* Literal.String */
- .na { color: @hue-6; } /* Name.Attribute */
- .nb { color: @hue-6-2; } /* Name.Builtin */
- .nc { color: @hue-6-2; } /* Name.Class */
- .no { color: @hue-6-2; } /* Name.Constant */
- .nd { color: @hue-6-2; } /* Name.Decorator */
- .ni { color: @hue-6-2; } /* Name.Entity */
- .ne { color: @hue-6-2; } /* Name.Exception */
- .nf { color: @mono-1; } /* Name.Function */
- .nl { color: @hue-6-2; } /* Name.Label */
- .nn { color: @mono-1; } /* Name.Namespace */
- .nx { color: @mono-1; } /* Name.Other */
- .py { color: @hue-6-2; } /* Name.Property */
- .nt { color: @hue-5; } /* Name.Tag */
- .nv { color: @hue-6-2; } /* Name.Variable */
- .ow { font-weight: bold; } /* Operator.Word */
- .w { color: #f8f8f2 } /* Text.Whitespace */
- .mf { color: @hue-6; } /* Literal.Number.Float */
- .mh { color: @hue-6; } /* Literal.Number.Hex */
- .mi { color: @hue-6; } /* Literal.Number.Integer */
- .mo { color: @hue-6; } /* Literal.Number.Oct */
- .sb { color: @hue-4; } /* Literal.String.Backtick */
- .sc { color: @hue-4; } /* Literal.String.Char */
- .sd { color: @hue-4; } /* Literal.String.Doc */
- .s2 { color: @hue-4; } /* Literal.String.Double */
- .se { color: @hue-4; } /* Literal.String.Escape */
- .sh { color: @hue-4; } /* Literal.String.Heredoc */
- .si { color: @hue-4; } /* Literal.String.Interpol */
- .sx { color: @hue-4; } /* Literal.String.Other */
- .sr { color: @hue-1; } /* Literal.String.Regex */
- .s1 { color: @hue-4; } /* Literal.String.Single */
- .ss { color: @hue-1; } /* Literal.String.Symbol */
- .bp { color: @hue-6-2; } /* Name.Builtin.Pseudo */
- .vc { color: @hue-6-2; } /* Name.Variable.Class */
- .vg { color: @hue-6-2; } /* Name.Variable.Global */
- .vi { color: @hue-5; } /* Name.Variable.Instance */
- .il { color: @hue-6; } /* Literal.Number.Integer.Long */
-
- .gh { } /* Generic Heading & Diff Header */
- .gu { color: #75715e; } /* Generic.Subheading & Diff Unified/Comment? */
- .gd { color: @syntax-color-removed; } /* Generic.Deleted & Diff Deleted */
- .gi { color: @syntax-color-added; } /* Generic.Inserted & Diff Inserted */
-	
- ::selection { background-color: @syntax-selection-color; }
-
- .language-json {
-   .w + .s2 { color: @hue-5; }
-   .kc { color: @hue-1; }
- }
-
- .language-python {
-   // python related modifications
- }
-
- .language-csharp {
-   // csharp related modifications
- }
-}

assets/js/just-the-docs.js

@@ -488,7 +488,7 @@ jtd.onReady(function(){
 
 jtd.onReady(function(){
 
-  var codeBlocks = document.querySelectorAll('div.highlighter-rouge, div.listingblock, figure.highlight');
+  var codeBlocks = document.querySelectorAll('div.highlighter-rouge, div.listingblock > div.content, figure.highlight');
 
   // note: the SVG svg-copied and svg-copy is only loaded as a Jekyll include if site.enable_copy_code_button is true; see _includes/icons/icons.html
   var svgCopied =  '<svg viewBox="0 0 24 24" class="copy-icon"><use xlink:href="#svg-copied"></use></svg>';

fixtures/Gemfile-github-pages

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem 'github-pages', group: :jekyll_plugins

fixtures/README.md

@@ -0,0 +1,3 @@
+# Test Fixtures
+
+These files are used by Just the Docs maintainers to test *the theme itself*. **If you are using Just the Docs as a theme, you should not copy these files over.**

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.4.0"
+  spec.version       = "0.4.1"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]
 
@@ -19,7 +19,7 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z ':!:*.jpg' ':!:*.png'`.split("\x0").select { |f| f.match(%r{^(assets|bin|_layouts|_includes|lib|Rakefile|_sass|LICENSE|README|CHANGELOG|favicon)}i) }
   spec.executables   << 'just-the-docs'
 
-  spec.add_development_dependency "bundler", "~> 2.3.5"
+  spec.add_development_dependency "bundler", ">= 2.3.5"
   spec.add_runtime_dependency "jekyll", ">= 3.8.5"
   spec.add_runtime_dependency "jekyll-seo-tag", ">= 2.0"
   spec.add_runtime_dependency "rake", ">= 12.3.1"

package-lock.json

@@ -9,7 +9,7 @@
       "version": "0.3.3",
       "license": "MIT",
       "devDependencies": {
-        "prettier": "^2.8.3",
+        "prettier": "^2.8.4",
         "stylelint": "^14.16.1",
         "stylelint-config-prettier-scss": "0.0.1",
         "stylelint-config-standard-scss": "^6.1.0",
@@ -1274,9 +1274,9 @@
       "dev": true
     },
     "node_modules/prettier": {
-      "version": "2.8.3",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.3.tgz",
-      "integrity": "sha512-tJ/oJ4amDihPoufT5sM0Z1SKEuKay8LfVAMlbbhnnkvt6BUserZylqo2PN+p9KeljLr0OHa2rXHU1T8reeoTrw==",
+      "version": "2.8.4",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.4.tgz",
+      "integrity": "sha512-vIS4Rlc2FNh0BySk3Wkd6xmwxB0FpOndW5fisM5H8hsZSxU2VWVB5CWIkIjWvrHjIhxk2g3bfMKM87zNTrZddw==",
       "dev": true,
       "bin": {
         "prettier": "bin-prettier.js"
@@ -2997,9 +2997,9 @@
       "dev": true
     },
     "prettier": {
-      "version": "2.8.3",
-      "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.3.tgz",
-      "integrity": "sha512-tJ/oJ4amDihPoufT5sM0Z1SKEuKay8LfVAMlbbhnnkvt6BUserZylqo2PN+p9KeljLr0OHa2rXHU1T8reeoTrw==",
+      "version": "2.8.4",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.4.tgz",
+      "integrity": "sha512-vIS4Rlc2FNh0BySk3Wkd6xmwxB0FpOndW5fisM5H8hsZSxU2VWVB5CWIkIjWvrHjIhxk2g3bfMKM87zNTrZddw==",
       "dev": true
     },
     "prettier-linter-helpers": {

package.json

@@ -6,7 +6,7 @@
   "license": "MIT",
   "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
   "devDependencies": {
-    "prettier": "^2.8.3",
+    "prettier": "^2.8.4",
     "stylelint": "^14.16.1",
     "stylelint-config-prettier-scss": "0.0.1",
     "stylelint-config-standard-scss": "^6.1.0",