Add tabindex=0 to all code blocks

Note: this is a bit hacky. Ideally, I'd like to do this at the
markdown level, since this doesn't serve folks who have
JS disabled (among many other things).

Also, curious to see how this interacts with custom highlighters;
needs some more testing!

.github/workflows/ci.yml

@@ -15,54 +15,54 @@ jobs:
       fail-fast: false
       matrix:
         jekyll-version: [3.9, 4.3]
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
-        ruby-version: ["3.1", "3.2", "3.3", "3.4"]
+        ruby-version: ["3.1", "3.2", "3.3"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
+    - uses: actions/checkout@v4
-      - name: Setup Ruby ${{ matrix.ruby-version }}
+    - name: Setup Ruby ${{ matrix.ruby-version }}
-        uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@v1
-        with:
+      with:
-          ruby-version: ${{ matrix.ruby-version }}
+        ruby-version: ${{ matrix.ruby-version }}
-          bundler-cache: false
+        bundler-cache: false
-      - name: Bundle Install (Jekyll ${{ matrix.jekyll-version }})
+    - name: Bundle Install (Jekyll ${{ matrix.jekyll-version }})
-        run: bundle install
+      run: bundle install
-        env:
+      env:
-          BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
+        BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
-      - name: Init Search
+    - name: Init Search
-        run: bundle exec rake search:init
+      run: bundle exec rake search:init
-        env:
+      env:
-          BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
+        BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
-      - name: Build Site
+    - name: Build Site
-        run: bundle exec jekyll build
+      run: bundle exec jekyll build
-        env:
+      env:
-          BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
+        BUNDLE_GEMFILE: fixtures/Gemfile-jekyll-${{ matrix.jekyll-version }}
 
   github-pages-build:
     name: Build (github-pages gem)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+    - uses: actions/checkout@v4
-      - name: Setup Ruby
+    - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
+      uses: ruby/setup-ruby@v1
-        with:
+      with:
-          ruby-version: "3.4"
+        ruby-version: "3.2"
-          bundler-cache: false
+        bundler-cache: false
-      - name: Bundle Install
+    - name: Bundle Install
-        run: bundle install
+      run: bundle install
-        env:
+      env:
-          BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
+        BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
-      - name: Build Site
+    - name: Build Site
-        run: bundle exec jekyll build
+      run: bundle exec jekyll build
-        env:
+      env:
-          BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
+        BUNDLE_GEMFILE: fixtures/Gemfile-github-pages
 
   validate:
     name: Validate HTML
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ["3.4"]
+        ruby-version: ["3.2"]
     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/,/flickr.com/"
+        run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/"
         env:
           NOKOGIRI_USE_SYSTEM_LIBRARIES: true
 
@@ -96,13 +96,13 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [22.x]
+        node-version: [18.x]
 
     steps:
-      - uses: actions/checkout@v4
+    - uses: actions/checkout@v4
-      - name: Use Node.js ${{ matrix.node-version }}
+    - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+      uses: actions/setup-node@v3
-        with:
+      with:
-          node-version: ${{ matrix.node-version }}
+        node-version: ${{ matrix.node-version }}
-      - run: npm install
+    - run: npm install
-      - run: npm test
+    - run: npm test

.github/workflows/deploy.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.4"
+          ruby-version: "3.3"
           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
@@ -47,9 +47,7 @@ jobs:
           JEKYLL_ENV: production
       - name: Upload artifact
         # Automatically uploads an artifact from the './_site' directory by default
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v2
-        with:
-          path: _site
 
   # Deployment job
   deploy:
@@ -61,4 +59,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v2

.github/workflows/publish-gem.yml

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

CHANGELOG.md

@@ -17,79 +17,18 @@ This website is built from the `HEAD` of the `main` branch of the theme reposito
 
 Code changes to `main` that are *not* in the latest release:
 
-- N/A
-
-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!
-
-This release should be a straightforward upgrade for all users of Just the Docs. Thank you for your continued support!
-
-### Using Release `v0.10.0`
-
-Users who have not pinned the theme version will be **automatically upgraded to `v0.9.0` 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.10.0
-```
-
-To use this version 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.10.0"
-```
-
-To use and pin a previous version of the theme, replace the `0.10.0` with the desired release tag.
-
 ### New Features
 
 - Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1431]
 
-### Documentation
+Docs changes made since the latest release:
 
 - Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1440]
 - Added: sitemap (via `jekyll-sitemap` plugin) by [@mattxwang] in [#1530]
-- Fixed: (non-systemic) accessibility issues flagged by aXe by [@mattxwang] in [#1531]
 
 [#1431]: https://github.com/just-the-docs/just-the-docs/pull/1431
 [#1440]: https://github.com/just-the-docs/just-the-docs/pull/1440
 [#1530]: https://github.com/just-the-docs/just-the-docs/pull/1530
-[#1530]: https://github.com/just-the-docs/just-the-docs/pull/1531
 
 ## Release v0.9.0
 

Dockerfile

@@ -0,0 +1,12 @@
+FROM ruby:2.7
+
+ENV LC_ALL C.UTF-8
+ENV LANG en_US.UTF-8
+ENV LANGUAGE en_US.UTF-8
+
+WORKDIR /usr/src/app
+
+COPY Gemfile just-the-docs.gemspec ./
+RUN gem install bundler && bundle install
+
+EXPOSE 4000

Gemfile

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

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    just-the-docs (0.10.1)
+    just-the-docs (0.9.0)
       jekyll (>= 3.8.5)
       jekyll-include-cache
       jekyll-seo-tag (>= 2.0)
@@ -10,25 +10,22 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    Ascii85 (2.0.1)
+    Ascii85 (1.1.0)
-    addressable (2.8.7)
+    addressable (2.8.6)
-      public_suffix (>= 2.0.2, < 7.0)
+      public_suffix (>= 2.0.2, < 6.0)
     afm (0.2.2)
-    async (2.23.0)
+    async (2.11.0)
-      console (~> 1.29)
+      console (~> 1.25, >= 1.25.2)
       fiber-annotation
-      io-event (~> 1.9)
+      io-event (~> 1.5, >= 1.5.1)
-      metrics (~> 0.12)
+      timers (~> 4.1)
-      traces (~> 0.15)
+    bigdecimal (3.1.8)
-    base64 (0.2.0)
-    bigdecimal (3.1.9)
     colorator (1.1.0)
-    concurrent-ruby (1.3.5)
+    concurrent-ruby (1.2.3)
-    console (1.29.3)
+    console (1.25.2)
       fiber-annotation
       fiber-local (~> 1.1)
       json
-    csv (3.3.3)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
       http_parser.rb (~> 0)
@@ -39,21 +36,18 @@ GEM
       faraday-net_http (>= 2.0, < 3.2)
     faraday-net_http (3.1.0)
       net-http
-    ffi (1.17.1-arm64-darwin)
+    ffi (1.16.3)
-    ffi (1.17.1-x86_64-linux-gnu)
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
       fiber-storage
-    fiber-storage (1.0.0)
+    fiber-storage (0.1.0)
     forwardable-extended (2.6.0)
-    google-protobuf (4.29.3-arm64-darwin)
+    google-protobuf (4.26.1-arm64-darwin)
-      bigdecimal
       rake (>= 13)
-    google-protobuf (4.29.3-x86_64-linux)
+    google-protobuf (4.26.1-x86_64-linux)
-      bigdecimal
       rake (>= 13)
     hashery (2.1.2)
-    html-proofer (5.0.10)
+    html-proofer (5.0.9)
       addressable (~> 2.3)
       async (~> 2.1)
       nokogiri (~> 1.13)
@@ -63,23 +57,20 @@ GEM
       yell (~> 2.0)
       zeitwerk (~> 2.5)
     http_parser.rb (0.8.0)
-    i18n (1.14.7)
+    i18n (1.14.4)
       concurrent-ruby (~> 1.0)
-    io-event (1.9.0)
+    io-event (1.5.1)
-    jekyll (4.4.1)
+    jekyll (4.3.3)
       addressable (~> 2.4)
-      base64 (~> 0.2)
       colorator (~> 1.0)
-      csv (~> 3.0)
       em-websocket (~> 0.5)
       i18n (~> 1.0)
       jekyll-sass-converter (>= 2.0, < 4.0)
       jekyll-watch (~> 2.0)
-      json (~> 2.6)
       kramdown (~> 2.3, >= 2.3.1)
       kramdown-parser-gfm (~> 1.0)
       liquid (~> 4.0)
-      mercenary (~> 0.3, >= 0.3.6)
+      mercenary (>= 0.3.6, < 0.5)
       pathutil (~> 0.9)
       rouge (>= 3.0, < 5.0)
       safe_yaml (~> 1.0)
@@ -98,9 +89,9 @@ GEM
       jekyll (>= 3.7, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    json (2.10.2)
+    json (2.7.2)
-    kramdown (2.5.1)
+    kramdown (2.4.0)
-      rexml (>= 3.3.9)
+      rexml
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liquid (4.0.4)
@@ -108,63 +99,62 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
-    metrics (0.12.1)
     net-http (0.4.1)
       uri
-    nokogiri (1.18.4-arm64-darwin)
+    nokogiri (1.16.5-arm64-darwin)
       racc (~> 1.4)
-    nokogiri (1.18.4-x86_64-linux-gnu)
+    nokogiri (1.16.5-x86_64-linux)
       racc (~> 1.4)
     octokit (6.1.1)
       faraday (>= 1, < 3)
       sawyer (~> 0.9)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    pdf-reader (2.14.1)
+    pdf-reader (2.12.0)
-      Ascii85 (>= 1.0, < 3.0, != 2.0.0)
+      Ascii85 (~> 1.0)
       afm (~> 0.2.1)
       hashery (~> 2.0)
       ruby-rc4
       ttfunk
-    public_suffix (6.0.1)
+    public_suffix (5.0.5)
-    racc (1.8.1)
+    racc (1.7.3)
     rainbow (3.1.1)
     rake (13.2.1)
     rb-fsevent (0.11.2)
-    rb-inotify (0.11.1)
+    rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rexml (3.4.0)
+    rexml (3.3.6)
-    rouge (4.5.1)
+      strscan
+    rouge (4.2.1)
     ruby-rc4 (0.1.5)
     safe_yaml (1.0.5)
-    sass-embedded (1.83.4-arm64-darwin)
+    sass-embedded (1.75.0-arm64-darwin)
-      google-protobuf (~> 4.29)
+      google-protobuf (>= 3.25, < 5.0)
-    sass-embedded (1.83.4-x86_64-linux-gnu)
+    sass-embedded (1.75.0-x86_64-linux-gnu)
-      google-protobuf (~> 4.29)
+      google-protobuf (>= 3.25, < 5.0)
     sawyer (0.9.2)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
+    strscan (3.1.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
-    traces (0.15.2)
+    timers (4.3.5)
     ttfunk (1.8.0)
       bigdecimal (~> 3.1)
     typhoeus (1.4.1)
       ethon (>= 0.9.0)
-    unicode-display_width (2.6.0)
+    unicode-display_width (2.5.0)
-    uri (0.13.2)
+    uri (0.13.0)
-    webrick (1.9.1)
+    webrick (1.8.1)
     yell (2.2.2)
-    zeitwerk (2.7.2)
+    zeitwerk (2.6.13)
 
 PLATFORMS
   arm64-darwin
   x86_64-linux-gnu
 
 DEPENDENCIES
-  base64
   bundler (>= 2.3.5)
-  csv
   html-proofer (~> 5.0)
   jekyll-github-metadata (>= 2.15)
   jekyll-include-cache

MIGRATION.md

@@ -43,18 +43,6 @@ This document contains instructions on how to migrate and upgrade Just the Docs
 
 [CHANGELOG]: {% link CHANGELOG.md %}
 
-## v0.9.x - v0.10.0
-
-There are no potentially-breaking changes in v0.10.0.
-
-## v0.8.x - v0.9.0
-
-There are no potentially-breaking changes in v0.9.0.
-
-## v0.7.x - v0.8.0
-
-There are no potentially-breaking changes in v0.8.0.
-
 ## v0.6.x - v0.7.0
 
 ### POTENTIALLY-BREAKING CHANGES in v0.7.0

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 as a Ruby Gem
+### Use RubyGems
 
 Alternatively, you can install the theme as a Ruby Gem, without creating a new site.
 
@@ -48,11 +48,17 @@ And add this line to your Jekyll site's `_config.yml`:
 theme: just-the-docs
 ```
 
-And then install all relevant dependencies:
+And then execute:
 
-```shell
+    $ bundle
-$ 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
 
 ## Usage
 

_includes/components/breadcrumbs.html

@@ -11,14 +11,14 @@
 
 {%- if page.url != "/" and page.parent and page.title -%}
 
-{%- 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 site_nav -%}
+{%- include_cached components/site_nav.html all=true -%}
+{%- endcapture -%}
+
 {%- capture nav_list_simple -%}
 <ul class="nav-list">
 {%- endcapture -%}

_includes/components/children_nav.html

@@ -11,24 +11,23 @@
 {%- 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. (The site_nav is rendered the first time
+  otherwise nav_children is left unset.
-  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 -%}

_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 or site.back_to_top %}
+{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %}
   <hr>
   <footer>
     {% if site.back_to_top %}

_includes/css/activation.scss.liquid

@@ -20,10 +20,6 @@
   - 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;
@@ -43,6 +39,10 @@
 <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 -%}

assets/js/just-the-docs.js

@@ -566,8 +566,17 @@ jtd.onReady(function(){
   {%- endif %}
 });
 
-// Copy button on code
+// Accessibility: set tabindex=0 on each code highlight block, so screenreaders
+// can focus over (particularly important if there's horizontal scroll)
+// see: https://dequeuniversity.com/rules/axe/4.9/scrollable-region-focusable?application=axeAPI
 
+jtd.onReady(() => {
+  document
+    .querySelectorAll("div.highlight")
+    .forEach(codeBlock => codeBlock.setAttribute("tabindex", "0"));
+});
+
+// Copy button on code
 
 {%- if site.enable_copy_code_button != false %}
 

docker-compose.yml

@@ -0,0 +1,14 @@
+version: "3.5"
+
+services:
+  jekyll:
+    build:
+      context: ./
+    ports:
+      - 4000:4000
+    volumes:
+      - .:/usr/src/app
+    stdin_open: true
+    tty: true
+    command: bundle exec jekyll serve -H 0.0.0.0 -t
+

docs/customization.md

@@ -20,8 +20,8 @@ Just the Docs supports two color schemes: light (default), and dark.
 
 To enable a color scheme, set the `color_scheme` parameter in your site's `_config.yml` file:
 
-### Example: preview dark color scheme
+#### Example
-{: .no_toc .text-delta }
+{: .no_toc }
 
 ```yaml
 # Color scheme supports "light" (default) and "dark"
@@ -76,8 +76,8 @@ Available variables are listed in the [\_variables.scss](https://github.com/just
 
 For example, to change the link color from the purple default to blue, include the following inside your scheme file:
 
-#### Example: custom link color
+#### Example
-{: .no_toc .text-delta }
+{: .no_toc }
 
 ```scss
 $link-color: $blue-000;
@@ -142,11 +142,11 @@ Additionally, you may want to add completely custom CSS specific to your content
 To do this, put your styles in the file `_sass/custom/custom.scss`.
 This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied.
 
-### Example: custom print styles
-{: .no_toc .text-delta }
-
 For example, if you'd like to add your own styles for printing a page, you could add the following styles.
 
+#### Example
+{: .no_toc }
+
 ```scss
 // Print-only styles.
 @media print {
@@ -179,7 +179,7 @@ New (v0.4.0)
 
 If the page has any child pages, and `has_toc` is not set to `false`, this content appears as a heading above the [auto-generating list of child pages]({% link docs/navigation/children.md %}) after the page's content.
 
-#### Example: changing TOC heading
+#### Example
 {: .no_toc }
 
 To change the default TOC heading to "Contents", create `_includes/toc_heading_custom.html` and add:

docs/index-test.md

@@ -27,17 +27,17 @@ There should be whitespace between paragraphs.
 
 There should be whitespace between paragraphs. We recommend including a README, or a file with information about your project.
 
-# Header 1
+# [](#header-1)Header 1
 
 This is a normal paragraph following a header. GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere.
 
-## Header 2
+## [](#header-2)Header 2
 
 > This is a blockquote following a header.
 >
 > When something is important enough, you do it even if the odds are not in your favor.
 
-### Header 3
+### [](#header-3)Header 3
 
 ```js
 // Javascript code with syntax highlighting.
@@ -54,19 +54,19 @@ GitHubPages::Dependencies.gems.each do |gem, version|
 end
 ```
 
-#### Header 4 `with code not transformed`
+#### [](#header-4-with-code-not-transformed)Header 4 `with code not transformed`
 
 *   This is an unordered list following a header.
 *   This is an unordered list following a header.
 *   This is an unordered list following a header.
 
-##### Header 5
+##### [](#header-5)Header 5
 
 1.  This is an ordered list following a header.
 2.  This is an ordered list following a header.
 3.  This is an ordered list following a header.
 
-###### Header 6
+###### [](#header-6)Header 6
 
 [This is a very long link which wraps and therefore doesn't overflow
 even when it comes at the beginning](.) of the line.
@@ -303,8 +303,6 @@ The following code is displayed as a diagram only when a `mermaid` key supplied
 
 ```mermaid
 graph TD;
-    accTitle: the diamond pattern
-    accDescr: a graph with four nodes: A points to B and C, while B and C both point to D
     A-->B;
     A-->C;
     B-->D;

docs/layout/minimal/default-child.md

@@ -5,6 +5,4 @@ parent: A minimal layout page
 grand_parent: Layout
 ---
 
-# 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).

docs/layout/minimal/minimal-child.md

@@ -5,6 +5,4 @@ parent: A minimal layout page
 grand_parent: Layout
 ---
 
-# Minimal layout child page
-
 This is a child page that uses the same minimal layout as its parent page.

docs/minimal-test.md

@@ -4,8 +4,6 @@ title: Minimal layout test
 nav_exclude: true
 ---
 
-# Minimal Layout Test Page
-
 [Return to main website]({{site.baseurl}}/).
 
 This page demonstrates the packaged `minimal` layout, which does not render the sidebar or header. It can be used for standalone pages. It is also an example of using the new modular site components to define custom layouts; see ["Custom layouts and includes" in the customization docs]({{site.baseurl}}/docs/customization/#custom-layouts-and-includes) for more information.

docs/navigation/auxiliary.md

@@ -8,10 +8,7 @@ nav_order: 2
 
 You can add a list of auxiliary links to your site, shown at the top right on all pages. You do this by including the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
 
-## Example Auxiliary Link
+#### Example
-{: .text-delta }
-
-This website has an auxiliary link: "Just the Docs on GitHub". It is rendered with the following code:
 
 ```yaml
 aux_links:

docs/navigation/children.md

@@ -10,8 +10,7 @@ By default, all parent pages will automatically have a so-called 'Table of Conte
 
 To disable this automatic list, set `has_toc: false` in the parent page's front matter.
 
-## Example: disabling table of contents
+#### Example
-{: .text-delta }
 
 ```yaml
 ---

docs/navigation/in-page.md

@@ -15,35 +15,15 @@ nav_order: 5
 
 To support in-page navigation, you can generate a *Table of Contents* (TOC) with links to headings, like the one shown above, as well as a link to the top of the page.
 
-## Generating Table of Contents
+## Table of Contents
 
 To generate a *Table of Contents* in a page, you use Kramdown's `{:toc}` method, immediately after the start of a list. This will automatically generate a list of anchor links to various sections of the page, based on headings and heading levels.
 
-{: .note }
-`{:toc}` can be used only once on each page.
-
-You **must** have a list immediately preceding the table of contents. The type of list determines the style of your table of contents.
-
-For an *ordered* table of contents, use the following markdown code:
-
-```md
-1. TOC
-{:toc}
-```
-
-The `{:toc}` line *must* follow the `1. TOC` line, which begins a list.
-
-For an *unordered* table of contents, instead use the following markdown code:
-
-```
-- TOC
-{:toc}
-```
-
-## Omitting Heading from Table of Contents
-
 If you want to omit a particular heading from the TOC, follow it immediately by `{: .no_toc }` (possibly together with other CSS class names).
 
+#### Example 
+{: .no_toc }
+
 ```markdown
 # In-Page Navigation
 {: .no_toc }
@@ -57,10 +37,15 @@ If you want to omit a particular heading from the TOC, follow it immediately by
 
 This example omits the top-level heading (`In-Page Navigation`) from the TOC, as well as the heading for the *Table of Contents* itself.
 
-## Collapsible Table of Contents (with `<details>` and `<summary>`)
+To get an unordered list, replace `1. TOC` by `- TOC` in the above example.
+
+## Collapsible Table of Contents
 
 You can make the Table of Contents collapsible using the `<details>` and `<summary>` elements, as in the following example.
 
+#### Example
+{: .no_toc }
+
 ```markdown
 <details open markdown="block">
   <summary>
@@ -74,6 +59,9 @@ You can make the Table of Contents collapsible using the `<details>` and `<summa
 
 The attribute `open` (which expands the Table of Contents by default) and the styling (here with `text-delta`) are optional.
 
+{: .note }
+`{:toc}` can be used only once on each page.
+
 ## Back to Top {#back-to-top-doc}
 
 {: .warning }

docs/navigation/main/ancestry.md

@@ -10,8 +10,7 @@ If no two pages on your website have the same `title`, you only need to set the
 
 If two parents have the same `title`, but different grandparents, you can set their `grand_parent` titles to distinguish between their parents. The `grand_parent` title needs to be the same as the `parent` of the `parent`.
 
-## Example: distinguishing parents with `grand_parent`
+#### Example
-{: .text-delta }
 
 ```yaml
 ---

docs/navigation/main/collections.md

@@ -14,8 +14,7 @@ However, you can configure Just the Docs to include also pages from [Jekyll coll
 
 [^1]: You can optionally specify a directory to store all your collections. For example, if you specify `collections_dir: my_collections` in `_config.yml`, you should then store the pages of the `tests` collection in the `my_collections/_tests` directory.
 
-## Example: defining custom collections
+#### Example
-{: .text-delta }
 
 To define a Jekyll `tests` collection named `Tests` in your main navigation, store its pages in the `_tests` directory, and add the following to `_config.yml`:
 
@@ -42,11 +41,10 @@ Together with the `name` to be used for a collection in the navigation, you can
 
 The main navigation for all your normal pages (if any) is displayed before those in collections. When *all* your pages are in a single collection, its name is not displayed.
 
-## Example: multiple collections
-{: .text-delta }
-
 You can configure multiple collections. This creates categories in the main navigation with the configured names.
 
+#### Example
+
 ```yaml
 collections:
   tests:

docs/navigation/main/exclude.md

@@ -8,8 +8,7 @@ nav_order: 2
 
 For specific pages that you do not wish to include in the main navigation (e.g., a 404 page or a landing page) set `nav_exclude: true` in their front matter.
 
-## Example: using `nav_exclude`
+#### Example
-{: .text-delta }
 
 ```yaml
 ---

docs/navigation/main/external.md

@@ -9,8 +9,7 @@ nav_order: 6
 To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file.
 External links will appear in the navigation after the links to ordinary pages, but before any collections.
 
-## Example: external links
+#### Example
-{: .text-delta }
 
 ```yaml
 # External navigation links

docs/navigation/main/index.md

@@ -13,7 +13,7 @@ You need to specify the `title` of each page in its front matter. Page titles ar
 By default, links to all pages appear in the main navigation at the top level, ordered alphabetically by their titles. By adding further fields to the front matter of individual pages, you can [change their order]({% link docs/navigation/main/order.md %}), [exclude pages]({% link docs/navigation/main/exclude.md %}), and change their [parent pages]({% link docs/navigation/main/levels.md %}).
 
 {: .new-title }
-> New (v0.10.0)
+> New (Multi-level)
 >
 > The main navigation can be structured as a multi-level menu of unlimited depth:
 > pages can always have child pages.
@@ -25,7 +25,7 @@ For the construction of the navigation display to work (and to avoid potential c
 * The title of each page must be different from the titles of all its child pages, and from the titles of their child pages, etc.
 
 {: .new-title }
-> New (v0.10.0)
+> New (Multi-level)
 >
 > If *all* the pages of your site have different titles, you need only to specify the `title` of each page, and the `parent` title of each lower-level page.[^1]
 
@@ -34,7 +34,7 @@ For the construction of the navigation display to work (and to avoid potential c
 If your site has pages with the same title, you need to avoid confusion when you reference that title as `parent` on other pages. When the pages with the same title have different `parent` pages, you can distinguish between them using the `grand_parent` parameter. 
 
 {: .new-title }
-> New (v0.10.0)
+> New (Multi-level)
 >
 > For deeper navigation structures, you can specify the title of a grandparent or higher level page as an `ancestor` title.
 

docs/navigation/main/levels.md

@@ -31,8 +31,7 @@ Sometimes you will want to create a page with many children. First, it is recomm
 └─ ...
 ```
 
-## Example: page with no parents
+#### Example
-{: .text-delta }
 
 ```yaml
 ---
@@ -49,8 +48,7 @@ The navigation links for all pages with children come with an expander. When you
 
 On child pages, simply set the `parent` front matter to the parent page's `title`, and set a navigation order (relative to pages having the same parent).
 
-### Example: creating a child page
+#### Example
-{: .text-delta }
 
 ```yaml
 ---
@@ -63,7 +61,7 @@ nav_order: 2
 The Buttons page appears as a child of UI Components and appears second in the UI Components pages.
 
 {: .new-title }
-> New (v0.10.0)
+> New (Multi-level)
 >
 > The `has_children` field is now redundant (and ignored, except when significant for backwards compatibility).
 
@@ -71,8 +69,7 @@ The Buttons page appears as a child of UI Components and appears second in the U
 
 Child pages can themselves have children, to any number of levels. 
 
-### Example: pages with (recursive) children
+#### Example
-{: .text-delta }
 
 ```yaml
 ---

docs/navigation/main/order.md

@@ -8,8 +8,7 @@ nav_order: 1
 
 To specify a page order, you can use the `nav_order` parameter in the front matter of the pages.
 
-## Example: using `nav_order`
+#### Example
-{: .text-delta }
 
 ```yaml
 ---

docs/search.md

@@ -113,6 +113,8 @@ Will make <kbd>Ctrl</kbd> + <kbd>K</kbd> focus the search bar for Windows users
 Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g., a 404 page.
 To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
 
+#### Example
+
 {: .no_toc }
 
 ```yaml
@@ -156,8 +158,7 @@ By default, the search feature indexes a page's `.content`, `.title`, and *some*
 2. Add a new file named `_includes/lunr/custom-data.json`. Insert custom Liquid code that reads your data (e.g. the page object at `include.page`) then generates custom Javascript fields that hold the custom data you want to index. Verify these fields in the generated `assets/js/search-data.json`.
 3. Add a new file named `_includes/lunr/custom-index.js`. Insert custom Javascript code that reads your custom Javascript fields and inserts them into the search index. You may want to inspect `assets/js/just-the-docs.js` to better understand the code.
 
-### Example: adding custom `usage` and `examples` fields
+#### Example
-{: .text-delta }
 
 This example adds front matter `usage` and `examples` fields to the search index.
 

docs/ui-components/callouts.md

@@ -22,8 +22,8 @@ When you have [configured]({% link docs/configuration.md %}#callouts) the  `colo
 [^postfix]:
     You can put the callout markup either before or after its content.
 
-## An untitled callout
+#### An untitled callout
-{: .no_toc .text-delta }
+{: .no_toc }
 
 ```markdown
 {: .highlight }
@@ -34,8 +34,8 @@ A paragraph
 A paragraph
 
 
-## A single paragraph callout
+#### A single paragraph callout
-{: .no_toc .text-delta }
+{: .no_toc }
 
 ```markdown
 {: .note }
@@ -57,8 +57,8 @@ A paragraph
 >
 > A paragraph with a custom title callout
 
-## A multi-paragraph callout
+#### A multi-paragraph callout
-{: .no_toc .text-delta }
+{: .no_toc }
 
 ```markdown
 {: .important }
@@ -96,8 +96,8 @@ A paragraph
 >
 > The last paragraph
 
-## An indented callout
+#### An indented callout
-{: .no_toc .text-delta }
+{: .no_toc }
 
 ```markdown
 > {: .highlight }
@@ -107,8 +107,8 @@ A paragraph
 > {: .highlight }
   A paragraph
 
-## Indented multi-paragraph callouts
+#### Indented multi-paragraph callouts
-{: .no_toc .text-delta }
+{: .no_toc }
 
 ```markdown
 > {: .new }
@@ -127,8 +127,8 @@ A paragraph
 > > The last paragraph
 
 
-## Nested callouts
+#### Nested callouts
-{: .no_toc .text-delta }
+{: .no_toc }
 
 ```markdown
 {: .important }
@@ -140,8 +140,8 @@ A paragraph
 > {: .warning }
 > A paragraph
 
-## Opaque background
+#### Opaque background
-{: .no_toc .text-delta }
+{: .no_toc }
 
 ```markdown
 {: .important }

docs/ui-components/code/index.md

@@ -129,8 +129,6 @@ Once mermaid is installed, it can be used in markdown files. The markdown for a
 {% highlight markdown %}
 ```mermaid
 graph TD;
-    accTitle: the diamond pattern
-    accDescr: a graph with four nodes: A points to B and C, while B and C both point to D
     A-->B;
     A-->C;
     B-->D;
@@ -142,8 +140,6 @@ which renders:
 
 ```mermaid
 graph TD;
-    accTitle: the diamond pattern
-    accDescr: a graph with four nodes: A points to B and C, while B and C both point to D
     A-->B;
     A-->C;
     B-->D;
@@ -181,8 +177,6 @@ By default, AsciiDoc generates HTML markup that mermaid cannot properly parse. T
 ++++
 <pre class="language-mermaid">
 graph TD;
-    accTitle: the diamond pattern
-    accDescr: a graph with four nodes: A points to B and C, while B and C both point to D
     A-->B;
     A-->C;
     B-->D;

docs/utilities/layout.md

@@ -18,7 +18,7 @@ parent: Utilities
 
 These spacers are available to use for margins and padding with responsive utility classes. Combine these prefixes with a screen size and spacing scale to use them responsively.
 
-| Classname prefix | Related CSS Property          |
+| Classname prefix | What it does                  |
 |:-----------------|:------------------------------|
 | `.m-`            | `margin`                      |
 | `.mx-`           | `margin-left`, `margin-right` |
@@ -28,7 +28,7 @@ These spacers are available to use for margins and padding with responsive utili
 | `.mb-`           | `margin-bottom`               |
 | `.ml-`           | `margin-left`                 |
 
-| Classname prefix | Related CSS Property            |
+| Classname prefix | What it does                    |
 |:-----------------|:--------------------------------|
 | `.p-`            | `padding`                       |
 | `.px-`           | `padding-left`, `padding-right` |
@@ -54,8 +54,8 @@ Spacing values are based on a `1rem = 16px` spacing scale, broken down into thes
 
 Use `mx-auto` to horizontally center elements.
 
-### Applying Spacing Utilities with `{: }`
+#### Examples
-{: .no_toc .text-delta }
+{: .no_toc }
 
 In Markdown, use the `{: }` wrapper to apply custom classes:
 
@@ -69,7 +69,7 @@ This paragraph will have 2rem/32px of padding on the right and left at all scree
 
 ## Horizontal Alignment
 
-| CSS Class               | Applied CSS Declaration          |
+| Classname               | What it does                     |
 |:------------------------|:---------------------------------|
 | `.float-left`           | `float: left`                    |
 | `.float-right`          | `float: right`                   |
@@ -82,7 +82,7 @@ _Note: any of the `flex-` classes must be used on a parent element that has `d-f
 
 ## Vertical Alignment
 
-| CSS Class              | Applied CSS Declaration         |
+| Classname              | What it does                    |
 |:-----------------------|:--------------------------------|
 | `.v-align-baseline`    | `vertical-align: baseline`      |
 | `.v-align-bottom`      | `vertical-align: bottom`        |
@@ -95,7 +95,7 @@ _Note: any of the `flex-` classes must be used on a parent element that has `d-f
 
 Display classes aid in adapting the layout of the elements on a page:
 
-| CSS Class         | Applied CSS Declaration |
+| Class             |                         |
 |:------------------|:------------------------|
 | `.d-block`        | `display: block`        |
 | `.d-flex`         | `display: flex`         |
@@ -105,8 +105,8 @@ Display classes aid in adapting the layout of the elements on a page:
 
 Use these classes in conjunction with the responsive modifiers.
 
-### Applying Display Utilities with `{: }`
+#### Examples
-{: .no_toc .text-delta }
+{: .no_toc }
 
 In Markdown, use the `{: }` wrapper to apply custom classes:
 

fixtures/Gemfile-jekyll-3.9

@@ -2,10 +2,6 @@ source "https://rubygems.org"
 
 gem "jekyll", "~> 3.9"
 
-gem "base64"
-gem "bigdecimal"
-gem "csv"
-
 gem "jekyll-seo-tag", ">= 2.0"
 gem "rake", ">= 12.3.1"
 

fixtures/Gemfile-jekyll-4.3

@@ -2,9 +2,6 @@ source "https://rubygems.org"
 
 gem "jekyll", "~> 4.3"
 
-gem "base64"
-gem "csv"
-
 gem "jekyll-seo-tag", ">= 2.0"
 gem "rake", ">= 12.3.1"
 

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.10.1"
+  spec.version       = "0.9.0"
   spec.authors       = ["Patrick Marsceill", "Matthew Wang"]
   spec.email         = ["patrick.marsceill@gmail.com", "matt@matthewwang.me"]
 

package.json

@@ -7,9 +7,9 @@
   "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
   "devDependencies": {
     "npm-run-all": "^4.1.5",
-    "prettier": "^3.5.3",
+    "prettier": "^3.3.3",
-    "stylelint": "^16.16.0",
+    "stylelint": "^16.9.0",
-    "stylelint-config-standard-scss": "^14.0.0"
+    "stylelint-config-standard-scss": "^13.1.0"
   },
   "scripts": {
     "lint": "npm-run-all --parallel --continue-on-error lint:*",