Version 0.7.0

PR for the issue flagged in https://github.com/just-the-docs/just-the-docs/discussions/1359#discussioncomment-7267686 (and related to #1358, #1350, etc.). This PR essentially just disables the `head-nav` stylesheet by ID instead of relying on the index; this makes the code more robust against stylesheets that are arbitrarily entered into the document (such as by JavaScript, which is the case of #1359).

.babelrc.json

@@ -1,15 +0,0 @@
-{
-  "sourceType": "unambiguous",
-  "presets": [
-    [
-      "@babel/preset-env",
-      {
-        "targets": {
-          "chrome": 100
-        }
-      }
-    ],
-    "@babel/preset-typescript"
-  ],
-  "plugins": []
-}

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: just-the-docs
+open_collective: just-the-docs

.github/workflows/chromatic.yml

@@ -1,51 +0,0 @@
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-
-name: 'Chromatic'
-
-jobs:
-  chromatic:
-    name: "Chromatic"
-    strategy:
-      matrix:
-        jekyll-version: [4.3]
-        os: [ ubuntu-latest ]
-        ruby-version: [3.1]
-        node-version: [18.x]
-    runs-on: ${{ matrix.os }}
-    steps:
-
-    # Ruby setup
-    - uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-    - name: Setup Ruby ${{ matrix.ruby-version }}
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby-version }}
-        bundler-cache: false
-    - name: Bundle Install
-      run: bundle install
-    - name: Install Jekyll ${{ matrix.jekyll-version }}
-      run: gem install jekyll -v ${{ matrix.jekyll-version }}
-    - name: Init Search
-      run: bundle exec rake search:init
-    - name: Build Site
-      run: bundle exec jekyll build
-
-    # Node setup
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
-      with:
-        node-version: ${{ matrix.node-version }}
-    - run: npm install
-    - run: npm run build-storybook
-    - name: Publish to Chromatic
-      uses: chromaui/action@v1
-      env:
-        CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

.github/workflows/ci.yml

@@ -19,7 +19,7 @@ jobs:
         ruby-version: ["3.0", "3.1", "3.2"]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup Ruby ${{ matrix.ruby-version }}
       uses: ruby/setup-ruby@v1
       with:
@@ -42,7 +42,7 @@ jobs:
     name: Build (github-pages gem)
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup Ruby
       uses: ruby/setup-ruby@v1
       with:
@@ -66,7 +66,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Setup Ruby ${{ matrix.ruby-version }}
         uses: ruby/setup-ruby@v1
         with:
@@ -75,17 +75,16 @@ jobs:
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Cache HTMLProofer
         id: cache-htmlproofer
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: tmp/.htmlproofer
           key: ${{ runner.os }}-htmlproofer
       - name: Build Site
         run: bundle exec jekyll build
       - name: Test with Nu Validator
-        uses: Cyb3r-Jak3/html5validator-action@c7bb77a0fe3b0458583de50fd0f4dd819569b8a9
+        uses: Cyb3r-Jak3/html5validator-action@2a593a9f2c10593cbac84791a6fc4c47e9a106c8
         with:
-          root: _site
+          config: fixtures/html5validator-config.yml
-          blacklist: line-numbers
       - name: Test with html-proofer
         run: bundle exec htmlproofer _site --ignore-urls "/github.com/,/web.archive.org/"
         env:
@@ -100,9 +99,9 @@ jobs:
         node-version: [18.x]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
     - run: npm install

.github/workflows/deploy.yml

@@ -30,7 +30,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -39,7 +39,7 @@ jobs:
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v2
+        uses: actions/configure-pages@v3
       - name: Build with Jekyll
         # Outputs to the './_site' directory by default
         run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
@@ -47,7 +47,7 @@ jobs:
           JEKYLL_ENV: production
       - name: Upload artifact
         # Automatically uploads an artifact from the './_site' directory by default
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v2
 
   # Deployment job
   deploy:
@@ -59,4 +59,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v1
+        uses: actions/deploy-pages@v2

.github/workflows/publish-gem.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Setup Ruby 3.2
       uses: ruby/setup-ruby@v1
       with:

.gitignore

@@ -16,13 +16,10 @@ vendor/
 
 # These next files are used by Just the Docs developers. They are not necessary for end users of the theme, only developers.
 
-# We use Stylelint and Prettier, JavaScript tools, to lint and format our own code,
+# We use Stylelint and Prettier, JavaScript tools, to lint and format our own code.
 # We use Node.js as our runtime, so we ignore node_modules
 node_modules
 
-# We also use Storybook to test regressions in changes; we ignore the build output.
-storybook-static
-
 # .DS_Store is a macOS-only metadata file about directories. Convention is to not commit them.
 # See: https://en.wikipedia.org/wiki/.DS_Store
 .DS_Store

.storybook/main.js

@@ -1,17 +0,0 @@
-/** @type { import('@storybook/html-webpack5').StorybookConfig } */
-const config = {
-  stories: ["../stories/**/*.mdx", "../stories/**/*.stories.@(js|jsx|ts|tsx)"],
-  addons: [
-    "@storybook/addon-links",
-    "@storybook/addon-essentials",
-    "@storybook/addon-interactions",
-  ],
-  framework: {
-    name: "@storybook/html-webpack5",
-    options: {},
-  },
-  docs: {
-    autodocs: "tag",
-  },
-}
-export default config

.storybook/preview.js

@@ -1,14 +0,0 @@
-/** @type { import('@storybook/html').Preview } */
-const preview = {
-  parameters: {
-    actions: { argTypesRegex: "^on[A-Z].*" },
-    controls: {
-      matchers: {
-        color: /(background|color)$/i,
-        date: /Date$/,
-      },
-    },
-  },
-}
-
-export default preview

CHANGELOG.md

@@ -17,8 +17,87 @@ 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:
 
-- Fixed: Windows emoji font fallback by [@flanakin] in [#1337]
+- N/A
 
+## Release v0.7.0
+
+Hi folks! This is a minor release that adds a new configuration option for opening external links in a new tab and provides many bugfixes (in both correctness and performance) for Just the Docs users with large sites. We anticipate that for most users, this is a straightforward upgrade. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme.
+
+### Migrating to `v0.7.0`
+
+**Migration**: users will need to migrate if:
+
+- they overrode `_includes/nav.html`, which has moved to `_includes/components/nav.html`
+- they have an element with the IDs `jtd-nav-activation` or `jtd-head-nav-stylesheet`
+
+For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/).
+
+### Using Release `v0.7.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.7.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.7.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.7.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.7.0` with the desired release tag.
+
+### New Features
+
+- Added: configuration options for opening external links in new tab by [@CarbonNeuron] in [#1360]
+
+### Bugfixes
+
+- Fixed: remove href from the navigation link to the current page by [@pdmosses] in [#1356]
+- Fixed: improve build time by [@pdmosses] in [#1358]
+- Fixed: erroneous parentheses in `site_nav` conditional by [@mattxwang] in [#1366]
+- Fixed: navigation scroll to active link regression by [@pdmosses] in [#1367]
+- Fixed: invalid CSS rules in head elements by [@pdmosses] in [#1368]
+- Fixed: accidental disabling of forward-declared stylesheets by [@mattxwang] in [#1373]
+
+{: .warning }
+[#1358] moved `_includes/nav.html` to the `_includes/components` directory,
+Users who were overriding that file will need to adjust their sites accordingly.
+
+### Documentation:
+
+- Docs: fix typos in `CHANGELOG` and `MIGRATION` by [@thapasusheel] in [#1377]
+
+### New Contributors
+
+- [@CarbonNeuron] made their first contribution in [#1360]
+- [@thapasusheel] made their first contribution in [#1377]
+
+[@CarbonNeuron]: https://github.com/CarbonNeuron
+[@thapasusheel]: https://github.com/thapasusheel
+
+[#1356]: https://github.com/just-the-docs/just-the-docs/pull/1356
+[#1358]: https://github.com/just-the-docs/just-the-docs/pull/1358
+[#1360]: https://github.com/just-the-docs/just-the-docs/pull/1360
+[#1366]: https://github.com/just-the-docs/just-the-docs/pull/1366
+[#1367]: https://github.com/just-the-docs/just-the-docs/pull/1367
+[#1368]: https://github.com/just-the-docs/just-the-docs/pull/1368
+[#1373]: https://github.com/just-the-docs/just-the-docs/pull/1373
+[#1377]: https://github.com/just-the-docs/just-the-docs/pull/1377
+
+## Release v0.6.2
+
+Hi all, this is a small patch release that includes two changes: adding a missing Windows emoji font fallback, and removing some (now-unused) code introduced in 0.6.
+
+### Bugfixes
+
+- Fixed: Windows emoji font fallback by [@flanakin] in [#1337]
+- Removed: unused `.passive` toggle in navigation by [@pdmosses] in [#1335]
+
+[#1335]: https://github.com/just-the-docs/just-the-docs/pull/1335
 [#1337]: https://github.com/just-the-docs/just-the-docs/pull/1337
 
 ### New Contributors
@@ -634,7 +713,7 @@ This RC does not introduce any major user-facing features. It adds more customiz
 
 ### Trying out pre-release `v0.4.0.rc5`
 
-Simlar to the prior release, `v0.4.0.rc5` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in.
+Similar to the prior release, `v0.4.0.rc5` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` following immediately after. While we don't anticipate many users using this RC, it is still possible to opt-in.
 
 To use this RC explicitly as a remote theme:
 
@@ -735,7 +814,7 @@ Have any questions, thoughts, or concerns? We'd love to hear from you! Please [o
 
 ### Trying out pre-release `v0.4.0.rc4`
 
-Simlar to the prior release, `v0.4.0.rc4` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc4`.
+Similar to the prior release, `v0.4.0.rc4` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc4`.
 
 To use this RC explicitly as a remote theme:
 
@@ -856,7 +935,7 @@ As soon as we get stable test results from major downstream users, we'll push ou
 
 ### Trying out pre-release `v0.4.0.rc3`
 
-Simlar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`.
+Similar to the prior release, `v0.4.0.rc3` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc3`.
 
 To use this RC explicitly as a remote theme:
 
@@ -932,7 +1011,7 @@ The intention of this release candidate is to gather even more feedback on a pot
 
 ### Trying out pre-release `v0.4.0.rc2`
 
-Simlar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`.
+Similar to the prior release, `v0.4.0.rc2` is a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc2`.
 
 To use this RC explicitly as a remote theme:
 
@@ -1020,7 +1099,7 @@ We want your feedback! Are these changes helpful? Are our docs easy to understan
 
 ### Trying out pre-release `v0.4.0.rc1`
 
-Due to the massive scope of these changes, we're making `v0.4.0.rc1` avaialble as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`.
+Due to the massive scope of these changes, we're making `v0.4.0.rc1` available as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1`.
 
 To use this RC explicitly as a remote theme:
 
@@ -1532,7 +1611,7 @@ fixes #291 #256 #293 #177
 
 ## v0.2.1
 
-This update fixes security vulnerablities in the lodash sub-dependency and bumps other dev dependencies to their latest version.
+This update fixes security vulnerabilities in the lodash sub-dependency and bumps other dev dependencies to their latest version.
 
 ## v0.2.0
 

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    just-the-docs (0.6.1)
+    just-the-docs (0.6.2)
       jekyll (>= 3.8.5)
       jekyll-include-cache
       jekyll-seo-tag (>= 2.0)

MIGRATION.md

@@ -43,6 +43,34 @@ This document contains instructions on how to migrate and upgrade Just the Docs
 
 [CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
 
+## v0.6.x - v0.7.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.7.0
+
+There are some *very minor* potentially-breaking changes for users in version `v0.7.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern:
+
+1. the movement of `_includes/nav.html`, which has moved to `_includes/components/nav.html`
+  - **explicit migration only necessary if users have overridden `_includes/nav.html`**
+2. the addition of `<script>` tags with `id`s `jtd-nav-activation` and `jtd-head-nav-stylesheet`
+  - **explicit migration only necessary if users have existing elements with those IDs**
+
+#### Moved Include
+
+Version `v0.7.0` has moved (and changed the contents of) `_includes/nav.html`; it is now in `_includes/components/nav.html`. This means that user overrides for the component will *no longer be loaded*, reverting to the Just the Docs default.
+
+Users who have overridden this `_includes` should:
+
+1. copy in the new upstream `_includes/components/nav.html` into their site
+2. port over any changes from their custom `_includes/nav.html`
+
+No other changes are necessary.
+
+#### New Script IDs
+
+Version `v0.7.0` adds the `id`s `jtd-nav-activation` and `jtd-head-nav-stylesheet` to some existing script tags. This will cause errors for users that have their own custom components with those IDs.
+
+Users who have elements with those `id`s should rename their elements to avoid a collision.
+
 ## v0.5.x - v0.6.0
 
 ### POTENTIALLY-BREAKING CHANGES in v0.6.0
@@ -119,7 +147,7 @@ However, some users may load different favicons for each page (and/or dynamicall
 
 ### POTENTIALLY-BREAKING CHANGES in v0.5.0
 
-There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concering `setup.scss`. To provide context:
+There is one potentially-breaking change for users migrating from `v0.4.2` to `v0.5.0` concerning `setup.scss`. To provide context:
 
 1. `setup.scss` was introduced in `v0.4.0`
 2. in `v0.4.0` and `v0.4.1`, `setup.scss` was imported *before* color scheme SCSS code

_config.yml

@@ -48,7 +48,6 @@ exclude:
    - Dockerfile
  # theme test code
    - fixtures/
-   - stories/
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"

_includes/components/breadcrumbs.html

@@ -3,30 +3,38 @@
   Depends on: page, site.
   Results in: HTML for the breadcrumbs component.
   Overwrites:
-    pages_list, parent_page, grandparent_page.
+    node, pages_list, parent_page, grandparent_page.
 {%- endcomment -%}
 
 {%- if page.url != "/" and page.parent -%}
 
-  {%- assign pages_list = site[page.collection]
+  {%- assign pages_list = site[page.collection] | default: site.html_pages -%}
-      | default: site.html_pages
-      | where_exp: "item", "item.title != nil"
-      | where_exp: "item", "item.has_children != nil" -%}
 
-  {%- if page.grand_parent -%}
+  {%- assign parent_page = nil -%}
-    {%- assign parent_page = pages_list
+  {%- assign grandparent_page = nil -%}
-        | where: "title", page.parent
+
-        | where: "parent", page.grand_parent
+  {%- for node in pages_list -%}
-        | first -%}
+  
-    {%- assign grandparent_page = pages_list
+    {%- if node.has_children and page.grand_parent -%}
-        | where: "title", page.grand_parent
+
-        | first -%}
+      {%- if node.title == page.parent and node.parent == page.grand_parent -%}
-  {%- else -%}
+        {%- assign parent_page = node -%}
-    {%- assign parent_page = pages_list
-        | where: "title", page.parent
-        | where_exp: "item", "item.parent == nil"
-        | first -%}
       {%- endif -%}
+      {%- if node.title ==  page.grand_parent -%}
+        {%- assign grandparent_page = node -%}
+      {%- endif -%}
+      {%- if parent_page and grandparent_page -%}
+        {%- break -%}
+      {%- endif -%}
+
+    {%- elsif node.has_children and node.title == page.parent and node.parent == nil -%}
+
+      {%- assign parent_page = node -%}
+      {%- break -%}
+
+    {%- endif -%}
+
+  {%- endfor -%}
 
 <nav aria-label="Breadcrumb" class="breadcrumb-nav">
   <ol class="breadcrumb-nav-list">

_includes/components/nav.html

@@ -1,5 +1,5 @@
 {%- comment -%}
-  Include as: {%- include_cached nav.html pages=pages -%}
+  Include as: {%- include components/nav.html pages=pages -%}
   Depends on: include.pages.
   Results in: HTML for the navigation panel.
   Includes:

_includes/components/sidebar.html

@@ -3,10 +3,9 @@
   Depends on: page(?), site.
   Results in: HTML for the side bar.
   Includes:
-    title.html, nav.html, nav_footer_custom.html
+    title.html, components/site_nav.html, nav_footer_custom.html
   Overwrites:
-    pages_top_size, collections_size, collection_entry,
+    nav_footer_custom.
-    collection_key, collection_value, collection, nav_footer_custom.
   Should not be cached, because nav_footer_custom.html might depend on page.
 {%- endcomment -%}
 
@@ -17,58 +16,8 @@
       <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-menu"></use></svg>
     </button>
   </div>
-  <nav aria-label="Main" id="site-nav" class="site-nav">
+
-    {% assign pages_top_size = site.html_pages
+  {% include_cached components/site_nav.html %}
-          | where_exp:"item", "item.title != nil"
-          | where_exp:"item", "item.parent == nil"
-          | where_exp:"item", "item.nav_exclude != true"
-          | size %}
-    {% if pages_top_size > 0 %}
-      {% include_cached nav.html pages=site.html_pages %}
-    {% endif %}
-    {%- if site.nav_external_links -%}
-      <ul class="nav-list">
-        {%- for node in site.nav_external_links -%}
-          <li class="nav-list-item external">
-            <a href="{{ node.url | absolute_url }}" class="nav-list-link external">
-              {{ node.title }}
-              {% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
-            </a>
-          </li>
-        {%- endfor -%}
-      </ul>
-    {%- endif -%}
-    {% if site.just_the_docs.collections %}
-      {% assign collections_size = site.just_the_docs.collections | size %}
-      {% for collection_entry in site.just_the_docs.collections %}
-        {% assign collection_key = collection_entry[0] %}
-        {% assign collection_value = collection_entry[1] %}
-        {% assign collection = site[collection_key] %}
-        {% if collection_value.nav_exclude != true %}
-          {% if collections_size > 1 or pages_top_size > 0 %}
-            {% if collection_value.nav_fold == true %}
-              <ul class="nav-list nav-category-list">
-                <li class="nav-list-item{% if page.collection == collection_key %} active{% endif %}">
-                  {%- if collection.size > 0 -%}
-                  <button class="nav-list-expander btn-reset" aria-label="Toggle collection {{ collection_value.name }}" aria-pressed="{% if page.collection == collection_key %}true{% else %}false{% endif %}">
-                    <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
-                  </button>
-                  {%- endif -%}
-                  <div class="nav-category">{{ collection_value.name }}</div>
-                  {% include_cached nav.html pages=collection %}
-                </li>
-              </ul>
-            {% else %}
-              <div class="nav-category">{{ collection_value.name }}</div>
-              {% include_cached nav.html pages=collection %}
-            {% endif %}
-          {% else %}
-            {% include_cached nav.html pages=collection %}
-          {% endif %}
-        {% endif %}
-      {% endfor %}
-    {% endif %}
-  </nav>
 
   {% capture nav_footer_custom %}
     {%- include nav_footer_custom.html -%}

_includes/components/site_nav.html

@@ -0,0 +1,67 @@
+{%- comment -%}
+  Include as: {%- include_cached components/site_nav.html -%}
+  Depends on: site.
+  Results in: HTML for the site-nav.
+  Includes:
+    components/nav.html
+  Overwrites:
+    pages_top_size, collections_size, collection_entry,
+    collection_key, collection_value, collection.
+{%- endcomment -%}
+
+<nav aria-label="Main" id="site-nav" class="site-nav">
+  {% assign pages_top_size = site.html_pages
+        | where_exp:"item", "item.title != nil"
+        | where_exp:"item", "item.parent == nil"
+        | where_exp:"item", "item.nav_exclude != true"
+        | size %}
+  {% if pages_top_size > 0 %}
+    {% include components/nav.html pages=site.html_pages %}
+  {% endif %}
+  {%- if site.nav_external_links -%}
+    <ul class="nav-list">
+      {%- for node in site.nav_external_links -%}
+        <li class="nav-list-item external">
+          <a href="{{ node.url | absolute_url }}" class="nav-list-link external"
+            {% if node.opens_in_new_tab or node.opens_in_new_tab == nil and site.nav_external_links_new_tab %}
+              target="_blank" rel="noopener noreferrer"
+            {% endif %}
+          >
+            {{ node.title }}
+            {% unless node.hide_icon %}<svg viewBox="0 0 24 24" aria-labelledby="svg-external-link-title"><use xlink:href="#svg-external-link"></use></svg>{% endunless %}
+          </a>
+        </li>
+      {%- endfor -%}
+    </ul>
+  {%- endif -%}
+  {% if site.just_the_docs.collections %}
+    {% assign collections_size = site.just_the_docs.collections | size %}
+    {% for collection_entry in site.just_the_docs.collections %}
+      {% assign collection_key = collection_entry[0] %}
+      {% assign collection_value = collection_entry[1] %}
+      {% assign collection = site[collection_key] %}
+      {% if collection_value.nav_exclude != true %}
+        {% if collections_size > 1 or pages_top_size > 0 %}
+          {% if collection_value.nav_fold == true %}
+            <ul class="nav-list nav-category-list">
+              <li class="nav-list-item">
+                {%- if collection.size > 0 -%}
+                <button class="nav-list-expander btn-reset" aria-label="Toggle collection {{ collection_value.name }}" aria-pressed="false">
+                  <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
+                </button>
+                {%- endif -%}
+                <div class="nav-category">{{ collection_value.name }}</div>
+                {% include components/nav.html pages=collection %}
+              </li>
+            </ul>
+          {% else %}
+            <div class="nav-category">{{ collection_value.name }}</div>
+            {% include components/nav.html pages=collection %}
+          {% endif %}
+        {% else %}
+          {% include components/nav.html pages=collection %}
+        {% endif %}
+      {% endif %}
+    {% endfor %}
+  {% endif %}
+</nav>

_includes/css/activation.scss.liquid

@@ -1,20 +1,47 @@
 {%- comment -%}
   Include as: {%- include css/activation.scss.liquid -%}
   Depends on: page, site.
-  Results in: page-dependent SCSS rules for inclusion in a head style element.
+  Results in: page-dependent (non-nested) CSS rules for inclusion in a head style element,
+    which needs to be suppressed when JS is enabled.
   Includes:
     sorted_pages.html.
   Overwrites: 
-    activation_pages, activation_pages_top_size, activation_page, activation_title,
+    activation_no_nav_link, activation_pages, activation_pages_top_size, activation_page, activation_title,
     activation_first_level, activation_second_level, activation_third_level,
     activation_first_level_reversed, activation_second_level_reversed,
-    activation_first_level_index, activation_second_level_index, activation_third_level_index.
+    activation_first_level_index, activation_second_level_index, activation_third_level_index,
+    activation_index, activation_collection_prefix, activation_other_collection_prefix.
   Should not be cached, because it depends on page.
   (For a site with only top-level pages, the rendering of this file is always empty.
-  This property could be detected, and might halve the build time for such sites.)
+  This property could be detected, and used to reduce the build time for such sites.)
 {%- endcomment -%}
 
-{%- unless page.title == nil or page.nav_exclude == true -%}
+{%- comment -%}
+  The CSS rules in activation_no_nav_link are for use on pages excluded from the main navigation.
+  - The first rule ensures that no nav-link has a background image.
+  - The other two rules ensure that all folding collections are expanded.
+{%- endcomment -%}
+
+{%- capture activation_no_nav_link %}
+.site-nav ul li a {
+  background-image: none;
+}
+
+{%- if site.just_the_docs.collections %}
+.site-nav > ul.nav-category-list > li > button svg {
+  transform: rotate(-90deg);
+}
+.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list {
+  display: block;
+}
+{%- endif %}
+{% endcapture -%}
+
+{%- if page.title == nil or page.nav_exclude == true -%}
+
+{{ activation_no_nav_link }}
+
+{%- else -%}
 
 {%- assign activation_pages = site[page.collection]
       | default: site.html_pages
@@ -27,6 +54,11 @@
 {%- assign activation_first_level_reversed = nil -%}
 {%- assign activation_second_level_reversed = nil -%}
 
+{%- comment -%}
+  The generated CSS depends on the position of the current page in each level in
+  the navigation.
+{%- endcomment -%}
+
 {%- assign activation_title = page.grand_parent | default: page.parent | default: page.title -%}
 {%- assign activation_first_level = activation_pages
       | where_exp: "item", "item.parent == nil" -%}
@@ -39,7 +71,11 @@
   {%- endif -%}
 {%- endfor -%}
 
-{%- unless activation_first_level_index == nil -%}
+{%- if activation_first_level_index == nil -%}
+
+{{ activation_no_nav_link }}
+
+{%- else -%}
 
 {%- if page.grand_parent -%}
   {%- assign activation_title = page.parent -%}
@@ -83,23 +119,52 @@
   {%- endfor -%}
 {%- endif -%}
 
-{%- unless activation_second_level_index == nil and activation_third_level_index -%}
+{%- if activation_second_level_index == nil and activation_third_level_index -%}
+
+{{ activation_no_nav_link }}
+
+{%- else -%}
+
+{%- comment -%}
+  The site-nav is:
+  - an optional ul.nav-list with li.nav-list-items for non-collection top-level pages
+  - an optional ul.nav-list with li.nav-list-item.externals
+  - any number of just-the-docs.collections
+  
+  A non-foldable collection is:
+  - a div.nav-category with the collection name, followed by:
+  - a ul.nav-list with li.nav-list-items for its top-level pages
+  
+  A foldable collection is:
+  - a ul.nav-list.nav-category-list with a single li.nav-list-item containing:
+    - an optional button with the expander svg
+    - a div.nav-category with the collection name
+    - a ul.nav-list with li.nav-list-items for its top-level pages
+  
+  The generated CSS uses:
+  - activation_collection_prefix, to select the site-nav > ul.nav-list for the page
+  - activation_other_collection_prefix, to select all the other site-nav > ul.nav-lists
+{%- endcomment -%}
 
 {%- if page.collection == nil -%}
 
   {%- capture activation_collection_prefix -%}
-  .site-nav > .nav-list:nth-child(1):not(.nav-category-list) 
+  .site-nav > ul.nav-list:first-child
+  {%- endcapture -%}
+
+  {%- capture activation_other_collection_prefix -%}
+  .site-nav > ul.nav-list:not(:first-child)
   {%- endcapture -%}
 
 {%- else -%}
 
   {%- for activation_collection in site.just_the_docs.collections -%}
     {%- if activation_collection[0] == page.collection -%}
-      {%- assign activation_collection_index = forloop.index -%}
+      {%- assign activation_index = forloop.index -%}
       {%- break -%}
     {%- endif -%}
   {%- endfor -%}
-  {%- assign activation_index = activation_collection_index -%}
+
   {%- assign activation_pages_top_size = site.html_pages
           | where_exp:"item", "item.title != nil"
           | where_exp:"item", "item.parent == nil"
@@ -108,66 +173,109 @@
   {%- if activation_pages_top_size > 0 -%}
     {%- assign activation_index = activation_index | plus: 1 -%}
   {%- endif -%}
+
   {%- if site.nav_external_links -%}
     {%- assign activation_index = activation_index | plus: 1 -%}
   {%- endif -%}
+
   {%- capture activation_collection_prefix -%}
-  .site-nav > .nav-list:nth-of-type({{ activation_index }}){% if site.just_the_docs.collections[page.collection].nav_fold == true %} > .nav-list-item > .nav-list{% endif %}
+  .site-nav > ul:nth-of-type({{ activation_index }})
+  {%- if site.just_the_docs.collections[page.collection].nav_fold %} > li > ul
+  {%- endif -%}
+  {%- endcapture -%}
+
+  {%- capture activation_other_collection_prefix -%}
+  .site-nav > ul:not(:nth-of-type({{ activation_index }}))
   {%- endcapture -%}
 
 {%- endif -%}
 
-// Styling for the nav-list-link to the current page:
+{%- comment -%}
-{{ activation_collection_prefix }} {
+  The required background image of the link to the current page may involve SCSS.
-  > .nav-list-item:not(.external):nth-child({{ activation_first_level_index }}){%- if activation_second_level_index %} > .nav-list > .nav-list-item:nth-child({{ activation_second_level_index }}){%- if activation_third_level_index %} > .nav-list > .nav-list-item:nth-child({{ activation_third_level_index }}){% endif %}{% endif %} {
+  To avoid page-dependent SCSS, all nav links initially have that background image.
-    > .nav-list-link {
+  The following rule removes the image from the links to all parents, siblings,
-      display: block;
+  and children of the current page.
+{%- endcomment %}
+
+{% if activation_third_level_index -%}
+
+{{ activation_collection_prefix }} > li > a,
+{{ activation_collection_prefix }} > li > ul > li > a,
+{{ activation_collection_prefix }} > li > ul > li > ul > li:not(:nth-child({{ activation_third_level_index }})) > a {
+  background-image: none;
+}
+
+{%- elsif activation_second_level_index -%}
+
+{{ activation_collection_prefix }} > li > a,
+{{ activation_collection_prefix }} > li > ul > li:not(:nth-child({{ activation_second_level_index }})) > a,
+{{ activation_collection_prefix }} > li > ul > li > ul > li > a {
+  background-image: none;
+}
+
+{%- else -%}
+
+{{ activation_collection_prefix }} > li:not(:nth-child({{ activation_first_level_index }})) > a,
+{{ activation_collection_prefix }} > li > ul > li > a,
+{{ activation_collection_prefix }} > li > ul > li > ul > li > a {
+  background-image: none;
+}
+
+{%- endif %}
+
+{%- comment -%}
+  The following rule removes the image from the links to pages in other collections.
+{%- endcomment %}
+
+{{ activation_other_collection_prefix }} a,
+.site-nav li.external a {
+  background-image: none;
+}
+
+{%- comment -%}
+  The following rule styles the link to the current page.
+{%- endcomment %}
+
+{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }})
+{%- if activation_second_level_index %} > ul > li:nth-child({{ activation_second_level_index }})
+{%- if activation_third_level_index %} > ul > li:nth-child({{ activation_third_level_index }})
+{%- endif -%}
+{%- endif %} > a {
   font-weight: 600;
   text-decoration: none;
-      background-image: linear-gradient(
-        -90deg,
-        rgba($feedback-color, 1) 0%,
-        rgba($feedback-color, 0.8) 80%,
-        rgba($feedback-color, 0) 100%
-      );
-    }
-  }
 }
 
-// Styling for nav-list-expanders at first and second levels,
+{%- comment -%}
-// suppressed when a click has deactivated the expander (making the nav-list-item .passive):
+  The following rules unfold all collections, and display the links to any children
-{{ activation_collection_prefix }} {
+  of the current page.
-  > .nav-list-item:not(.passive):nth-child({{ activation_first_level_index }}){%- if activation_second_level_index %},
+  
-  > .nav-list-item:not(.passive):nth-child({{ activation_first_level_index }}) > .nav-list > .nav-list-item:not(.passive):nth-child({{ activation_second_level_index }}){% endif %} {
+  To avoid dependence on the SCSS variable nav-list-expander-right, the direction
-    > .nav-list-expander svg {
+  of the rotation of the expander icon is fixed, and corresponds to the appearance
-      @if $nav-list-expander-right {
+  when nav-list-expander-right is true. This results in a minor visual difference
+  between the appearance of active expander icons when JS is enabled/disabled and
+  nav-list-expander-right is false, which seems unavoidable.
+{%- endcomment %}
+
+{%- if site.just_the_docs.collections %}
+.site-nav > ul.nav-category-list > li > button svg,
+{% endif -%}
+{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) > button svg
+{%- if activation_second_level_index -%},
+{{ activation_collection_prefix }} > li:nth-child({{ activation_first_level_index }}) > ul > li:nth-child({{ activation_second_level_index }}) > button svg
+{%- endif %} {
   transform: rotate(-90deg);
-      } @else {
-        transform: rotate(90deg);
-      }
-    }
-
-    > .nav-list {
-      display: block;
-    }
-  }
 }
 
-// Styling for nav-list-expander for categories:
+{%- if site.just_the_docs.collections %}
-.site-nav > .nav-category-list > .nav-list-item:not(.passive) {
+.site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list,
-  > .nav-list-expander svg {
+{% endif -%}
-    @if $nav-list-expander-right {
+{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ activation_first_level_index }}) > ul.nav-list
-      transform: rotate(-90deg);
+{%- if activation_second_level_index %},
-    } @else {
+{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ activation_first_level_index }}) > ul.nav-list > li.nav-list-item:nth-child({{ activation_second_level_index }}) > ul.nav-list
-      transform: rotate(90deg);
+{%- endif %} {
-    }
-  }
-
-  > .nav-list {
   display: block;
-  }
 }
 
-{%- endunless -%}
+{%- endif -%}
-{%- endunless -%}
+{%- endif -%}
-{%- endunless -%}
+{%- endif -%}

_includes/head.html

@@ -4,7 +4,7 @@
     site.search_enabled, site.static_files, site.favicon_ico.
   Results in: HTML for the head element.
   Includes:
-    head_nav.html, head_custom.html.
+    css/activation.scss.liquid, head_custom.html.
   Overwrites:
     ga_tracking_ids, ga_property, file, favicon.
   Should not be cached, because included files depend on page.
@@ -16,7 +16,11 @@
 
   <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
 
-  {% include head_nav.html %}
+  <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-head-nav.css' | relative_url }}" id="jtd-head-nav-stylesheet">
+
+  <style id="jtd-nav-activation">
+  {% include css/activation.scss.liquid %}
+  </style>
 
   {% if site.ga_tracking != nil %}
     {% assign ga_tracking_ids = site.ga_tracking | split: "," %}

_includes/head_nav.html

@@ -1,48 +0,0 @@
-{%- comment -%}
-  Include as: {%- include head_nav.html -%}
-  Depends on: site.color_scheme.
-  Results in: HTML for a page-specific style element.
-  Includes:
-    css/activation.scss.liquid.
-  Overwrites: 
-    activation, test_scss, scss, css, index, count.
-  Should not be cached, because css/activation.scss.liquid depends on page.
-{%- endcomment -%}
-
-{% capture activation %}
-  {% include css/activation.scss.liquid %}
-{%- endcapture -%}
-
-{% capture test_scss %}
-  @import "./support/support";
-  @import "./color_schemes/light";
-  {{ activation }}
-{%- endcapture -%}
-
-{%- capture scss -%}
-  @import "./support/support";
-  @import "./custom/setup";
-  {% if site.color_scheme and site.color_scheme != "nil" -%}
-    {%- assign color_scheme = site.color_scheme -%}
-  {%- else -%}
-    {%- assign color_scheme = "light" -%}
-  {%- endif %}
-  @import "./color_schemes/light";
-  {% unless color_scheme == "light" %}
-  @import "./color_schemes/{{ color_scheme }}";
-  {% endunless %}
-  {{ activation }}
-{%- endcapture -%}
-
-{%- comment -%}
-  Convert to CSS, then remove the color_scheme import rules to avoid duplication.
-  The value of count is page-dependent, but independent of custom color schemes.
-{%- endcomment -%}
-{%- assign count = test_scss  | scssify | split: ".site-nav" | size -%}
-{%- unless count == 1 %}
-{%- assign index = 1 | minus: count -%}
-{%- assign css = scss | scssify | split: ".site-nav" | slice: index, count | join: ".site-nav" -%}
-<style type="text/css">
-{{ css | prepend: ".site-nav" }}
-</style>
-{%- endunless %}

_sass/buttons.scss

@@ -105,7 +105,7 @@
 }
 
 .btn-purple {
-  @include btn-color($white, $purple-300);
+  @include btn-color($white, $purple-100);
 }
 
 .btn-blue {

assets/css/just-the-docs-head-nav.css

@@ -0,0 +1,24 @@
+---
+---
+{%- if site.color_scheme and site.color_scheme != "nil" -%}
+  {%- assign color_scheme = site.color_scheme -%}
+{%- else -%}
+  {%- assign color_scheme = "light" -%}
+{%- endif -%}
+
+{%- capture newline %}
+{% endcapture -%}
+
+{%- capture scss -%}
+{% include css/just-the-docs.scss.liquid color_scheme=color_scheme %}
+.site-nav ul li a {
+  background-image: linear-gradient(
+    -90deg,
+    rgba($feedback-color, 1) 0%,
+    rgba($feedback-color, 0.8) 80%,
+    rgba($feedback-color, 0) 100%
+  );
+}
+{%- endcapture -%}
+
+{{ scss | scssify | split: newline | slice: -3, 3 | join: newline }}

assets/js/just-the-docs.js

@@ -31,10 +31,7 @@ function initNav() {
     }
     if (target) {
       e.preventDefault();
-      const active = target.parentNode.classList.toggle('active');
+      target.ariaPressed = target.parentNode.classList.toggle('active');
-      const passive = target.parentNode.classList.toggle('passive');
-      if (active && passive) target.parentNode.classList.toggle('passive');
-      target.ariaPressed = active;
     }
   });
 
@@ -42,7 +39,7 @@ function initNav() {
   const mainHeader = document.getElementById('main-header');
   const menuButton = document.getElementById('menu-button');
 
-  disableHeadStyleSheet();
+  disableHeadStyleSheets();
 
   jtd.addEvent(menuButton, 'click', function(e){
     e.preventDefault();
@@ -71,13 +68,23 @@ function initNav() {
   {%- endif %}
 }
 
-// The page-specific <style> in the <head> is needed only when JS is disabled.
+// The <head> element is assumed to include the following stylesheets:
-// Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme). 
+// - a <link> to /assets/css/just-the-docs-head-nav.css,
-// The page-specific stylesheet is assumed to have index 1 in the list of stylesheets.
+//             with id 'jtd-head-nav-stylesheet'
+// - a <style> containing the result of _includes/css/activation.scss.liquid.
+// To avoid relying on the order of stylesheets (which can change with HTML
+// compression, user-added JavaScript, and other side effects), stylesheets
+// are only interacted with via ID
 
-function disableHeadStyleSheet() {
+function disableHeadStyleSheets() {
-  if (document.styleSheets[1]) {
+  const headNav = document.getElementById('jtd-head-nav-stylesheet');
-    document.styleSheets[1].disabled = true;
+  if (headNav) {
+    headNav.disabled = true;
+  }
+
+  const activation = document.getElementById('jtd-nav-activation');
+  if (activation) {
+    activation.disabled = true;
   }
 }
 
@@ -494,12 +501,12 @@ function scrollNav() {
   if (targetLink) {
     const rect = targetLink.getBoundingClientRect();
     document.getElementById('site-nav').scrollBy(0, rect.top - 3*rect.height);
+    targetLink.removeAttribute('href');
   }
 }
 
 // Find the nav-list-link that refers to the current page
-// then make it and all enclosing nav-list-item elements active,
+// then make it and all enclosing nav-list-item elements active.
-// and make all other folded collections passive
 
 function activateNav() {
   var target = navLink();
@@ -515,17 +522,6 @@ function activateNav() {
       target = target.parentNode;
     }
   }
-  const elements = document.getElementsByClassName("nav-category-list");
-  for (const element of elements) {
-    const item = element.children[0];
-    const active = item.classList.toggle('active');
-    if (active) {
-      item.classList.toggle('active', false);
-      item.classList.toggle('passive', true);
-    } else {
-      item.classList.toggle('active', true);
-    }
-  }
 }
 
 // Document ready

docs/customization.md

@@ -52,7 +52,7 @@ New (v0.4.2)
 {: .label .label-green }
 
 
-In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who are want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme.
+In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme.
 
 ## Custom schemes
 

docs/navigation-structure.md

@@ -20,7 +20,7 @@ nav_order: 5
 
 ## Main navigation
 
-The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
+The main navigation for your Just the Docs site is on the left side of the page on large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
 
 By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see [Pages with Children](#pages-with-children)).
 
@@ -30,7 +30,7 @@ By default, all pages will appear as top level pages in the main nav unless a pa
 
 To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
 
-#### Example
+### Example (ordering pages)
 {: .no_toc }
 
 ```yaml
@@ -55,7 +55,7 @@ By default, all Capital letters come before all lowercase letters; you can add `
 
 For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the `nav_exclude: true` parameter in the YAML front matter for that page.
 
-#### Example
+### Example (excluding pages)
 {: .no_toc }
 
 ```yaml
@@ -108,7 +108,7 @@ On the parent pages, add this YAML front matter parameter:
 
 - `has_children: true` (tells us that this is a parent page)
 
-#### Example
+### Example (parent pages)
 {: .no_toc }
 
 ```yaml
@@ -129,7 +129,7 @@ Here we're setting up the UI Components landing page that is available at `/docs
 
 On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).
 
-#### Example
+#### Example (child pages)
 {: .no_toc }
 
 ```yaml
@@ -154,7 +154,7 @@ You can optionally add the following to the YAML front matter to reverse the def
 
 - `child_nav_order: reversed`
 
-#### Example
+#### Example (ordering child pages)
 {: .no_toc }
 ```yaml
 ---
@@ -168,7 +168,7 @@ child_nav_order: reversed
 
 By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter.
 
-#### Example
+#### Example (auto-generating Table of Contents)
 {: .no_toc }
 
 ```yaml
@@ -191,7 +191,7 @@ Child pages can also have children (grandchildren). This is achieved by using a
 1. Add the `has_children` attribute to the child
 1. Add the `parent` and `grand_parent` attribute to the grandchild
 
-#### Example
+##### Example (children within children)
 {: .no_toc }
 
 ```yaml
@@ -241,7 +241,7 @@ Currently, the navigation structure is limited to 3 levels: grandchild pages can
 
 To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
 
-#### Example
+### Example (auxiliary links)
 {: .no_toc }
 
 ```yaml
@@ -262,7 +262,7 @@ New (v0.4.0)
 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
+### Example (external navigation links)
 {: .no_toc }
 
 ```yaml
@@ -271,18 +271,32 @@ nav_external_links:
   - title: Just the Docs on GitHub
     url: https://github.com/just-the-docs/just-the-docs
     hide_icon: false # set to true to hide the external link icon - defaults to false
+    opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false
 ```
 
+### Opening external links in a new tab
+{: .d-inline-block }
+
+New (unreleased)
+{: .label .label-green }
+
 The external links are decorated by an icon, which distinguishes them from internal links.
 You can suppress the icon by setting `hide_icon: true`.
 
+By default, external links are not opened in a new tab. However, this can be enabled by:
+
+1. setting `opens_in_new_tab: true` in the link's configuration object
+2. setting the configuration option `nav_external_links_new_tab: true` in `_config.yml`
+
+When they conflict, `opens_in_new_tab` takes precedence.
+
 ---
 
 ## In-page navigation with Table of Contents
 
 To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `<ol>` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class.
 
-#### Example
+### Example (in-page navigation with Table of Contents)
 {: .no_toc }
 
 ```markdown
@@ -300,7 +314,7 @@ This example skips the page name heading (`#`) from the TOC, as well as the head
 
 ### Collapsible Table of Contents
 
-The Table of Contents can be made collapsible using the `<details>` and `<summary>` elements , as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional.
+The Table of Contents can be made collapsible using the `<details>` and `<summary>` elements, as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional.
 
 ```markdown
 <details open markdown="block">

docs/utilities/layout.md

@@ -61,7 +61,7 @@ Use `mx-auto` to horizontally center elements.
 In Markdown, use the `{: }` wrapper to apply custom classes:
 
 ```markdown
-This paragraph will have a margin bottom of 1rem/16px at large screens.
+This paragraph will have a margin bottom of 1rem/16px on large screens.
 {: .mb-lg-4 }
 
 This paragraph will have 2rem/32px of padding on the right and left at all screen sizes.

docs/utilities/utilities.md

@@ -9,5 +9,5 @@ permalink: docs/utilities
 # Utilities
 {: .no_toc }
 
-CSS utility classes come in handy when you to want to override default styles to create additional whitespace (margins/padding), correct unexpected shifts in font size or weight, add color, or hide (or show) something at a specific screen size.
+CSS utility classes come in handy when you want to override default styles to create additional whitespace (margins/padding), correct unexpected shifts in font size or weight, add color, or hide (or show) something at a specific screen size.
 {: .fs-6 .fw-300 }

fixtures/html5validator-config.yml

@@ -0,0 +1,3 @@
+root: _site
+blacklist:
+  - "line-numbers"

just-the-docs.gemspec

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

package.json

@@ -1,43 +1,22 @@
 {
   "name": "just-the-docs",
-  "version": "0.5.0",
+  "version": "0.3.3",
   "description": "A modern Jekyll theme for documentation",
-  "repository": {
+  "repository": "just-the-docs/just-the-docs",
-    "type": "git",
-    "url": "git+https://github.com/just-the-docs/just-the-docs.git"
-  },
   "license": "MIT",
-  "bugs": {
+  "bugs": "https://github.com/just-the-docs/just-the-docs/issues",
-    "url": "https://github.com/just-the-docs/just-the-docs/issues"
-  },
   "devDependencies": {
-    "@babel/preset-env": "^7.21.4",
-    "@babel/preset-typescript": "^7.21.4",
-    "@storybook/addon-essentials": "^7.0.7",
-    "@storybook/addon-interactions": "^7.0.7",
-    "@storybook/addon-links": "^7.0.7",
-    "@storybook/blocks": "^7.0.7",
-    "@storybook/html": "^7.0.7",
-    "@storybook/html-webpack5": "^7.0.7",
-    "@storybook/testing-library": "^0.0.14-next.2",
-    "chromatic": "^6.17.3",
     "npm-run-all": "^4.1.5",
     "prettier": "^3.0.3",
-    "react": "^18.2.0",
+    "stylelint": "^15.11.0",
-    "react-dom": "^18.2.0",
+    "stylelint-config-standard-scss": "^11.0.0"
-    "storybook": "^7.0.7",
-    "stylelint": "^15.10.3",
-    "stylelint-config-standard-scss": "^10.0.0"
   },
   "scripts": {
     "lint": "npm-run-all --parallel --continue-on-error lint:*",
     "lint:css": "stylelint '**/*.scss'",
     "lint:formatting": "prettier --check '**/*.{scss,js,json}'",
     "format": "prettier --write '**/*.{scss,js,json}'",
-    "test": "npm run lint",
+    "test": "npm run lint"
-    "storybook": "bundle exec jekyll build && storybook dev -p 6006",
-    "build-storybook": "bundle exec jekyll build && storybook build",
-    "chromatic": "npx chromatic --project-token=9355f489c51b -d storybook-static"
   },
   "stylelint": {
     "ignoreFiles": [
@@ -64,7 +43,5 @@
     "singleQuote": false,
     "tabWidth": 2,
     "trailingComma": "es5"
-  },
+  }
-  "homepage": "https://just-the-docs.com",
-  "_id": "just-the-docs@0.5.0"
 }

stories/Introduction.mdx

@@ -1,7 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-<Meta title="Example/Introduction" />
-
-# Storybook for Just the Docs
-
-A WIP [Storybook](https://storybook.js.org/) for Just the Docs.

stories/ui-components/Button.js

@@ -1,11 +0,0 @@
-import "../../_site/assets/css/just-the-docs-default.css"
-
-export const createButton = ({ variant = "default", label, size = "4" }) => {
-  const btn = document.createElement("button")
-  btn.type = "button"
-  btn.innerText = label
-
-  btn.className = ["btn", `btn-${variant}`, `fs-${size}`].join(" ")
-
-  return btn
-}

stories/ui-components/Button.stories.js

@@ -1,68 +0,0 @@
-import { createButton } from "./Button"
-
-export default {
-  title: "UI Components/Button",
-  tags: ["autodocs"],
-  render: ({ label, ...args }) => {
-    return createButton({ label, ...args })
-  },
-  argTypes: {
-    label: { control: "text" },
-    size: {
-      control: { type: "select" },
-      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
-    },
-    variant: {
-      control: { type: "select" },
-      options: ["default", "primary", "purple", "blue", "green", "outline"],
-    },
-  },
-}
-
-export const Default = {
-  args: {
-    variant: "default",
-    label: "Button",
-    size: 4,
-  },
-}
-
-export const Primary = {
-  args: {
-    variant: "primary",
-    label: "Button",
-    size: 4,
-  },
-}
-
-export const Purple = {
-  args: {
-    variant: "purple",
-    label: "Button",
-    size: 4,
-  },
-}
-
-export const Blue = {
-  args: {
-    variant: "blue",
-    label: "Button",
-    size: 4,
-  },
-}
-
-export const Green = {
-  args: {
-    variant: "green",
-    label: "Button",
-    size: 4,
-  },
-}
-
-export const Outline = {
-  args: {
-    variant: "outline",
-    label: "Button",
-    size: 4,
-  },
-}

stories/ui-components/Label.js

@@ -1,10 +0,0 @@
-import "../../_site/assets/css/just-the-docs-default.css"
-
-export const createLabel = ({ variant = "default", label, size = "4" }) => {
-  const btn = document.createElement("span")
-  btn.innerText = label
-
-  btn.className = ["label", `label-${variant}`, `fs-${size}`].join(" ")
-
-  return btn
-}

stories/ui-components/Label.stories.js

@@ -1,68 +0,0 @@
-import { createLabel } from "./Label"
-
-export default {
-  title: "UI Components/Label",
-  tags: ["autodocs"],
-  render: ({ label, ...args }) => {
-    return createLabel({ label, ...args })
-  },
-  argTypes: {
-    label: { control: "text" },
-    size: {
-      control: { type: "select" },
-      options: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
-    },
-    variant: {
-      control: { type: "select" },
-      options: ["default", "purple", "blue", "green", "red", "yellow"],
-    },
-  },
-}
-
-export const Default = {
-  args: {
-    variant: "default",
-    label: "Label",
-    size: 4,
-  },
-}
-
-export const Purple = {
-  args: {
-    variant: "purple",
-    label: "Label",
-    size: 4,
-  },
-}
-
-export const Blue = {
-  args: {
-    variant: "blue",
-    label: "Label",
-    size: 4,
-  },
-}
-
-export const Green = {
-  args: {
-    variant: "green",
-    label: "Label",
-    size: 4,
-  },
-}
-
-export const Red = {
-  args: {
-    variant: "red",
-    label: "Label",
-    size: 4,
-  },
-}
-
-export const Yellow = {
-  args: {
-    variant: "yellow",
-    label: "Label",
-    size: 4,
-  },
-}