just-the-docs 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b96a130e7da963319bffcbfc09ce39881f538bfe8b56f2809251d29ab7aeb40
-  data.tar.gz: 7a1ec7d332331653d64e2adc7e8f157adf4fbb8f0041261f0b165032861b47ca
+  metadata.gz: c8593eb0f4214116b46db9b1904d2585e794db893633690a78e5d77ad12c2b4f
+  data.tar.gz: dc7aa12e6092af9eabe4a5fd5509df6270fb197abcadff2bb4c4cb0a23993b25
 SHA512:
-  metadata.gz: f033dfe192101707e7b6bebea2b6b0628a5d8a401a32bc6adda5bc483b126af8f98efa7eaf51dc62e399d0dfea09d39d96a91cf5c31b4a1c53d07fcb96a1a288
-  data.tar.gz: 5e9203f6620f854339e979b74811f677357baf57746aba62d242ffe1cc1f58de0eff2e8a8596e2377f317d65af6ad8e9b379a6a532e637b7bb32404f068a216e
+  metadata.gz: c7673a1920061a093328ab384a5a23b25f5e7ec0a1759d09280aa89d07fe63e4df66ce343cd27265d7774ebf431cf45bd45b8ef44f91656371a9e121efd22d41
+  data.tar.gz: 39cf8e32b64c2973e9b463c52799c7d56ef57b42d06e46d97d3b92034ccfb131826f6e502e24528051dd067f926cbe5a8373af16a28f1bb0993c960a62e30c7e

data/CHANGELOG.md

@@ -19,6 +19,60 @@ Code changes to `main` that are *not* in the latest release:
 
 - N/A
 
+Docs changes made since the latest release:
+
+- N/A
+
+## Release v0.8.0
+
+Hi folks! This first minor release of 2024 has a short number of changes: a large improvement of build times for large sites, a new keyboard shortcut to focus the search bar, and sidebar navigation bugfixes for "pretty" URLs (with `.html` omitted) and the clickable area on Safari. This release has no explicit breaking changes and should be a straightforward upgrade for most (if not all) users.
+
+### Using Release `v0.8.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.8.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.8.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.8.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.8.0` with the desired release tag.
+
+### New Features
+
+- Added: configurable keyboard shortcut to focus search input by [@kcromanpl-bajra] in [#1411]
+
+### Bugfixes
+
+- Fixed: quicker build by [@pdmosses] in [#1397]
+- Fixed: incorrect navigation when `.html` omitted from URL by [@pdmosses] in [#1374]
+- Fixed: incorrect positioning of clickable area for navigation links on Safari by [@mattxwang] in [#1403]
+
+### Documentation
+
+- Add documentation to "Navigation Structure" on grouping pages with collections by [@mitchnemirov] in [#1390]
+
+### New Contributors
+
+- [@mitchnemirov] made their first contribution in [#1390]
+- [@kcromanpl-bajra] made their first contribution in [#1411]
+
+[@mitchnemirov]: https://github.com/mitchnemirov
+[@kcromanpl-bajra]: https://github.com/kcromanpl-bajra
+
+[#1374]: https://github.com/just-the-docs/just-the-docs/pull/1374
+[#1390]: https://github.com/just-the-docs/just-the-docs/pull/1390
+[#1397]: https://github.com/just-the-docs/just-the-docs/pull/1397
+[#1403]: https://github.com/just-the-docs/just-the-docs/pull/1403
+[#1411]: https://github.com/just-the-docs/just-the-docs/pull/1411
+
 ## 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.

data/_includes/components/breadcrumbs.html

@@ -8,8 +8,91 @@
 
 {%- if page.url != "/" and page.parent -%}
 
-  {%- assign pages_list = site[page.collection] | default: site.html_pages -%}
+{%- capture nav_list_link -%}
+<a href="{{ page.url | relative_url }}" class="nav-list-link">
+{%- endcapture -%}
+
+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html -%}
+{%- endcapture -%}
+
+{%- if site_nav contains nav_list_link -%}
+
+  {%- capture nav_list_simple -%}
+  <ul class="nav-list">
+  {%- endcapture -%}
+
+  {%- capture nav_list_link_class %} class="nav-list-link">
+  {%- endcapture -%}
+
+  {%- capture nav_category -%}
+  <div class="nav-category">
+  {%- endcapture -%}
+
+  {%- assign nav_anchor_splits =
+        site_nav | split: nav_list_link |
+        first | split: nav_category |
+        last | split: "</a>" -%}
+
+  {%- comment -%}
+    The ordinary pages (if any) and the collections pages (if any) are separated by
+    occurrences of nav_category.
+    
+    Any ancestor nav-links of the page are contained in the last group of pages,
+    immediately preceding nav-lists. After splitting at "</a>", the anchor that
+    was split is a potential ancestor link when the following split starts with
+    a nav-list. 
+    
+    The array nav_breadcrumbs is the stack of current potential ancestors of the
+    current page. A split that contains one or more "</ul>"s requires that number
+    of potential ancestors to be popped from the stack.
+    
+    The number of occurrences of a string in nav_split_next is computed by removing
+    them all, then dividing the resulting size difference by the length of the string.
+  {%- endcomment %}
+
+  {%- assign nav_breadcrumbs = "" | split: "" -%}
+
+  {%- for nav_split in nav_anchor_splits -%}
+  {%- unless forloop.last -%}
+
+  {%- assign nav_split_next = nav_anchor_splits[forloop.index] | trim -%}
+
+  {%- assign nav_split_test =
+        nav_split_next | remove_first: nav_list_simple | prepend: nav_list_simple -%}
+  {%- if nav_split_test == nav_split_next -%}
+    {%- assign nav_breadcrumb_link =
+          nav_split | split: "<a " | last | prepend: "<a " |
+          replace: nav_list_link_class, ">" | append: "</a>" -%}
+    {%- assign nav_breadcrumbs = nav_breadcrumbs | push: nav_breadcrumb_link -%}
+  {%- endif -%}
+
+  {%- if nav_split_next contains "</ul>" -%}
+    {%- assign nav_list_end_less = nav_split_next | remove: "</ul>" -%}
+    {%- assign nav_list_end_count =
+          nav_split_next.size | minus: nav_list_end_less.size | divided_by: 5 -%}
+    {% for nav_end_index in (1..nav_list_end_count) %}
+      {%- assign nav_breadcrumbs = nav_breadcrumbs | pop -%}
+    {%- endfor -%}
+  {%- endif -%}
 
+  {%- endunless -%}
+  {%- endfor -%}
+
+  {%- assign nav_parent_link = nav_breadcrumbs[-1] -%}
+  {%- assign nav_grandparent_link = nav_breadcrumbs[-2] -%}
+
+{%- else -%}
+
+  {%- comment -%}
+    Pages whose links are excluded from the main navigation may still have
+    breadcrumbs. Determining them appears to require inspecting the front matter
+    of all the pages in the same group. For sites with 100s of pages, this is too
+    inefficient in Jekyll 3 (also when the for-loop is replaced by where-filters).
+  {%- endcomment -%}
+
+  {%- assign pages_list = site[page.collection] | default: site.html_pages -%}
+  
   {%- assign parent_page = nil -%}
   {%- assign grandparent_page = nil -%}
 
@@ -35,15 +118,25 @@
     {%- endif -%}
 
   {%- endfor -%}
+  
+  {%- capture nav_parent_link -%}
+    <a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a>
+  {%- endcapture -%}
+
+  {%- if page.grand_parent %}
+    {%- capture nav_grandparent_link -%}
+      <a href="{{ grandparent_page.url | relative_url }}">{{ page.grand_parent }}</a>
+    {%- endcapture -%}
+  {%- endif -%}
+
+{%- endif -%}
 
 <nav aria-label="Breadcrumb" class="breadcrumb-nav">
   <ol class="breadcrumb-nav-list">
-  {% if page.parent -%}
-  {%- if page.grand_parent %}
-    <li class="breadcrumb-nav-list-item"><a href="{{ grandparent_page.url | relative_url }}">{{ page.grand_parent }}</a></li>
+  {%- if nav_grandparent_link %}
+    <li class="breadcrumb-nav-list-item">{{ nav_grandparent_link }}</li>
   {%- endif %}
-    <li class="breadcrumb-nav-list-item"><a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a></li>
-  {% endif -%}
+    <li class="breadcrumb-nav-list-item">{{ nav_parent_link }}</li>
     <li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
   </ol>
 </nav>

data/_includes/css/activation.scss.liquid

@@ -1,19 +1,17 @@
 {%- comment -%}
   Include as: {%- include css/activation.scss.liquid -%}
-  Depends on: page, site.
-  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.
+  Depends on: page.
+  Results in: page-dependent CSS rules for inclusion in a style element,
+    which needs to be disabled when JS is enabled.
+  Includes: components/site_nav.html.
   Overwrites: 
-    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_index, activation_collection_prefix, activation_other_collection_prefix.
+    activation_no_nav_link, nav_list_link, site_nav,
+    nav_list, nav_list_end, nav_list_item, nav_category_list,
+    nav_list_link_prefix, nav_splits, nav_split, nav_levels,
+    nav_list_less, nav_list_count, nav_end_less, nav_end_count,
+    nav_index, nav_slice_size,
+    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 used to reduce the build time for such sites.)
 {%- endcomment -%}
 
 {%- comment -%}
@@ -37,89 +35,163 @@
 {%- endif %}
 {% endcapture -%}
 
-{%- if page.title == nil or page.nav_exclude == true -%}
+{%- capture nav_list_link -%}
+<a href="{{ page.url | relative_url }}" class="nav-list-link">
+{%- endcapture -%}
 
-{{ activation_no_nav_link }}
+{%- capture site_nav -%}
+{%- include_cached components/site_nav.html -%}
+{%- endcapture -%}
 
-{%- else -%}
+{%- if site_nav contains nav_list_link -%}
+
+{%- capture nav_list -%}
+<ul class="nav-list
+{%- endcapture -%}
+
+{%- assign nav_list_end = "</ul>" -%}
+
+{%- capture nav_list_item -%}
+<li class="nav-list-item
+{%- endcapture -%}
+
+{%- capture nav_category_list -%}
+<ul class="nav-list nav-category-list">
+{%- endcapture -%}
+
+{%- assign nav_list_link_prefix =
+      site_nav | split: nav_list_link | first | append: nav_list_link -%}
 
-{%- assign activation_pages = site[page.collection]
-      | default: site.html_pages
-      | where_exp: "item", "item.title != nil"
-      | where_exp: "item", "item.nav_exclude != true" -%}
+{%- assign nav_splits =
+      nav_list_link_prefix | split: nav_list_item | pop -%}
 
-{%- 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 nav_levels = "" | split: "" | push: 1 -%}
 
 {%- comment -%}
-  The generated CSS depends on the position of the current page in each level in
-  the navigation.
-{%- endcomment -%}
+  The pattern of occurrences of list and list-item tags in the site_nav string
+  is included in the language defined by the following context-free grammar:
+  
+    site_nav = PAGES? EXTERNALS? COLLECTION*
 
-{%- 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 -%}
+    PAGES = nav_list (nav_list_item PAGES?)+ nav_list_end
 
-{%- if activation_first_level_index == nil -%}
+    EXTERNALS = nav_list nav_list_item+ nav_list_end
 
-{{ activation_no_nav_link }}
+    COLLECTION = nav_list (nav_list_item PAGES?)* nav_list_end
+               | nav_category_list 
+                   nav_list_item nav_list (nav_list_item PAGES?)* nav_list_end
+                 nav_list_end
+  
+  To determine the path in the site_nav to the nav_list_link for the current page,
+  the prefix of nav_list_link in site_nav is split at each nav_list_item to give
+  an array of nav_splits.
+  
+  In site_nav, occurrences of nav_list must be separated by at least one
+  nav_list_item or nav_list_end. Moreover, when a nav_list_end is followed by a
+  nav_list without an intervening nav_list_item, that nav_list must start either
+  a list of external links or a collection. And when a nav_list is followed by a
+  nav_list_end without an intervening nav_list_item, they form an empty collection.
+  
+  nav_levels is the path determined by the previously inspected nav_splits.
+  How many times nav_list and nav_list_end occur in the current nav_split 
+  determines how to update the path.
+  
+  A nav_split can contain any number of empty non-foldable collections.
+  The path element produced by the outer nav_list of a foldable collection is
+  irrelevant; it is set to zero and subsequently removed.
+    
+  The number of occurrences of a string in a nav_split is computed by removing
+  them all, then dividing the resulting size difference by the length of the string.
+  
+  Case analysis on (nav_list_count, nav_list_end_count):
+  
+  - when (0, 0), the nav_split was between two nav_list_items at the same level;
+  
+  - when (0, N+1), all the nav_list_ends in the nav_split are in PAGES or in one
+    COLLECTION;
+    
+  - when (M+1, 0), M must be 0 (because two nav_lists in the same nav_split must
+    be separated by at least one nav_list_end);
+    
+  - when (M+1, N+1), the nav_split must contain either:
+    - the end of PAGES followed by the start of EXTERNALS, or
+    - the end of PAGES followed by the start of a COLLECTION, or
+    - the end of EXTERNALS followed by the start of a COLLECTION, or
+    - the end of one COLLECTION followed by the start of another, or
+    - (in the first nav_split) one or more empty non-foldable COLLECTIONS
+      followed by the start of a COLLECTION.
+    In general, nav_levels[0] here needs to be incremented by nav_list_count.
+    However, a nav_split that contains the end of an empty foldable collection
+    followed by the just the start of a collection has two occurrences of nav_list,
+    and the increment needs to be one less; similarly when the first nav_split
+    starts with an empty non-foldable collection.
+{%- endcomment %}
 
-{%- else -%}
+{%- for nav_split in nav_splits -%}
 
-{%- 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 -%}
+  {%- assign nav_list_less = nav_split | remove: nav_list -%}
+  {%- assign nav_list_count =
+        nav_split.size | minus: nav_list_less.size | 
+        divided_by: nav_list.size -%}
+
+  {%- assign nav_list_end_less = nav_split | remove: nav_list_end -%}
+  {%- assign nav_list_end_count =
+        nav_split.size | minus: nav_list_end_less.size | 
+        divided_by: nav_list_end.size -%}
+
+  {%- if nav_list_count == 0 and nav_list_end_count == 0 -%}
+
+    {%- assign nav_index = nav_levels[-1] | plus: 1 -%}
+    {%- assign nav_levels = nav_levels | pop | push: nav_index -%}
+
+  {%- elsif nav_list_count == 0 and nav_list_end_count >= 1 -%}
+
+    {%- assign nav_slice_size = nav_levels.size | minus: nav_list_end_count -%}
+    {%- assign nav_levels = nav_levels | slice: 0, nav_slice_size -%}
+    {%- assign nav_index = nav_levels[-1] | plus: 1 -%}
+    {%- assign nav_levels = nav_levels | pop | push: nav_index -%}
+
+  {%- elsif nav_list_count == 1 and nav_list_end_count == 0 -%}
+
+    {%- if nav_split contains nav_category_list -%}
+      {%- assign nav_levels = nav_levels | push: 0 -%}
+    {%- else -%}
+      {%- assign nav_levels = nav_levels | push: 1 -%}
     {%- 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 -%}
+  {%- elsif nav_list_count >= 1 and nav_list_end_count >= 1 -%}
+
+    {%- assign nav_index = nav_levels[0] | plus: nav_list_count -%}
+    {%- if nav_levels[-1] == 0 or forloop.first -%}
+      {%- assign nav_index = nav_index | minus: 1 -%}
+    {%- endif -%}
+    {%- assign nav_levels = nav_levels | slice: 0, 0 | push: nav_index -%}
+    {%- if nav_split contains nav_category_list -%}
+      {%- assign nav_levels = nav_levels | push: 0 -%}
+    {%- else -%}
+      {%- assign nav_levels = nav_levels | push: 1 -%}
     {%- endif -%}
-  {%- endfor -%}
+
+  {%- endif -%}
+
+{%- endfor -%}
+
+{%- assign nav_levels = nav_levels | where_exp: "item", "item >= 1" -%}
+
 {%- endif -%}
 
-{%- if activation_second_level_index == nil and activation_third_level_index -%}
+{%- comment -%}
+  The generated CSS depends on the position of the current page in each level in
+  the navigation.
+{%- endcomment -%}
+
+{%- if nav_levels[1] == nil -%}
+
+{{ activation_no_nav_link }}
+
+{%- else -%}
+
+{%- if nav_levels[2] == nil and nav_levels[3] -%}
 
 {{ activation_no_nav_link }}
 
@@ -158,34 +230,14 @@
 
 {%- else -%}
 
-  {%- for activation_collection in site.just_the_docs.collections -%}
-    {%- if activation_collection[0] == page.collection -%}
-      {%- assign activation_index = forloop.index -%}
-      {%- break -%}
-    {%- endif -%}
-  {%- endfor -%}
-
-  {%- 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 > ul:nth-of-type({{ activation_index }})
+  .site-nav > ul:nth-of-type({{ nav_levels[0] }})
   {%- 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 }}))
+  .site-nav > ul:not(:nth-of-type({{ nav_levels[0] }}))
   {%- endcapture -%}
 
 {%- endif -%}
@@ -197,25 +249,25 @@
   and children of the current page.
 {%- endcomment %}
 
-{% if activation_third_level_index -%}
+{% if nav_levels[3] -%}
 
 {{ 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 {
+{{ activation_collection_prefix }} > li > ul > li > ul > li:not(:nth-child({{ nav_levels[3] }})) > a {
   background-image: none;
 }
 
-{%- elsif activation_second_level_index -%}
+{%- elsif nav_levels[2] -%}
 
 {{ 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:not(:nth-child({{ nav_levels[2] }})) > 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:not(:nth-child({{ nav_levels[1] }})) > a,
 {{ activation_collection_prefix }} > li > ul > li > a,
 {{ activation_collection_prefix }} > li > ul > li > ul > li > a {
   background-image: none;
@@ -236,9 +288,9 @@
   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 }})
+{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }})
+{%- if nav_levels[2] %} > ul > li:nth-child({{ nav_levels[2] }})
+{%- if nav_levels[3] %} > ul > li:nth-child({{ nav_levels[3] }})
 {%- endif -%}
 {%- endif %} > a {
   font-weight: 600;
@@ -259,9 +311,9 @@
 {%- 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
+{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }}) > button svg
+{%- if nav_levels[2] -%},
+{{ activation_collection_prefix }} > li:nth-child({{ nav_levels[1] }}) > ul > li:nth-child({{ nav_levels[2] }}) > button svg
 {%- endif %} {
   transform: rotate(-90deg);
 }
@@ -269,13 +321,12 @@
 {%- if site.just_the_docs.collections %}
 .site-nav > ul.nav-category-list > li.nav-list-item > ul.nav-list,
 {% endif -%}
-{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ activation_first_level_index }}) > ul.nav-list
-{%- if activation_second_level_index %},
-{{ 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
+{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ nav_levels[1] }}) > ul.nav-list
+{%- if nav_levels[2] %},
+{{ activation_collection_prefix }} > li.nav-list-item:nth-child({{ nav_levels[1] }}) > ul.nav-list > li.nav-list-item:nth-child({{ nav_levels[2] }}) > ul.nav-list
 {%- endif %} {
   display: block;
 }
 
 {%- endif -%}
 {%- endif -%}
-{%- endif -%}

data/_includes/fix_linenos.html

@@ -1,29 +1,37 @@
 {%- comment -%}
-This file can be used to fix the HTML produced by Jekyll for highlighted
-code with line numbers.
+This file was previously used to "fix" the HTML produced by Jekyll for
+highlighted code with line numbers. While it often resolves layout issues
+from the missing HTML tags, it still generates invalid HTML (by placing
+a `<table>` element within a `<code>` block). As such, we no longer
+recommend using this workaround. For more information, see the
+"Code snippets with line numbers" docs page:
+https://just-the-docs.com/docs/ui-components/code/line-numbers/
+(or, docs/ui-components/line-nos.md/)
 
-It works with `{% highlight some_language linenos %}...{% endhighlight %}`
-and with the Kramdown option to add line numbers to fenced code.
+The next portion of this file, including the comments and the workaround,
+are preserved for backwards comptability.
 
-The implementation was derived from the workaround provided by 
+ACKNOWLEDGEMENTS
+
+The implementation was derived from the workaround provided by
 Dmitry Hrabrov (DeXP) at
 https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901
 
-EXPLANATION
+EXPLANATION (OLD)
 
-The HTML produced by Rouge highlighting with lie numbers is of the form
-`code table`. Jekyll (<= 4.1.1) always wraps the highlighted HTML
+The HTML produced by Rouge highlighting with line numbers is of the form
+`code table`. Jekyll always wraps the highlighted HTML
 with `pre`. This wrapping is not only unnecessary, but also transforms
 the conforming HTML produced by Rouge to non-conforming HTML, which
-results in HTML validation error reports. 
+results in HTML validation error reports.
 
 The fix removes the outer `pre` tags whenever they contain the pattern
 `<table class="rouge-table">`.
-  
+
 Apart from avoiding HTML validation errors, the fix allows the use of
 the [Jekyll layout for compressing HTML](http://jch.penibelst.de),
 which relies on `pre` tags not being nested, according to
-https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842 
+https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-172069842
 
 USAGE
 
@@ -48,7 +56,7 @@ Some code
 
 CAVEATS
 
-The above does not work when `Some code` happens to contain the matched string 
+The above does not work when `Some code` happens to contain the matched string
 `<table class="rouge-table">`.
 
 The use of this file overwrites the variable `fix_linenos_code` with `nil`.

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

@@ -145,6 +145,18 @@ function searchLoaded(index, docs) {
   var currentInput;
   var currentSearchIndex = 0;
 
+  {%- if site.search.focus_shortcut_key %}
+  // add event listener on ctrl + <focus_shortcut_key> for showing the search input
+  jtd.addEvent(document, 'keydown', function (e) {
+    if ((e.ctrlKey || e.metaKey) && e.key === '{{ site.search.focus_shortcut_key }}') {
+      e.preventDefault();
+
+      mainHeader.classList.add('nav-open');
+      searchInput.focus();
+    }
+  });
+  {%- endif %}
+
   function showSearch() {
     document.documentElement.classList.add('search-active');
   }
@@ -487,11 +499,28 @@ jtd.setTheme = function(theme) {
 // and not have the slash on GitHub Pages
 
 function navLink() {
-  var href = document.location.pathname;
-  if (href.endsWith('/') && href != '/') {
-    href = href.slice(0, -1);
+  var pathname = document.location.pathname;
+
+  var navLink = document.getElementById('site-nav').querySelector('a[href="' + pathname + '"]');
+  if (navLink) {
+    return navLink;
   }
-  return document.getElementById('site-nav').querySelector('a[href="' + href + '"], a[href="' + href + '/"]');
+
+  // The `permalink` setting may produce navigation links whose `href` ends with `/` or `.html`.
+  // To find these links when `/` is omitted from or added to pathname, or `.html` is omitted:
+
+  if (pathname.endsWith('/') && pathname != '/') {
+    pathname = pathname.slice(0, -1);
+  }
+
+  if (pathname != '/') {
+    navLink = document.getElementById('site-nav').querySelector('a[href="' + pathname + '"], a[href="' + pathname + '/"], a[href="' + pathname + '.html"]');
+    if (navLink) {
+      return navLink;
+    }
+  }
+
+  return null; // avoids `undefined`
 }
 
 // Scroll site-nav to ensure the link to the current page is visible
@@ -499,8 +528,7 @@ function navLink() {
 function scrollNav() {
   const targetLink = navLink();
   if (targetLink) {
-    const rect = targetLink.getBoundingClientRect();
-    document.getElementById('site-nav').scrollBy(0, rect.top - 3*rect.height);
+    targetLink.scrollIntoView({ block: "center" });
     targetLink.removeAttribute('href');
   }
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: just-the-docs
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Patrick Marsceill
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-25 00:00:00.000000000 Z
+date: 2024-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler