Merge branch 'just-the-docs:main' into main

acm-uiuc · Jan 21, 2025 · b402ce7 · b402ce7
2 parents 9b07956 + 883d7e5
commit b402ce7
Show file tree

Hide file tree

Showing 20 changed files with 571 additions and 421 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -16,7 +16,7 @@ jobs:
       matrix:
         jekyll-version: [3.9, 4.3]
         os: [ubuntu-latest, macos-latest, windows-latest]
-        ruby-version: ["3.1", "3.2", "3.3"]
+        ruby-version: ["3.1", "3.2", "3.3", "3.4"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
@@ -46,7 +46,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.3"
+          ruby-version: "3.4"
           bundler-cache: false
       - name: Bundle Install
         run: bundle install
@@ -62,7 +62,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ["3.3"]
+        ruby-version: ["3.4"]
     runs-on: ubuntu-latest
 
     steps:
@@ -86,7 +86,7 @@ jobs:
         with:
           config: fixtures/html5validator-config.yml
       - name: Test with html-proofer
-        run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/"
+        run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/,/flickr.com/"
         env:
           NOKOGIRI_USE_SYSTEM_LIBRARIES: true
 
@@ -96,7 +96,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [20.x]
+        node-version: [22.x]
 
     steps:
       - uses: actions/checkout@v4

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -34,7 +34,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.3"
+          ruby-version: "3.4"
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Setup Pages

diff --git a/.github/workflows/publish-gem.yml b/.github/workflows/publish-gem.yml
@@ -1,31 +1,30 @@
 name: Publish Ruby Gem
 
-on:
-  workflow_dispatch
+on: workflow_dispatch
 
 jobs:
   build:
     name: Publish
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Setup Ruby 3.3
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: "3.3"
+      - uses: actions/checkout@v4
+      - name: Setup Ruby 3.4
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
 
-    - name: Publish to GPR
-      run: |
-        mkdir -p $HOME/.gem
-        touch $HOME/.gem/credentials
-        chmod 0600 $HOME/.gem/credentials
-        printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
-        gem build *.gemspec
-        gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
-      env:
-        GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
-        OWNER: ${{ github.repository_owner }}
+      - name: Publish to GPR
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:github: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+          gem build *.gemspec
+          gem push --KEY github --host https://rubygems.pkg.github.com/${OWNER} *.gem
+        env:
+          GEM_HOST_API_KEY: "Bearer ${{secrets.GITHUB_TOKEN}}"
+          OWNER: ${{ github.repository_owner }}
 
     # Disabled as this does not handle 2FA
     # - name: Publish to RubyGems

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -23,6 +23,35 @@ Docs changes made since the latest release:
 
 - N/A
 
+## Release v0.10.1
+
+Hi folks! This patch fixes two bugs related to generated navigation elements and improves our docs.
+
+This release should be a straightforward upgrade for all users of Just the Docs. Thank you for your continued support!
+
+### Bugfixes
+
+- Fixed: `back_to_top` not displaying when no other footer variables are set by [@mattxwang] in [#1461]
+- Fixed: auto-generated child navigation (TOC) by [@pdmosses] in [#1590]
+
+### Documentation
+
+- Fixed: incorrect docs for example with minimal layout parent, default layout child by [@janbrasna] in [#1540]
+- Fixed: unclear docs on using in-page table of contents by [@sebjameswml] in [#1551]
+
+### New Contributors
+
+- [@janbrasna] made their first contribution in [#1540]
+- [@sebjameswml] made their first contribution in [#1551]
+
+[@janbrasna]: https://github.com/janbrasna
+[@sebjameswml]: https://github.com/sebjameswml
+
+[#1461]: https://github.com/just-the-docs/just-the-docs/pull/1461
+[#1540]: https://github.com/just-the-docs/just-the-docs/pull/1540
+[#1551]: https://github.com/just-the-docs/just-the-docs/pull/1551
+[#1590]: https://github.com/just-the-docs/just-the-docs/pull/1590
+
 ## Release v0.10.0
 
 Hi folks! This minor release adds one of our most-requested features: unlimited multi-level navigation (also known as recursive navigation). Huge thanks to [@pdmosses] for his wonderful work in implementing this feature!

diff --git a/Dockerfile b/Dockerfile
diff --git a/Gemfile b/Gemfile
@@ -1,6 +1,9 @@
 source "https://rubygems.org"
 gemspec
 
+gem "base64"
+gem "csv"
+
 gem "jekyll-github-metadata", ">= 2.15"
 
 gem "jekyll-include-cache", group: :jekyll_plugins

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    just-the-docs (0.10.0)
+    just-the-docs (0.10.1)
       jekyll (>= 3.8.5)
       jekyll-include-cache
       jekyll-seo-tag (>= 2.0)
@@ -19,13 +19,15 @@ GEM
       fiber-annotation
       io-event (~> 1.5, >= 1.5.1)
       timers (~> 4.1)
+    base64 (0.2.0)
     bigdecimal (3.1.8)
     colorator (1.1.0)
     concurrent-ruby (1.3.4)
     console (1.25.2)
       fiber-annotation
       fiber-local (~> 1.1)
       json
+    csv (3.3.2)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
@@ -36,17 +38,17 @@ GEM
       faraday-net_http (>= 2.0, < 3.2)
     faraday-net_http (3.1.0)
       net-http
-    ffi (1.17.0-arm64-darwin)
-    ffi (1.17.0-x86_64-linux-gnu)
+    ffi (1.17.1-arm64-darwin)
+    ffi (1.17.1-x86_64-linux-gnu)
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
       fiber-storage
     fiber-storage (0.1.0)
     forwardable-extended (2.6.0)
-    google-protobuf (4.28.2-arm64-darwin)
+    google-protobuf (4.29.3-arm64-darwin)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.28.2-x86_64-linux)
+    google-protobuf (4.29.3-x86_64-linux)
       bigdecimal
       rake (>= 13)
     hashery (2.1.2)
@@ -104,9 +106,9 @@ GEM
     mercenary (0.4.0)
     net-http (0.4.1)
       uri
-    nokogiri (1.16.5-arm64-darwin)
+    nokogiri (1.18.1-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.16.5-x86_64-linux)
+    nokogiri (1.18.1-x86_64-linux-gnu)
       racc (~> 1.4)
     octokit (6.1.1)
       faraday (>= 1, < 3)
@@ -126,7 +128,7 @@ GEM
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rexml (3.3.7)
+    rexml (3.3.9)
     rouge (4.4.0)
     ruby-rc4 (0.1.5)
     safe_yaml (1.0.5)
@@ -146,7 +148,7 @@ GEM
       ethon (>= 0.9.0)
     unicode-display_width (2.6.0)
     uri (0.13.0)
-    webrick (1.8.1)
+    webrick (1.8.2)
     yell (2.2.2)
     zeitwerk (2.6.13)
 
@@ -155,7 +157,9 @@ PLATFORMS
   x86_64-linux-gnu
 
 DEPENDENCIES
+  base64
   bundler (>= 2.3.5)
+  csv
   html-proofer (~> 5.0)
   jekyll-github-metadata (>= 2.15)
   jekyll-include-cache

diff --git a/README.md b/README.md
@@ -32,7 +32,7 @@ More specifically, the created site:
 
 Other than that, you're free to customize sites that you create with the template, however you like. You can easily change the versions of `just-the-docs` and Jekyll it uses, as well as adding further plugins.
 
-### Use RubyGems
+### Use as a Ruby Gem
 
 Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
 
@@ -48,17 +48,11 @@ And add this line to your Jekyll site's `_config.yml`:
 theme: just-the-docs
 ```
 
-And then execute:
+And then install all relevant dependencies:
 
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install just-the-docs
-
-Alternatively, you can run it inside Docker while developing your site
-
-    $ docker-compose up
+```shell
+$ bundle
+```
 
 ## Usage
 

diff --git a/_includes/components/breadcrumbs.html b/_includes/components/breadcrumbs.html
@@ -11,14 +11,14 @@
 
 {%- if page.url != "/" and page.parent and page.title -%}
 
-{%- capture nav_list_link -%}
-<a href="{{ page.url | relative_url }}" class="nav-list-link">
-{%- endcapture -%}
-
 {%- capture site_nav -%}
 {%- include_cached components/site_nav.html all=true -%}
 {%- endcapture -%}
 
+{%- capture nav_list_link -%}
+<a href="{{ page.url | relative_url }}" class="nav-list-link">
+{%- endcapture -%}
+
 {%- capture nav_list_simple -%}
 <ul class="nav-list">
 {%- endcapture -%}

diff --git a/_includes/components/children_nav.html b/_includes/components/children_nav.html
@@ -11,23 +11,24 @@
 {%- comment -%}
   Whether a page has any children is checked efficiently by inspecting the cached
   site_nav. If the page has no children, nav_children is set to an empty array;
-  otherwise nav_children is left unset.
+  otherwise nav_children is left unset. (The site_nav is rendered the first time
+  it is included, and that may overwrite various variables.)
 {%- endcomment -%}
 
 {%- if page.has_children == false -%}
   {%- assign nav_children = "" | split: "" -%}
 {%- else -%}
 
+  {%- capture site_nav -%}
+  {%- include_cached components/site_nav.html all=true -%}
+  {%- endcapture -%}
+
   {%- assign nav_children = nil -%}
 
   {%- capture nav_list_link -%}
   <a href="{{ page.url | relative_url }}" class="nav-list-link">
   {%- endcapture -%}
 
-  {%- capture site_nav -%}
-  {%- include_cached components/site_nav.html all=true -%}
-  {%- endcapture -%}
-
   {%- capture nav_list_simple -%}
   <ul class="nav-list">
   {%- endcapture -%}

diff --git a/_includes/components/footer.html b/_includes/components/footer.html
@@ -1,7 +1,7 @@
 {% capture footer_custom %}
   {%- include footer_custom.html -%}
 {% endcapture %}
-{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %}
+{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link or site.back_to_top %}
   <hr>
   <footer>
     {% if site.back_to_top %}

diff --git a/_includes/css/activation.scss.liquid b/_includes/css/activation.scss.liquid
@@ -20,6 +20,10 @@
   - The other two rules ensure that all folding collections are expanded.
 {%- endcomment -%}
 
+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html -%}
+{%- endcapture -%}
+
 {%- capture activation_no_nav_link %}
     .site-nav ul li a {
       background-image: none;
@@ -39,10 +43,6 @@
 <a href="{{ page.url | relative_url }}" class="nav-list-link">
 {%- endcapture -%}
 
-{%- capture site_nav -%}
-{%- include_cached components/site_nav.html -%}
-{%- endcapture -%}
-
 {%- if site_nav contains nav_list_link -%}
 
   {%- capture nav_list -%}

diff --git a/docker-compose.yml b/docker-compose.yml
diff --git a/docs/layout/minimal/default-child.md b/docs/layout/minimal/default-child.md
@@ -5,6 +5,6 @@ parent: A minimal layout page
 grand_parent: Layout
 ---
 
-# A minimal layout page
+# Default layout child page
 
-This is a child page that uses the same minimal layout as its parent page.
+This is a child page that uses the `default` layout as compared to its parent page (which uses the `minimal` layout).