just-the-docs 0.5.4 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 986143230e171f827a5a5b1305f3e3f90483b528098811ea2abe8732dcf0ea55
-  data.tar.gz: f47ff09e5cbf500df3b411b496dd478a1e0f89d62daf01cab1ca7bb33a48940a
+  metadata.gz: d446ba90f56256475c5081e27d1a5f344210001ae32a51b180946ce22a2981ae
+  data.tar.gz: c77e78250f79451b833b4b5482069a978c92933e89079f0efcc67fa6f161fa38
 SHA512:
-  metadata.gz: 38aa0de5e1e0d5c32c5769fdc4fc8cba569799c179688c755c4d33b84707a66e7546983d9e915677a74a2c57307e13c2436f62f9f4d21e4463bcee807bfeea5d
-  data.tar.gz: 31125488864c34d27ef32875b478f642cfdb9fac73131788b1933ac47a952ea3e842990dcc55c5c282eefa5b3b4261c848c727d10be80a75e6c403f0f98a7be8
+  metadata.gz: 99744850f76f7660bc97b00d6fcbf2acd9f9495c466fc7c3f0a65474fcea05c94e5448f8b16be0d90f39a76e6e7f1c08bd8b64348924179421a46a40a9767c7f
+  data.tar.gz: 9ea114f0cd183928b053e40ba2a6474fe2936b4bfcc34b2956643ff5e6ef1c11db0b2fcb9265f830467af1e697b076a53b0e90eb24699bbdc11182a9ce67d8fb

data/CHANGELOG.md

@@ -15,16 +15,69 @@ The project underwent a major maintenance shift in March 2022.
 {: .note }
 This website is built from the `HEAD` of the `main` branch of the theme repository.
 
-{: .warning }
-This website includes docs for some new features that are not available in `v0.5.2`!
-
 Code changes to `main` that are *not* in the latest release:
 
 - N/A
 
-Docs changes in `main` that are *not* in the latest release:
+## Release v0.6.0
 
-- N/A
+Hi all, this is a minor release that introduces performance improvements for build times on large sites, correctly sets the `color-scheme` property, and fixes invalid HTML. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme.
+
+### Migrating to `v0.6.0`
+
+**Migration**: users will need to migrate if:
+
+- they have an existing `_includes` file named `favicon.html`, `head_nav.html`, or `css/activation.scss.liquid`
+- they have code that refers to `#main-content-wrap`
+- they override the default `light` theme's code, or the theme-loading logic
+- they have different favicons for different pages
+
+For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/).
+
+### Using Release `v0.6.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.6.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.6.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.6.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.6.0` with the desired release tag.
+
+### New Features and Bugfixes
+
+- Added: `$color-scheme` theme variable to specify `color-scheme` for `:root` by [@sigv] in [#1280]
+- Fixed: build times for large sites by [@pdmosses] in [#1244]
+- Fixed: missing closing `</button>` tag in `sidebar.html` by [@mattxwang] in [#1304]
+- Fixed: removed duplicate `#main-content-wrap` minimal and default layouts by [@mattxwang] in [#1305]
+
+### Documentation
+
+{: .warning }
+The theme docs are unversioned, and already reflect the above changes.
+
+Docs changes:
+
+- A [footnote]({% link docs/configuration.md %}#fn:js-disabled) in the configuration docs explains how disabling JavaScript affects the display of navigation links when browsing folded collections.
+- Invalid HTML has been removed from most documentation examples.
+
+### New Contributors
+
+- [@sigv] made their first contribution in [#1280]
+
+[@sigv]: https://github.com/sigv
+[#1244]: https://github.com/just-the-docs/just-the-docs/pull/1244
+[#1280]: https://github.com/just-the-docs/just-the-docs/pull/1280
+[#1304]: https://github.com/just-the-docs/just-the-docs/pull/1304
+[#1305]: https://github.com/just-the-docs/just-the-docs/pull/1305
 
 ## Release v0.5.4
 

data/_includes/components/sidebar.html

@@ -1,9 +1,21 @@
+{%- comment -%}
+  Include as: {%- include components/sidebar.html -%}
+  Depends on: page(?), site.
+  Results in: HTML for the side bar.
+  Includes:
+    title.html, nav.html, nav_footer_custom.html
+  Overwrites: 
+    pages_top_size, collections_size, collection_entry,
+    collection_key, collection_value, collection, nav_footer_custom.
+  Should not be cached, because nav_footer_custom.html might depend on page.
+{%- endcomment -%}
+
 <div class="side-bar">
   <div class="site-header" role="banner">
     <a href="{{ '/' | relative_url }}" class="site-title lh-tight">{% include title.html %}</a>
     <button id="menu-button" class="site-button btn-reset" aria-label="Toggle menu" aria-pressed="false">
       <svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-menu"></use></svg>
-    </a>
+    </button>
   </div>
   <nav aria-label="Main" id="site-nav" class="site-nav">
     {% assign pages_top_size = site.html_pages
@@ -12,7 +24,7 @@
           | where_exp:"item", "item.nav_exclude != true"
           | size %}
     {% if pages_top_size > 0 %}
-      {% include nav.html pages=site.html_pages key=nil %}
+      {% include_cached nav.html pages=site.html_pages %}
     {% endif %}
     {%- if site.nav_external_links -%}
       <ul class="nav-list">
@@ -43,15 +55,15 @@
                   </button>
                   {%- endif -%}
                   <div class="nav-category">{{ collection_value.name }}</div>
-                  {% include nav.html pages=collection key=collection_key %}
+                  {% include_cached nav.html pages=collection %}
                 </li>
               </ul>
             {% else %}
               <div class="nav-category">{{ collection_value.name }}</div>
-              {% include nav.html pages=collection key=collection_key %}
+              {% include_cached nav.html pages=collection %}
             {% endif %}
           {% else %}
-            {% include nav.html pages=collection key=collection_key %}
+            {% include_cached nav.html pages=collection %}
           {% endif %}
         {% endif %}
       {% endfor %}

data/_includes/css/activation.scss.liquid

@@ -0,0 +1,173 @@
+{%- 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.
+  Includes:
+    sorted_pages.html.
+  Overwrites: 
+    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.
+  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.)
+{%- endcomment -%}
+
+{%- unless page.title == nil or page.nav_exclude == true -%}
+
+{%- assign activation_pages = site[page.collection]
+      | default: site.html_pages
+      | where_exp: "item", "item.title != nil"
+      | where_exp: "item", "item.nav_exclude != true" -%}
+
+{%- assign activation_first_level_index = nil -%}
+{%- assign activation_second_level_index = nil -%}
+{%- assign activation_third_level_index = nil -%}
+{%- assign activation_first_level_reversed = nil -%}
+{%- assign activation_second_level_reversed = nil -%}
+
+{%- assign activation_title = page.grand_parent | default: page.parent | default: page.title -%}
+{%- assign activation_first_level = activation_pages
+      | where_exp: "item", "item.parent == nil" -%}
+{%- include sorted_pages.html pages = activation_first_level -%}
+{%- for activation_page in sorted_pages -%}
+  {%- if activation_page.title == activation_title -%}
+    {%- assign activation_first_level_index = forloop.index -%}
+    {%- assign activation_first_level_reversed = activation_page.child_nav_order -%}
+    {%- break -%}
+  {%- endif -%}
+{%- endfor -%}
+
+{%- unless activation_first_level_index == nil -%}
+
+{%- if page.grand_parent -%}
+  {%- assign activation_title = page.parent -%}
+  {%- assign activation_second_level = activation_pages
+        | where_exp: "item", "item.grand_parent == nil"
+        | where_exp: "item", "item.parent == page.grand_parent" -%}
+{%- elsif page.parent -%}
+  {%- assign activation_title = page.title -%}
+  {%- assign activation_second_level = activation_pages
+        | where_exp: "item", "item.grand_parent == nil"
+        | where_exp: "item", "item.parent == page.parent" -%}
+{%- endif -%}
+{%- if page.parent -%}
+  {%- include sorted_pages.html pages = activation_second_level -%}
+  {%- for activation_page in sorted_pages -%}
+    {%- if activation_page.title == activation_title -%}
+      {%- assign activation_second_level_index = forloop.index -%}
+      {%- assign activation_second_level_reversed = activation_page.child_nav_order -%}
+      {%- if activation_first_level_reversed -%}
+        {%- assign activation_second_level_index = sorted_pages | size | plus: 1 | minus: activation_second_level_index -%}
+      {%- endif -%}
+      {%- break -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+
+{%- if page.grand_parent -%}
+  {%- assign activation_third_level = activation_pages
+        | where_exp: "item", "item.parent == page.parent"
+        | where_exp: "item", "item.grand_parent == page.grand_parent" -%}
+  {%- include sorted_pages.html pages = activation_third_level -%}
+  {%- assign activation_third_level = sorted_pages -%}
+  {%- for activation_page in sorted_pages -%}
+    {%- if activation_page.title == page.title -%}
+      {%- assign activation_third_level_index = forloop.index -%}
+      {%- if activation_second_level_reversed -%}
+        {%- assign activation_third_level_index = sorted_pages | size | plus: 1 | minus: activation_third_level_index -%}
+      {%- endif -%}
+      {%- break -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+
+{%- unless activation_second_level_index == nil and activation_third_level_index -%}
+
+{%- if page.collection == nil -%}
+
+  {%- capture activation_collection_prefix -%}
+  .site-nav > .nav-list:nth-child(1):not(.nav-category-list) 
+  {%- endcapture -%}
+
+{%- else -%}
+
+  {%- for activation_collection in site.just_the_docs.collections -%}
+    {%- if activation_collection[0] == page.collection -%}
+      {%- assign activation_collection_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"
+          | where_exp:"item", "item.nav_exclude != true"
+          | size -%}
+  {%- 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 %}
+  {%- endcapture -%}
+  
+{%- endif -%}
+
+// Styling for the nav-list-link to the current page:
+{{ activation_collection_prefix }} {
+  > .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 %} {
+    > .nav-list-link {
+      display: block;
+      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,
+// suppressed when a click has deactivated the expander (making the nav-list-item .passive):
+{{ activation_collection_prefix }} {
+  > .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 %} {
+    > .nav-list-expander svg {
+      @if $nav-list-expander-right {
+        transform: rotate(-90deg);
+      } @else {
+        transform: rotate(90deg);
+      }
+    }
+
+    > .nav-list {
+      display: block;
+    }
+  }
+}
+
+// Styling for nav-list-expander for categories:
+.site-nav > .nav-category-list > .nav-list-item:not(.passive) {
+  > .nav-list-expander svg {
+    @if $nav-list-expander-right {
+      transform: rotate(-90deg);
+    } @else {
+      transform: rotate(90deg);
+    }
+  }
+
+  > .nav-list {
+    display: block;
+  }
+}
+
+{%- endunless -%}
+{%- endunless -%}
+{%- endunless -%}

data/_includes/favicon.html

@@ -0,0 +1,23 @@
+{%- comment -%}
+  Include as: {%- include_cached favicon.html -%}
+  Depends on: site.static_files.
+  Results in: HTML for a link to an existing `favicon.ico` file.
+  Overwrites: 
+    file.
+  
+  The endoflife.date site has 226 pages and 3410 static files. @marcwrobel pointed
+  out that the time taken by evaluating the code in this file on every page when
+  building that site was significant, and suggested making it optional. As it is
+  page-independent, it can easily be cached. Doing that reduced the time taken by
+  rendering `_includes/head.html` from 15.294s to 10.760s, thereby reducing the
+  total build time from 26.074s to 21.656s -- a saving of about 17%.
+{%- endcomment -%}
+
+{% for file in site.static_files %}
+  {% if file.path == site.favicon_ico or file.path == '/favicon.ico' %}
+    {% assign favicon = true %}
+  {% endif %}
+{% endfor %}
+{% if favicon %}
+  <link rel="icon" href="{{ site.favicon_ico | default: '/favicon.ico' | relative_url }}" type="image/x-icon">
+{% endif %}

data/_includes/head.html

@@ -1,8 +1,22 @@
+{%- comment -%}
+  Include as: {%- include head.html -%}
+  Depends on: site.ga_tracking, site.ga_tracking_anonymize_ip,
+    site.search_enabled, site.static_files, site.favicon_ico.
+  Results in: HTML for the head element.
+  Includes:
+    head_nav.html, head_custom.html.
+  Overwrites: 
+    ga_tracking_ids, ga_property, file, favicon.
+  Should not be cached, because included files depend on page.
+{%- endcomment -%}
+
 <head>
   <meta charset="UTF-8">
   <meta http-equiv="X-UA-Compatible" content="IE=Edge">
 
   <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
+  
+  {% include head_nav.html %}
 
   {% if site.ga_tracking != nil %}
     {% assign ga_tracking_ids = site.ga_tracking | split: "," %}
@@ -26,14 +40,7 @@
 
   <meta name="viewport" content="width=device-width, initial-scale=1">
 
-  {% for file in site.static_files %}
-    {% if file.path == site.favicon_ico or file.path == '/favicon.ico' %}
-      {% assign favicon = true %}
-    {% endif %}
-  {% endfor %}
-  {% if favicon %}
-    <link rel="icon" href="{{ site.favicon_ico | default: '/favicon.ico' | relative_url }}" type="image/x-icon">
-  {% endif %}
+  {% include_cached favicon.html %}
 
   {% seo %}
 

data/_includes/head_nav.html

@@ -0,0 +1,48 @@
+{%- 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 %}

data/_includes/nav.html

@@ -1,6 +1,6 @@
 {%- comment -%}
-  Include as: {%- include nav.html pages = pages key = key -%}
-  Depends on: include.pages, include.key, page, site.
+  Include as: {%- include_cached nav.html pages=pages -%}
+  Depends on: include.pages.
   Results in: HTML for the navigation panel.
   Includes:
     sorted_pages.html
@@ -15,6 +15,10 @@
 
 {%- include sorted_pages.html pages = nav_pages -%}
 
+{%- comment -%}
+  It might be more efficient to sort the pages at each level separately.
+{%- endcomment -%}
+
 {%- assign first_level_pages = sorted_pages
     | where_exp: "item", "item.parent == nil" -%}
 {%- assign second_level_pages = sorted_pages
@@ -23,84 +27,49 @@
 {%- assign third_level_pages = sorted_pages
     | where_exp: "item", "item.grand_parent != nil" -%}
 
-{%- comment -%}
-  The order of sibling pages in `sorted_pages` determines the order of display of
-  links to them in lists of navigation links.
-
-  Note that Liquid evaluates conditions from right to left (and it does not allow
-  the use of parentheses). Some conditions are not so easy to express clearly...
-
-  For example, consider the following condition:
-
-    C: page.collection = = include.key and
-       page.url = = node.url or
-       page.grand_parent = = node.title or
-       page.parent = = node.title and
-       page.grand_parent = = nil
-
-  Here, `node` is a first-level page. The last part of the condition
-  -- namely: `page.parent = = node.title and page.grand_parent = = nil` --
-  is evaluated first; it holds if and only if `page` is a child of `node`.
-
-  The condition `page.grand_parent = = node.title or ...` holds when
-  `page` is a grandchild of node, OR `...` holds.
-
-  The condition `page.url = = node.url or ...` holds when
-  `page` is `node`, OR `...` holds.
-
-  The condition C: `page.collection = = include.key and ...` holds when we are
-  generating the nav links for a collection that includes `page`, AND `...` holds.
-{%- endcomment -%}
-
 <ul class="nav-list">
 {%- for node in first_level_pages -%}
-    {%- unless node.nav_exclude -%}
-      <li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil %} active{% endif %}">
-        {%- if node.has_children -%}
-        <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ node.title }} category" aria-pressed="{% if page.collection == include.key and page.url == node.url or page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil %}true{% else %}false{% endif %}">
-          <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
-        </button>
-        {%- endif -%}
-        <a href="{{ node.url | relative_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
-        {%- if node.has_children -%}
-          {%- assign children_list = second_level_pages
-                | where: "parent", node.title -%}
-          {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
-            {%- assign children_list = children_list | reverse -%}
+  <li class="nav-list-item">
+    {%- if node.has_children -%}
+    <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ node.title }} category" aria-pressed="false">
+      <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
+    </button>
+    {%- endif -%}
+    <a href="{{ node.url | relative_url }}" class="nav-list-link">{{ node.title }}</a>
+    {%- if node.has_children -%}
+      {%- assign children_list = second_level_pages
+            | where: "parent", node.title -%}
+      {%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
+        {%- assign children_list = children_list | reverse -%}
+      {%- endif -%}
+      <ul class="nav-list">
+      {%- for child in children_list -%}
+        <li class="nav-list-item">
+          {%- if child.has_children -%}
+          <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ child.title }} category" aria-pressed="false">
+            <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
+          </button>
+          {%- endif -%}
+          <a href="{{ child.url | relative_url }}" class="nav-list-link">{{ child.title }}</a>
+          {%- if child.has_children -%}
+            {%- assign grand_children_list = third_level_pages
+                  | where: "parent", child.title
+                  | where: "grand_parent", node.title -%}
+            {%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
+              {%- assign grand_children_list = grand_children_list | reverse -%}
+            {%- endif -%}
+            <ul class="nav-list">
+            {%- for grand_child in grand_children_list -%}
+              <li class="nav-list-item">
+                <a href="{{ grand_child.url | relative_url }}" class="nav-list-link">{{ grand_child.title }}</a>
+              </li>
+            {%- endfor -%}
+            </ul>
           {%- endif -%}
-          <ul class="nav-list">
-          {%- for child in children_list -%}
-            {%- unless child.nav_exclude -%}
-            <li class="nav-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
-              {%- if child.has_children -%}
-                <button class="nav-list-expander btn-reset" aria-label="toggle items in {{ child.title }} category" aria-pressed="{% if page.url == child.url or page.parent == child.title %}true{% else %}false{% endif %}">
-                  <svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
-                </button>
-              {%- endif -%}
-              <a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
-              {%- if child.has_children -%}
-                {%- assign grand_children_list = third_level_pages
-                      | where: "parent", child.title
-                      | where: "grand_parent", node.title -%}
-                {%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
-                  {%- assign grand_children_list = grand_children_list | reverse -%}
-                {%- endif -%}
-                <ul class="nav-list">
-                {%- for grand_child in grand_children_list -%}
-                  {%- unless grand_child.nav_exclude -%}
-                  <li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
-                    <a href="{{ grand_child.url | relative_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
-                  </li>
-                  {%- endunless -%}
-                {%- endfor -%}
-                </ul>
-              {%- endif -%}
-            </li>
-            {%- endunless -%}
-          {%- endfor -%}
-          </ul>
-        {%- endif -%}
-      </li>
-    {%- endunless -%}
+        </li>
+      {%- endfor -%}
+      </ul>
+    {%- endif -%}
+  </li>
 {%- endfor -%}
 </ul>

data/_includes/sorted_pages.html

@@ -1,9 +1,9 @@
 {%- comment -%}
-  Include as: {%- include sorted_pages.html pages = pages -%}
+  Include as: {%- include sorted_pages.html pages=array_of_pages -%}
   Depends on: include.pages.
   Assigns to: sorted_pages.
   Overwrites: 
-    nav_order_pages, title_order_pages, 
+    nav_order_pages, title_order_pages, double_quote, empty_array,
     nav_number_pages, nav_string_pages, nav_order_groups, group,
     title_number_pages, title_string_pages, title_order_groups.
 {%- endcomment -%}
@@ -29,29 +29,55 @@
 {%- endcomment -%}
 
 {%- assign nav_order_pages = include.pages
-    | where_exp: "item", "item.nav_order != nil" -%}
+      | where_exp: "item", "item.nav_order != nil" -%}
 {%- assign title_order_pages = include.pages
-    | where_exp: "item", "item.nav_order == nil" -%}
+      | where_exp: "item", "item.nav_order == nil" -%}
 
 {%- comment -%}
-  Divide the arrays of `nav_order_pages` and `title_order_pages` according to
-  the type of value.
+  First, filter `nav_order_pages` and `title_order_pages` according to the type
+  of value to be used for sorting.
   
-  The first character of the result of `jsonify` is `"` only for strings.
-  Grouping by a single character also ensures the number of groups is small.
+  The first character of the result of filtering with `jsonify` is `"` only for
+  strings. Removing `"` from its `slice : 0` has size 0 for strings and 1 for
+  numbers, so grouping the pages gives at most two groups.
 {%- endcomment -%}
 
-{%- assign nav_number_pages = "" | split: "" -%}
-{%- assign nav_string_pages = "" | split: "" -%}
-{%- assign nav_order_groups = nav_order_pages
-  | group_by_exp: "item", "item.nav_order | jsonify | slice: 0" -%}
-{%- for group in nav_order_groups -%}
-  {%- if group.name == '"' -%}
-    {%- assign nav_string_pages = group.items -%}
-  {%- else -%}
-    {%- assign nav_number_pages = nav_number_pages | concat: group.items -%}
-  {%- endif -%}
-{%- endfor -%}
+{%- assign double_quote = '"' -%}
+{%- assign empty_array = "" | split: "" -%}
+
+{%- assign nav_string_pages = empty_array -%}
+{%- assign nav_number_pages = empty_array -%}
+{%- unless nav_order_pages == empty -%}
+  {%- assign nav_order_groups = nav_order_pages
+        | group_by_exp: "item",
+            "item.nav_order | jsonify | slice: 0 | remove: double_quote | size" -%}
+  {%- for group in nav_order_groups -%}
+    {%- if group.name == 0 -%}
+      {%- assign nav_string_pages = group.items -%}
+    {%- elsif group.name == 1 -%}
+      {%- assign nav_number_pages = group.items -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endunless -%}
+
+{%- assign title_string_pages = empty_array -%}
+{%- assign title_number_pages = empty_array -%}
+{%- unless title_order_pages == empty -%}
+  {%- assign title_order_groups = title_order_pages
+        | group_by_exp: "item",
+            "item.title | jsonify | slice: 0 | remove: double_quote | size" -%}
+  {%- for group in title_order_groups -%}
+    {%- if group.name == 0 -%}
+      {%- assign title_string_pages = group.items -%}
+    {%- elsif group.name == 1 -%}
+      {%- assign title_number_pages = group.items -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endunless -%}
+
+{%- comment -%}
+  Now sort each array of pages separately, then concatenate the sorted arrays.
+{%- endcomment -%}
 
 {%- unless nav_number_pages == empty -%}
   {%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
@@ -65,18 +91,6 @@
   {%- endif -%}
 {%- endunless -%}
 
-{%- assign title_number_pages = "" | split: "" -%}
-{%- assign title_string_pages = "" | split: "" -%}
-{%- assign title_order_groups = title_order_pages
-    | group_by_exp: "item", "item.title | jsonify | slice: 0" -%}
-{%- for group in title_order_groups -%}
-  {%- if group.name == '"' -%}
-    {%- assign title_string_pages = group.items -%}
-  {%- else -%}
-    {%- assign title_number_pages = title_number_pages | concat: group.items -%}
-  {%- endif -%}
-{%- endfor -%}
-
 {%- unless title_number_pages == empty -%}
   {%- assign title_number_pages = title_number_pages | sort: "title" -%}
 {%- endunless -%}
@@ -90,6 +104,6 @@
 {%- endunless -%}
 
 {%- assign sorted_pages = nav_number_pages
-    | concat: nav_string_pages
-    | concat: title_number_pages
-    | concat: title_string_pages -%}
+      | concat: nav_string_pages
+      | concat: title_number_pages
+      | concat: title_string_pages -%}

data/_layouts/default.html

@@ -12,7 +12,7 @@ layout: table_wrappers
   {% include components/sidebar.html %}
   <div class="main" id="top">
     {% include components/header.html %}
-    <div id="main-content-wrap" class="main-content-wrap">
+    <div class="main-content-wrap">
       {% include components/breadcrumbs.html %}
       <div id="main-content" class="main-content">
         <main>

data/_layouts/minimal.html

@@ -9,7 +9,7 @@ layout: table_wrappers
 <body>
   <a class="skip-to-main" href="#main-content">Skip to main content</a>
   {% include icons/icons.html %}
-  <div id="main-content-wrap" class="main-content-wrap" id="top">
+  <div class="main-content-wrap" id="top">
     {% include components/breadcrumbs.html %}
     <div id="main-content" class="main-content" role="main">
       {% if site.heading_anchors != false %}

data/_sass/base.scss

@@ -1,6 +1,10 @@
 // Base element style overrides
 // stylelint-disable selector-no-type, selector-max-type, selector-max-specificity, selector-max-id
 
+:root {
+  color-scheme: $color-scheme;
+}
+
 * {
   box-sizing: border-box;
 }

data/_sass/buttons.scss

@@ -17,7 +17,9 @@
   background-color: $base-button-color;
   border-width: 0;
   border-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
   appearance: none;
 
   &:focus {
@@ -87,7 +89,9 @@
   &:focus {
     text-decoration: none;
     outline: none;
-    box-shadow: inset 0 0 0 2px $grey-dk-100, 0 0 0 3px rgba(blue, 0.25);
+    box-shadow:
+      inset 0 0 0 2px $grey-dk-100,
+      0 0 0 3px rgba(blue, 0.25);
   }
 
   &:focus:hover,

data/_sass/color_schemes/dark.scss

@@ -1,3 +1,4 @@
+$color-scheme: dark;
 $body-background-color: $grey-dk-300;
 $body-heading-color: $grey-lt-000;
 $body-text-color: $grey-lt-300;

data/_sass/color_schemes/light.scss

@@ -1,3 +1,4 @@
+$color-scheme: light !default;
 $body-background-color: $white !default;
 $body-heading-color: $grey-dk-300 !default;
 $body-text-color: $grey-dk-100 !default;

data/_sass/search.scss

@@ -23,7 +23,9 @@
   height: $sp-8;
   overflow: hidden;
   border-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
   transition: height linear #{$transition-duration * 0.5};
 
   @include mq(md) {
@@ -96,7 +98,9 @@
   background-color: $search-background-color;
   border-bottom-right-radius: $border-radius;
   border-bottom-left-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
 
   @include mq(md) {
     top: 100%;
@@ -230,7 +234,9 @@
   background-color: $search-background-color;
   border: 1px solid rgba($link-color, 0.3);
   border-radius: #{$sp-9 * 0.5};
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
   align-items: center;
   justify-content: center;
 }
@@ -244,7 +250,9 @@
   height: 0;
   background-color: rgba(0, 0, 0, 0.3);
   opacity: 0;
-  transition: opacity ease $transition-duration, width 0s $transition-duration,
+  transition:
+    opacity ease $transition-duration,
+    width 0s $transition-duration,
     height 0s $transition-duration;
 }
 
@@ -264,7 +272,9 @@
 
     @include mq(md) {
       width: $search-results-width;
-      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+      box-shadow:
+        0 1px 2px rgba(0, 0, 0, 0.12),
+        0 3px 10px rgba(0, 0, 0, 0.08);
     }
   }
 
@@ -290,7 +300,10 @@
     width: 100%;
     height: 100%;
     opacity: 1;
-    transition: opacity ease $transition-duration, width 0s, height 0s;
+    transition:
+      opacity ease $transition-duration,
+      width 0s,
+      height 0s;
   }
 
   @include mq(md) {

data/_sass/support/_variables.scss

@@ -1,5 +1,6 @@
 // Typography
 
+// prettier-ignore
 $body-font-family: system-ui, -apple-system, blinkmacsystemfont, "Segoe UI",
   roboto, "Helvetica Neue", arial, sans-serif !default;
 $mono-font-family: "SFMono-Regular", menlo, consolas, monospace !default;

data/_sass/support/mixins/_buttons.scss

@@ -4,7 +4,9 @@
   color: $fg;
   background-color: darken($bg, 2%);
   background-image: linear-gradient(lighten($bg, 5%), darken($bg, 2%));
-  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.25), 0 4px 10px rgba(0, 0, 0, 0.12);
+  box-shadow:
+    0 1px 3px rgba(0, 0, 0, 0.25),
+    0 4px 10px rgba(0, 0, 0, 0.12);
 
   &:hover,
   &.zeroclipboard-is-hover {

data/_sass/tables.scss

@@ -8,7 +8,9 @@
   margin-bottom: $sp-5;
   overflow-x: auto;
   border-radius: $border-radius;
-  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.12), 0 3px 10px rgba(0, 0, 0, 0.08);
+  box-shadow:
+    0 1px 2px rgba(0, 0, 0, 0.12),
+    0 3px 10px rgba(0, 0, 0, 0.08);
 }
 
 table {

data/assets/js/just-the-docs.js

@@ -31,13 +31,18 @@ function initNav() {
     }
     if (target) {
       e.preventDefault();
-      target.ariaPressed = target.parentNode.classList.toggle('active');
+      const active = target.parentNode.classList.toggle('active');
+      const passive = target.parentNode.classList.toggle('passive');
+      if (active && passive) target.parentNode.classList.toggle('passive');
+      target.ariaPressed = active;
     }
   });
 
   const siteNav = document.getElementById('site-nav');
   const mainHeader = document.getElementById('main-header');
   const menuButton = document.getElementById('menu-button');
+  
+  disableHeadStyleSheet();
 
   jtd.addEvent(menuButton, 'click', function(e){
     e.preventDefault();
@@ -66,6 +71,14 @@ function initNav() {
   {%- endif %}
 }
 
+// The page-specific <style> in the <head> is needed only when JS is disabled.
+// Moreover, it incorrectly overrides dynamic stylesheets set by setTheme(theme). 
+// The page-specific stylesheet is assumed to have index 1 in the list of stylesheets.
+
+function disableHeadStyleSheet() {
+  document.styleSheets[1].disabled = true;
+}
+
 {%- if site.search_enabled != false %}
 // Site search
 
@@ -461,15 +474,55 @@ jtd.setTheme = function(theme) {
   cssFile.setAttribute('href', '{{ "assets/css/just-the-docs-" | relative_url }}' + theme + '.css');
 }
 
+// Note: pathname can have a trailing slash on a local jekyll server
+// and not have the slash on GitHub Pages
+
+function navLink() {
+  var href = document.location.pathname;
+  if (href.endsWith('/') && href != '/') {
+    href = href.slice(0, -1);
+  }
+  return document.getElementById('site-nav').querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
+}
+
 // Scroll site-nav to ensure the link to the current page is visible
 
 function scrollNav() {
-  const href = document.location.pathname;
-  const siteNav = document.getElementById('site-nav');
-  const targetLink = siteNav.querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
-  if(targetLink){
+  const targetLink = navLink();
+  if (targetLink) {
     const rect = targetLink.getBoundingClientRect();
-    siteNav.scrollBy(0, rect.top - 3*rect.height);
+    document.getElementById('site-nav').scrollBy(0, rect.top - 3*rect.height);
+  }
+}
+
+// Find the nav-list-link that refers to the current page
+// then make it and all enclosing nav-list-item elements active,
+// and make all other folded collections passive
+
+function activateNav() {
+  var target = navLink();
+  if (target) {
+    target.classList.toggle('active', true);
+  }
+  while (target) {
+    while (target && !(target.classList && target.classList.contains('nav-list-item'))) {
+      target = target.parentNode;
+    }
+    if (target) {
+      target.classList.toggle('active', true);
+      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);
+    }
   }
 }
 
@@ -480,6 +533,7 @@ jtd.onReady(function(){
   {%- if site.search_enabled != false %}
   initSearch();
   {%- endif %}
+  activateNav();
   scrollNav();
 });
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: just-the-docs
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.0
 platform: ruby
 authors:
 - Patrick Marsceill
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-07-05 00:00:00.000000000 Z
+date: 2023-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,6 +53,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: jekyll-include-cache
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -89,13 +103,16 @@ files:
 - _includes/components/search_footer.html
 - _includes/components/search_header.html
 - _includes/components/sidebar.html
+- _includes/css/activation.scss.liquid
 - _includes/css/callouts.scss.liquid
 - _includes/css/custom.scss.liquid
 - _includes/css/just-the-docs.scss.liquid
+- _includes/favicon.html
 - _includes/fix_linenos.html
 - _includes/footer_custom.html
 - _includes/head.html
 - _includes/head_custom.html
+- _includes/head_nav.html
 - _includes/header_custom.html
 - _includes/icons/code_copy.html
 - _includes/icons/document.html