Tweak search to make it less bulky

Bump prettier from 2.0.5 to 2.1.1

.github/release-drafter.yml

@@ -0,0 +1,35 @@
+references:
+  - v+
+  - master
+name-template: 'v$RESOLVED_VERSION 🌈'
+tag-template: 'v$RESOLVED_VERSION'
+categories:
+  - title: '🚀 Features'
+    labels:
+      - 'feature'
+      - 'enhancement'
+  - title: '🐛 Bug Fixes'
+    labels:
+      - 'fix'
+      - 'bugfix'
+      - 'bug'
+  - title: '🧰 Maintenance'
+    label: 
+      - 'chore'
+      - 'dependencies'
+change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
+version-resolver:
+  major:
+    labels:
+      - 'next-major-release'
+  minor:
+    labels:
+      - 'next-minor-release'
+  patch:
+    labels:
+      - 'patch'
+  default: minor
+template: |
+  ## Changes
+
+  $CHANGES

.github/workflows/ci-master.yml

@@ -18,7 +18,7 @@ jobs:
       run: |
         docker run --rm \
         --volume="${{ github.workspace }}:/srv/jekyll" \
-        jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && jekyll build && bundle exec just-the-docs rake search:init"
+        jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
   jekyll-3-8-5:
     name: Build Jekyll site (v3.8.5)
     runs-on: ubuntu-latest
@@ -30,7 +30,7 @@ jobs:
       run: |
         docker run --rm \
         --volume="${{ github.workspace }}:/srv/jekyll" \
-        jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && jekyll build && bundle exec just-the-docs rake search:init"
+        jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
   assets:
     name: Format and test CSS and JS
     runs-on: ubuntu-latest

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
       run: |
         docker run --rm \
         --volume="${{ github.workspace }}:/srv/jekyll" \
-        jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && jekyll build && bundle exec rake search:init"
+        jekyll/builder:latest /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
 
   jekyll-3-8-5:
     name: Build Jekyll site (v3.8.5)
@@ -28,45 +28,17 @@ jobs:
       run: |
         docker run --rm \
         --volume="${{ github.workspace }}:/srv/jekyll" \
-        jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && jekyll build && bundle exec rake search:init"
+        jekyll/builder:3.8.5 /bin/bash -c "gem install bundler && chmod -R 777 /srv/jekyll && bundle install && bundle exec jekyll build && bundle exec rake search:init"
 
   assets:
-    name: Format and test CSS and JS
+    name: Test CSS and JS
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v2
-      # Using this so the this instead of GITHUB_TOKEN so that this workflow can trigger another
-      with:
-        token: ${{ secrets.PAT }} 
     - name: Use Node.js 12.x
       uses: actions/setup-node@v1
       with:
         node-version: '12.x'
-    - name: Extract branch name
-      shell: bash
-      run: echo "##[set-output name=branch;]$(echo ${GITHUB_HEAD_REF#refs/heads/})"
-      id: extract_branch
-
     - run: npm install
-    - run: npm run format
-    - name: Add changed files
-      run: |
-        echo "https://$GITHUB_ACTOR:$GITHUB_TOKEN@github.com/$GITHUB_REPOSITORY.git"
-        git config --global user.email $GITHUB_ACTOR@users.noreply.github.com
-        git config --global user.name $GITHUB_ACTOR
-        echo "extracted branch is ${{ steps.extract_branch.outputs.branch }}"
-        git checkout -b ${{ steps.extract_branch.outputs.branch }}
-        git status
-        git add .
-    - name: Are there any updates?
-      shell: bash
-      run: echo "##[set-output name=status]$(git status -s)"
-      id: is_dirty
-    - name: Commit files
-      if: steps.is_dirty.outputs.status
-      run: |
-        echo ${{ steps.is_dirty.outputs.status }}
-        git commit -m "🎨 Prettier"
-        git push --force --set-upstream "https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" ${{ steps.extract_branch.outputs.branch }}
     - run: npm test

404.html

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Page not found
+title: 404
 permalink: /404
 nav_exclude: true
 search_exclude: true
@@ -8,4 +8,4 @@ search_exclude: true
 
 <h1>Page not found</h1>
 
-<p>The page you requested could not be found. Try using the navigation {% if site.search_enabled %}or search {% endif %}to find what you're looking for or go to this <a href="{{ site.url }}{{ site.baseurl }}">site's home page</a>.</p>
+<p>The page you requested could not be found. Try using the navigation {% if site.search_enabled != false %}or search {% endif %}to find what you're looking for or go to this <a href="{{ '/' | absolute_url }}">site's home page</a>.</p>

Dockerfile

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

README.md

@@ -33,6 +33,10 @@ Or install it yourself as:
 
     $ gem install just-the-docs
 
+Alternatively, you can run it inside Docker while developing your site
+
+    $ docker-compose up
+
 ## Usage
 
 [View the documentation](https://pmarsceill.github.io/just-the-docs/) for usage information.

_config.yml

@@ -19,16 +19,45 @@ baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
 url: "https://pmarsceill.github.io" # the base hostname & protocol for your site, e.g. http://example.com
 
 permalink: pretty
-exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"]
+exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"
+, "docs/tests/"
+]
+
+# Regression tests
+# By default, the pages in /docs/tests are excluded when the ste is built.
+# To include them, comment-out the relevant line above.
+# Uncommenting the following line doesn't work - see https://github.com/jekyll/jekyll/issues/4791
+# include: ["docs/tests/"]
 
 # Set a path/url to a logo that will be displayed instead of the title
 #logo: "/assets/images/just-the-docs.png"
 
 # Enable or disable the site search
+# Supports true (default) or false
 search_enabled: true
-
-# Set the search token separator for hyphenated-word search:
-search_tokenizer_separator: /[\s/]+/
+search:
+  # Split pages into sections that can be searched individually
+  # Supports 1 - 6, default: 2
+  heading_level: 2
+  # Maximum amount of previews per search result
+  # Default: 3
+  previews: 2
+  # Maximum amount of words to display before a matched word in the preview
+  # Default: 5
+  preview_words_before: 3
+  # Maximum amount of words to display after a matched word in the preview
+  # Default: 10
+  preview_words_after: 3
+  # Set the search token separator
+  # Default: /[\s\-/]+/
+  # Example: enable support for hyphenated search words
+  tokenizer_separator: /[\s/]+/
+  # Display the relative url in search results
+  # Supports true (default) or false
+  rel_url: true
+  # Enable or disable the search button that appears in the bottom right corner of every page
+  # Supports true or false (default)
+  button: false
 
 # Enable or disable heading anchors
 heading_anchors: true
@@ -42,8 +71,8 @@ aux_links:
 aux_links_new_tab: false
 
 # Sort order for navigation links
-nav_sort: case_insensitive # default, equivalent to nil
-# nav_sort: case_sensitive # Capital letters sorted before lowercase
+# nav_sort: case_insensitive # default, equivalent to nil
+nav_sort: case_sensitive # Capital letters sorted before lowercase
 
 # Footer content
 # appears at the bottom of every page's main content
@@ -65,6 +94,7 @@ gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub"
 gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
 gh_edit_branch: "master" # the branch that your docs is served from
+# gh_edit_source: docs # the source that your files originate from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
 
 # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
@@ -78,6 +108,11 @@ ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (t
 plugins:
   - jekyll-seo-tag
 
+kramdown:
+  syntax_highlighter_opts:
+    block:
+      line_numbers: false
+
 compress_html:
   clippings: all
   comments: all
@@ -85,3 +120,5 @@ compress_html:
   startings: []
   blanklines: false
   profile: false
+  # ignore:
+  #   envs: all

_includes/fix_linenos.html

@@ -0,0 +1,65 @@
+{%- comment -%}
+This file can be used to fix the HTML produced by Jekyll for highlighted
+code with line numbers.
+
+It works with `{% highlight some_language linenos %}...{% endhighlight %}`
+and with the Kramdown option to add line numbers to fenced code.
+
+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
+
+The HTML produced by Rouge highlighting with lie numbers is of the form
+`code table`. Jekyll (<= 4.1.1) 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. 
+
+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 
+
+USAGE
+
+(Any names can be used for `some_var` and `some_language`.)
+
+{% capture some_var %}
+{% highlight some_language linenos %}
+Some code
+{% endhighlight %}
+{% endcapture %}
+{% include fix_linenos.html code=some_var %}
+
+For code fences:
+
+{% capture some_var %}
+```some_language
+Some code
+```
+{% endcapture %}
+{% assign some_var = some_var | markdownify %}
+{% include fix_linenos.html code=some_var %}
+
+CAVEATS
+
+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`.
+
+{%- endcomment -%}
+
+{% assign fix_linenos_code = include.code %}
+{% if fix_linenos_code contains '<table class="rouge-table">' %}
+  {% assign fix_linenos_code = fix_linenos_code | replace: '<pre class="highlight">', '<pre>' %}
+  {% assign fix_linenos_code = fix_linenos_code | replace: "<pre><code", "<code" %}
+  {% assign fix_linenos_code = fix_linenos_code | replace: "</code></pre>", "</code>" %}
+{% endif %}
+{{ fix_linenos_code }}
+{% assign fix_linenos_code = nil %}

_includes/head.html

@@ -10,9 +10,9 @@
     {% endif %}
   {% endunless %}
 
-  <link rel="shortcut icon" href="{{ 'favicon.ico' | absolute_url }}" type="image/x-icon">
+  <link rel="shortcut icon" href="{{ 'favicon.ico' | relative_url }}" type="image/x-icon">
 
-  <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | absolute_url }}">
+  <link rel="stylesheet" href="{{ '/assets/css/just-the-docs-default.css' | relative_url }}">
 
   {% if site.ga_tracking != nil %}
     <script async src="https://www.googletagmanager.com/gtag/js?id={{ site.ga_tracking }}"></script>
@@ -27,9 +27,9 @@
   {% endif %}
 
   {% if site.search_enabled != false %}
-    <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | absolute_url }}"></script>
+    <script type="text/javascript" src="{{ '/assets/js/vendor/lunr.min.js' | relative_url }}"></script>
   {% endif %}
-  <script type="text/javascript" src="{{ '/assets/js/just-the-docs.js' | absolute_url }}"></script>
+  <script type="text/javascript" src="{{ '/assets/js/just-the-docs.js' | relative_url }}"></script>
 
   <meta name="viewport" content="width=device-width, initial-scale=1">
 

_includes/nav.html

@@ -1,51 +1,100 @@
-<nav role="navigation" aria-label="Main navigation">
-  <ul class="navigation-list">
-    {%- assign ordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order != nil" -%}
-    {%- assign unordered_pages_list = site.html_pages | where_exp:"item", "item.nav_order == nil" -%}
-    {%- if site.nav_sort == 'case_insensitive' -%}
-      {%- assign sorted_ordered_pages_list = ordered_pages_list | sort_natural:"nav_order" -%}
-      {%- assign sorted_unordered_pages_list = unordered_pages_list | sort_natural:"title" -%}
+<ul class="nav-list">
+  {%- assign included_pages = include.pages
+        | where_exp:"item", "item.nav_exclude != true"
+        | where_exp:"item", "item.title != nil" -%}
+
+  {%- comment -%}
+    The values of `title` and `nav_order` can be numbers or strings.
+    Jekyll gives build failures when sorting on mixtures of different types,
+    so numbers and strings need to be sorted separately.
+
+    Here, numbers are sorted by their values, and come before all strings.
+    An omitted `nav_order` value is equivalent to the page's `title` value
+    (except that a numerical `title` value is treated as a string).
+
+    The case-sensitivity of string sorting is determined by `site.nav_sort`.
+  {%- endcomment -%}
+  
+  {%- assign string_ordered_pages = included_pages
+        | where_exp:"item", "item.nav_order == nil" -%}
+  {%- assign nav_ordered_pages = included_pages
+        | where_exp:"item", "item.nav_order != nil"  -%}
+
+  {%- comment -%}
+    The nav_ordered_pages have to be added to number_ordered_pages and
+    string_ordered_pages, depending on the nav_order value.
+    The first character of the jsonify result is `"` only for strings.
+  {%- endcomment -%}
+  {%- assign nav_ordered_groups = nav_ordered_pages
+        | group_by_exp:"item", "item.nav_order | jsonify | slice: 0" -%}
+  {%- assign number_ordered_pages = "" | split:"X" -%}
+  {%- for group in nav_ordered_groups -%}
+    {%- if group.name == '"' -%}
+      {%- assign string_ordered_pages = string_ordered_pages | concat: group.items -%}
     {%- else -%}
-      {%- assign sorted_ordered_pages_list = ordered_pages_list | sort:"nav_order" -%}
-      {%- assign sorted_unordered_pages_list = unordered_pages_list | sort:"title" -%}
+      {%- assign number_ordered_pages = number_ordered_pages | concat: group.items -%}
     {%- endif -%}
-    {%- assign pages_list = sorted_ordered_pages_list | concat: sorted_unordered_pages_list -%}
+  {%- endfor -%}
+  
+  {%- assign sorted_number_ordered_pages = number_ordered_pages | sort:"nav_order" -%}
+  
+  {%- comment -%}
+    The string_ordered_pages have to be sorted by nav_order, and otherwise title
+    (where appending the empty string to a numeric title converts it to a string).
+    After grouping them by those values, the groups are sorted, then the items
+    of each group are concatenated.
+  {%- endcomment -%}
+  {%- assign string_ordered_groups = string_ordered_pages
+        | group_by_exp:"item", "item.nav_order | default: item.title | append:''" -%}
+  {%- if site.nav_sort == 'case_insensitive' -%}
+    {%- assign sorted_string_ordered_groups = string_ordered_groups | sort_natural:"name" -%}
+  {%- else -%}
+    {%- assign sorted_string_ordered_groups = string_ordered_groups | sort:"name" -%}
+  {%- endif -%}
+  {%- assign sorted_string_ordered_pages = "" | split:"X" -%}
+  {%- for group in sorted_string_ordered_groups -%}
+    {%- assign sorted_string_ordered_pages = sorted_string_ordered_pages | concat: group.items -%}
+  {%- endfor -%}
+
+  {%- assign pages_list = sorted_number_ordered_pages | concat: sorted_string_ordered_pages -%}
+  
   {%- for node in pages_list -%}
-      {%- unless node.nav_exclude -%}
-        {%- if node.parent == nil and node.title -%}
-          <li class="navigation-list-item{% if page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
+    {%- if node.parent == nil -%}
+      <li class="nav-list-item{% if page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
         {%- if page.parent == node.title or page.grand_parent == node.title -%}
           {%- assign first_level_url = node.url | absolute_url -%}
         {%- endif -%}
-            <a href="{{ node.url | absolute_url }}" class="navigation-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
+        {%- if node.has_children -%}
+          <a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
+        {%- endif -%}
+        <a href="{{ node.url | absolute_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
         {%- if node.has_children -%}
           {%- assign children_list = pages_list | where: "parent", node.title -%}
-              <ul class="navigation-list-child-list ">
+          <ul class="nav-list ">
           {%- for child in children_list -%}
-                {%- unless child.nav_exclude -%}
-                  <li class="navigation-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
+            <li class="nav-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
               {%- if page.url == child.url or page.parent == child.title -%}
                 {%- assign second_level_url = child.url | absolute_url -%}
               {%- endif -%}
-                    <a href="{{ child.url | absolute_url }}" class="navigation-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
+              {%- if child.has_children -%}
+                <a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
+              {%- endif -%}
+              <a href="{{ child.url | absolute_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
               {%- if child.has_children -%}
                 {%- assign grand_children_list = pages_list | where: "parent", child.title | where: "grand_parent", node.title -%}
-                        <ul class="navigation-list-child-list">
+                <ul class="nav-list">
                 {%- for grand_child in grand_children_list -%}
-                          <li class="navigation-list-item {% if page.url == grand_child.url %} active{% endif %}">
-                            <a href="{{ grand_child.url | absolute_url }}" class="navigation-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
+                  <li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
+                    <a href="{{ grand_child.url | absolute_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
                   </li>
                 {%- endfor -%}
                 </ul>
               {%- endif -%}
             </li>
-                {%- endunless -%}
           {%- endfor -%}
           </ul>
         {%- endif -%}
       </li>
     {%- endif -%}
-      {%- endunless -%}
   {%- endfor -%}
 </ul>
-</nav>

_includes/vendor/anchor_headings.html

@@ -1,18 +1,44 @@
 {% capture headingsWorkspace %}
   {% comment %}
-    Version 1.0.3
+    Copyright (c) 2018 Vladimir "allejo" Jimenez
+
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use,
+    copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following
+    conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+    OTHER DEALINGS IN THE SOFTWARE.
+  {% endcomment %}
+  {% comment %}
+    Version 1.0.7
       https://github.com/allejo/jekyll-anchor-headings
 
     "Be the pull request you wish to see in the world." ~Ben Balter
 
     Usage:
-      {% include anchor_headings.html html=content %}
+      {% include anchor_headings.html html=content anchorBody="#" %}
 
     Parameters:
       * html          (string) - the HTML of compiled markdown generated by kramdown in Jekyll
 
     Optional Parameters:
       * beforeHeading (bool)   : false  - Set to true if the anchor should be placed _before_ the heading's content
+      * anchorAttrs   (string) :  ''    - Any custom HTML attributes that will be added to the `<a>` tag; you may NOT use `href`, `class` or `title`;
+                                          the `%heading%` and `%html_id%` placeholders are available
       * anchorBody    (string) :  ''    - The content that will be placed inside the anchor; the `%heading%` placeholder is available
       * anchorClass   (string) :  ''    - The class(es) that will be used for each anchor. Separate multiple classes with a space
       * anchorTitle   (string) :  ''    - The `title` attribute that will be used for anchors
@@ -42,17 +68,22 @@
     {% assign nextChar = node | replace: '"', '' | strip | slice: 0, 1 %}
     {% assign headerLevel = nextChar | times: 1 %}
 
-    <!-- If the level is cast to 0, it means it's not a h1-h6 tag, so let's try to fix it -->
+    <!-- If the level is cast to 0, it means it's not a h1-h6 tag, so let's see if we need to fix it -->
     {% if headerLevel == 0 %}
-      {% if nextChar != '<' and nextChar != '' %}
+      <!-- Split up the node based on closing angle brackets and get the first one. -->
+      {% assign firstChunk = node | split: '>' | first %}
+
+      <!-- If the first chunk does NOT contain a '<', that means we've broken another HTML tag that starts with 'h' -->
+      {% unless firstChunk contains '<' %}
         {% capture node %}<h{{ node }}{% endcapture %}
-      {% endif %}
+      {% endunless %}
 
       {% capture edited_headings %}{{ edited_headings }}{{ node }}{% endcapture %}
       {% continue %}
     {% endif %}
 
-    {% assign _workspace = node | split: '</h' %}
+    {% capture _closingTag %}</h{{ headerLevel }}>{% endcapture %}
+    {% assign _workspace = node | split: _closingTag %}
     {% assign _idWorkspace = _workspace[0] | split: 'id="' %}
     {% assign _idWorkspace = _idWorkspace[1] | split: '"' %}
     {% assign html_id = _idWorkspace[0] %}
@@ -74,6 +105,10 @@
         {% capture anchor %}{{ anchor }} title="{{ include.anchorTitle | replace: '%heading%', header }}"{% endcapture %}
       {% endif %}
 
+      {% if include.anchorAttrs %}
+        {% capture anchor %}{{ anchor }} {{ include.anchorAttrs | replace: '%heading%', header | replace: '%html_id%', html_id }}{% endcapture %}
+      {% endif %}
+
       {% capture anchor %}<a {{ anchor }}>{{ include.anchorBody | replace: '%heading%', header | default: '' }}</a>{% endcapture %}
 
       <!-- In order to prevent adding extra space after a heading, we'll let the 'anchor' value contain it -->
@@ -93,8 +128,17 @@
           {{ header }}{{ anchor }}
         {% endif %}
         {{ include.bodySuffix }}
-      </h{{ _workspace | last }}
+      </h{{ headerLevel }}>
     {% endcapture %}
+
+    <!--
+    If we have content after the `</hX>` tag, then we'll want to append that here so we don't lost any content.
+    -->
+    {% assign chunkCount = _workspace | size %}
+    {% if chunkCount > 1 %}
+      {% capture new_heading %}{{ new_heading }}{{ _workspace | last }}{% endcapture %}
+    {% endif %}
+
     {% capture edited_headings %}{{ edited_headings }}{{ new_heading }}{% endcapture %}
   {% endfor %}
 {% endcapture %}{% assign headingsWorkspace = '' %}{{ edited_headings | strip }}

_layouts/default.html

@@ -4,47 +4,88 @@ layout: table_wrappers
 
 <!DOCTYPE html>
 
-<html lang="{{ site.lang | default: "en-US" }}">
+<html lang="{{ site.lang | default: 'en-US' }}">
 {% include head.html %}
 <body>
   <svg xmlns="http://www.w3.org/2000/svg" style="display: none;">
-    <symbol id="link" viewBox="0 0 16 16">
+    <symbol id="svg-link" viewBox="0 0 24 24">
       <title>Link</title>
-      <path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path>
+      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link">
+        <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
+      </svg>
+    </symbol>
+    <symbol id="svg-search" viewBox="0 0 24 24">
+      <title>Search</title>
+      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-search">
+        <circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+      </svg>
+    </symbol>
+    <symbol id="svg-menu" viewBox="0 0 24 24">
+      <title>Menu</title>
+      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu">
+        <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line>
+      </svg>
+    </symbol>
+    <symbol id="svg-arrow-right" viewBox="0 0 24 24">
+      <title>Expand</title>
+      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-chevron-right">
+        <polyline points="9 18 15 12 9 6"></polyline>
+      </svg>
+    </symbol>
+    <symbol id="svg-doc" viewBox="0 0 24 24">
+      <title>Document</title>
+      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file">
+        <path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline>
+      </svg>
     </symbol>
   </svg>
 
-  <div class="page-wrap">
   <div class="side-bar">
     <div class="site-header">
-        <a href="{{ site.url }}{{ site.baseurl }}" class="site-title lh-tight">{% include title.html %}</a>
-        <button class="menu-button fs-3 js-main-nav-trigger" data-text-toggle="Hide" type="button">Menu</button>
-      </div>
-
-      <div class="navigation main-nav js-main-nav">
-        {% include nav.html %}
+      <a href="{{ '/' | absolute_url }}" class="site-title lh-tight">{% include title.html %}</a>
+      <a href="#" id="menu-button" class="site-button">
+        <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg>
+      </a>
     </div>
+    <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav">
+      {% 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 %}
+              <div class="nav-category">{{ collection_value.name }}</div>
+            {% endif %}
+            {% include nav.html pages=collection %}
+          {% endif %}
+        {% endfor %}
+      {% else %}
+        {% include nav.html pages=site.html_pages %}
+      {% endif %}
+    </nav>
     <footer class="site-footer">
-        <p class="text-small text-grey-dk-000 mb-4">This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.</p>
+      This site uses <a href="https://github.com/pmarsceill/just-the-docs">Just the Docs</a>, a documentation theme for Jekyll.
     </footer>
   </div>
-    <div class="main-content-wrap js-main-content" tabindex="0">
-      <div class="main-content" id="top">
-        <div class="page-header js-page-header">
+  <div class="main" id="top">
+    <div id="main-header" class="main-header">
       {% if site.search_enabled != false %}
         <div class="search">
           <div class="search-input-wrap">
-              <input type="text" class="js-search-input search-input" tabindex="0" placeholder="Search {{ site.title }}" aria-label="Search {{ site.title }}" autocomplete="off">
-              <svg width="14" height="14" viewBox="0 0 28 28" xmlns="http://www.w3.org/2000/svg" class="search-icon"><title>Search</title><g fill-rule="nonzero"><path d="M17.332 20.735c-5.537 0-10-4.6-10-10.247 0-5.646 4.463-10.247 10-10.247 5.536 0 10 4.601 10 10.247s-4.464 10.247-10 10.247zm0-4c3.3 0 6-2.783 6-6.247 0-3.463-2.7-6.247-6-6.247s-6 2.784-6 6.247c0 3.464 2.7 6.247 6 6.247z"/><path d="M11.672 13.791L.192 25.271 3.02 28.1 14.5 16.62z"/></g></svg>
+            <input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search {{ site.title }}" aria-label="Search {{ site.title }}" autocomplete="off">
+            <label for="search-input" class="search-label"><svg viewBox="0 0 24 24" class="search-icon"><use xlink:href="#svg-search"></use></svg></label>
           </div>
-            <div class="js-search-results search-results-wrap"></div>
+          <div id="search-results" class="search-results"></div>
         </div>
       {% endif %}
-          {% if site.aux_links != nil %}
-            <ul class="list-style-none text-small aux-nav">
+      {% if site.aux_links %}
+        <nav aria-label="Auxiliary" class="aux-nav">
+          <ul class="aux-nav-list">
             {% for link in site.aux_links %}
-                <li class="d-inline-block my-0{% unless forloop.last %} mr-2{% endunless %}">
-                  <a href="{{ link.last }}"
+              <li class="aux-nav-list-item">
+                <a href="{{ link.last }}" class="site-button"
                   {% if site.aux_links_new_tab %}
                   target="_blank" rel="noopener noreferrer"
                   {% endif %}
@@ -54,12 +95,13 @@ layout: table_wrappers
               </li>
             {% endfor %}
           </ul>
+        </nav>
       {% endif %}
     </div>
-        <div class="page">
+    <div id="main-content-wrap" class="main-content-wrap">
       {% unless page.url == "/" %}
         {% if page.parent %}
-              <nav class="breadcrumb-nav">
+          <nav aria-label="Breadcrumb" class="breadcrumb-nav">
             <ol class="breadcrumb-nav-list">
               {% if page.grand_parent %}
                 <li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.grand_parent }}</a></li>
@@ -72,9 +114,9 @@ layout: table_wrappers
           </nav>
         {% endif %}
       {% endunless %}
-          <div id="main-content" class="page-content" role="main">
+      <div id="main-content" class="main-content" role="main">
         {% if site.heading_anchors != false %}
-              {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#link\"></use></svg>" anchorClass="anchor-heading" %}
+          {% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#svg-link\"></use></svg>" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %}
         {% else %}
           {{ content }}
         {% endif %}
@@ -83,13 +125,11 @@ layout: table_wrappers
           <hr>
           <h2 class="text-delta">Table of contents</h2>
           <ul>
-              {%- assign children_list = pages_list | where: "parent", node.title -%}
+            {%- assign children_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%}
             {% for child in children_list %}
-                {% if child.parent == page.title and child.title != page.title and child.grand_parent == page.parent %}
               <li>
                 <a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
               </li>
-                {% endif %}
             {% endfor %}
           </ul>
         {% endif %}
@@ -98,7 +138,7 @@ layout: table_wrappers
           <hr>
           <footer>
             {% if site.back_to_top %}
-              <p><a href="#top">{{ site.back_to_top_text }}</a></p>
+              <p><a href="#top" id="back-to-top">{{ site.back_to_top_text }}</a></p>
             {% endif %}
             {% if site.footer_content != nil %}
               <p class="text-small text-grey-dk-000 mb-0">{{ site.footer_content }}</p>
@@ -111,29 +151,34 @@ layout: table_wrappers
                     Page last modified: <span class="d-inline-block">{{ page.last_modified_date | date: site.last_edit_time_format }}</span>.
                   </p>
                 {% endif %}
-                  {%
-                  if
+                {% if
                   site.gh_edit_link and
                   site.gh_edit_link_text and
                   site.gh_edit_repository and
                   site.gh_edit_branch and
                   site.gh_edit_view_mode
-
                 %}
                   <p class="text-small text-grey-dk-000 mb-0">
-                  <a href="{{ site.gh_edit_repository }}/{{ site.gh_edit_view_mode }}/{{ site.gh_edit_branch }}/{{ page.path }}">{{ site.gh_edit_link_text }}</a>
+                    <a href="{{ site.gh_edit_repository }}/{{ site.gh_edit_view_mode }}/{{ site.gh_edit_branch }}{% if site.gh_edit_source %}/{{ site.gh_edit_source }}{% endif %}/{{ page.path }}" id="edit-this-page">{{ site.gh_edit_link_text }}</a>
                   </p>
                 {% endif %}
               </div>
             {% endif %}
-
           </footer>
         {% endif %}
 
       </div>
     </div>
-    </div>
-  </div>
 
+    {% if site.search_enabled != false %}
+      {% if site.search.button %}
+        <a href="#" id="search-button" class="search-button">
+          <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-search"></use></svg>
+        </a>
+      {% endif %}
+
+      <div class="search-overlay"></div>
+    {% endif %}
+  </div>
 </body>
 </html>

_sass/code.scss

@@ -11,24 +11,96 @@ code {
   border-radius: $border-radius;
 }
 
-pre.highlight,
-figure.highlight {
+// Content structure for highlighted code blocks using fences or Liquid
+//
+// ```[LANG]...```, no kramdown line_numbers:
+//   div.[language-LANG.]highlighter-rouge > div.highlight > pre.highlight > code
+//
+// ```[LANG]...```, kramdown line_numbers = true:
+//   div.[language-LANG.]highlighter-rouge > div.highlight > pre.highlight > code
+//   > div.table-wrapper > table.rouge-table > tbody > tr
+//   > td.rouge-gutter.gl > pre.lineno
+//   | td.rouge-code > pre
+//
+// {% highlight LANG %}...{% endhighlight %}:
+//   figure.highlight > pre > code.language-LANG
+//
+// {% highlight LANG linenos %}...{% endhighlight %}:
+//   figure.highlight > pre > code.language-LANG
+//   > div.table-wrapper > table.rouge-table > tbody > tr
+//   > td.gutter.gl > pre.lineno
+//   | td.code > pre
+//
+// fix_linenos removes the outermost pre when it encloses table.rouge-table
+//
+// See docs/index-test.md for some tests.
+//
+// No kramdown line_numbers: fences and Liquid highlighting look the same.
+// Kramdown line_numbers = true: fences have a wider gutter than with Liquid?
+
+// ```[LANG]...```
+div.highlighter-rouge {
   padding: $sp-3;
   margin-top: 0;
-  margin-bottom: 0;
-  -webkit-overflow-scrolling: touch;
+  margin-bottom: $sp-3;
   background-color: $code-background-color;
+  border-radius: $border-radius;
+  box-shadow: none;
+  -webkit-overflow-scrolling: touch;
 
+  div.highlight,
+  pre.highlight,
   code {
     padding: 0;
+    margin: 0;
     border: 0;
   }
 }
 
-.highlighter-rouge {
+// {% highlight LANG %}...{% endhighlight %},
+// {% highlight LANG linenos %}...{% endhighlight %}:
+figure.highlight {
+  padding: $sp-3;
+  margin-top: 0;
   margin-bottom: $sp-3;
-  overflow: hidden;
+  background-color: $code-background-color;
   border-radius: $border-radius;
+  box-shadow: none;
+  -webkit-overflow-scrolling: touch;
+
+  pre,
+  code {
+    padding: 0;
+    margin: 0;
+    border: 0;
+  }
+}
+
+// ```[LANG]...```, kramdown line_numbers = true,
+// {% highlight LANG linenos %}...{% endhighlight %}:
+.highlight .table-wrapper {
+  padding: 0;
+  margin: 0;
+  border: 0;
+  box-shadow: none;
+
+  td,
+  pre {
+    @include fs-2;
+    min-width: 0;
+    padding: 0;
+    background-color: $code-background-color;
+    border: 0;
+  }
+
+  td.gl {
+    padding-right: $sp-3;
+  }
+
+  pre {
+    margin: 0;
+    line-height: 2;
+  }
 }
 
 .highlight .c {

_sass/color_schemes/dark.scss

@@ -14,3 +14,4 @@ $base-button-color: $grey-dk-250;
 $code-background-color: $grey-dk-250;
 $search-background-color: $grey-dk-250;
 $table-background-color: $grey-dk-250;
+$feedback-color: darken($sidebar-color, 3%);

_sass/content.scss

@@ -5,7 +5,7 @@
 //
 // stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type
 
-.page-content {
+.main-content {
   line-height: $content-line-height;
 
   ol,
@@ -109,7 +109,7 @@
 
   dl {
     display: grid;
-    grid-template-columns: max-content 1fr;
+    grid-template: auto / 10em 1fr;
   }
 
   dt,
@@ -118,16 +118,18 @@
   }
 
   dt {
+    grid-column: 1;
+    font-weight: 500;
     text-align: right;
-
     &::after {
       content: ":";
     }
   }
 
   dd {
+    grid-column: 2;
+    margin-bottom: 0;
     margin-left: 1em;
-    font-weight: 500;
   }
 
   .anchor-heading {
@@ -148,7 +150,7 @@
       display: inline-block;
       width: 100%;
       height: 100%;
-      fill: $link-color;
+      color: $link-color;
       visibility: hidden;
     }
   }
@@ -165,6 +167,10 @@
     }
   }
 
+  summary {
+    cursor: pointer;
+  }
+
   h1,
   h2,
   h3,

_sass/layout.scss

@@ -2,28 +2,15 @@
 // The basic two column layout
 //
 
-.page-wrap {
-  @include mq(md) {
-    position: absolute;
-    top: 0;
-    left: 0;
-    display: flex;
-    width: 100%;
-    height: 100%;
-    overflow-x: hidden;
-    overflow-y: hidden;
-  }
-}
-
 .side-bar {
-  z-index: 100;
+  z-index: 0;
   display: flex;
   flex-wrap: wrap;
   background-color: $sidebar-color;
 
   @include mq(md) {
     flex-wrap: nowrap;
-    position: absolute;
+    position: fixed;
     width: $nav-width-md;
     height: 100%;
     flex-direction: column;
@@ -37,20 +24,7 @@
   }
 }
 
-.main-content-wrap {
-  @include mq(md) {
-    position: absolute;
-    top: 0;
-    left: 0;
-    width: 100%;
-    height: 100%;
-    -webkit-overflow-scrolling: touch;
-    overflow-x: hidden;
-    overflow-y: scroll;
-  }
-}
-
-.main-content {
+.main {
   @include mq(md) {
     position: relative;
     max-width: $content-width;
@@ -64,11 +38,7 @@
   }
 }
 
-.js-main-content:focus {
-  outline: none;
-}
-
-.page {
+.main-content-wrap {
   @include container;
   padding-top: $gutter-spacing-sm;
   padding-bottom: $gutter-spacing-sm;
@@ -79,16 +49,14 @@
   }
 }
 
-.page-header {
-  @include container;
+.main-header {
+  z-index: 0;
   display: none;
-  padding-top: $gutter-spacing-sm;
-  padding-bottom: $gutter-spacing-sm;
   background-color: $sidebar-color;
 
   @include mq(md) {
     display: flex;
-    justify-content: flex-end;
+    justify-content: space-between;
     height: $header-height;
     background-color: $body-background-color;
     border-bottom: $border $border-color;
@@ -103,7 +71,7 @@
   }
 }
 
-.navigation,
+.site-nav,
 .site-header,
 .site-footer {
   width: 100%;
@@ -113,10 +81,15 @@
   }
 }
 
-.navigation {
-  @include container;
+.site-nav {
+  display: none;
+
+  &.nav-open {
+    display: block;
+  }
 
   @include mq(md) {
+    display: block;
     padding-top: $sp-8;
     padding-bottom: $gutter-spacing-sm;
     overflow-y: auto;
@@ -130,7 +103,6 @@
   align-items: center;
 
   @include mq(md) {
-    z-index: 101;
     height: $header-height;
     max-height: $header-height;
     border-bottom: $border $border-color;
@@ -165,27 +137,42 @@
   }
 }
 
-.menu-button {
-  appearance: none;
+.site-button {
   display: flex;
   height: 100%;
   padding: $gutter-spacing-sm;
   align-items: center;
-  color: $link-color;
-  text-transform: uppercase;
-  background: transparent;
-  border: 0;
+}
 
 @include mq(md) {
+  .site-header .site-button {
     display: none;
   }
 }
 
+.site-title:hover {
+  background-image: linear-gradient(
+    -90deg,
+    rgba($feedback-color, 1) 0%,
+    rgba($feedback-color, 0.8) 80%,
+    rgba($feedback-color, 0) 100%
+  );
+}
+
+.site-button:hover {
+  background-image: linear-gradient(
+    -90deg,
+    rgba($feedback-color, 1) 0%,
+    rgba($feedback-color, 0.8) 100%
+  );
+}
+
 // stylelint-disable selector-max-type
 
 body {
   position: relative;
   padding-bottom: $sp-10;
+  overflow-y: scroll;
 
   @include mq(md) {
     position: static;
@@ -202,9 +189,17 @@ body {
   left: 0;
   padding-top: $sp-4;
   padding-bottom: $sp-4;
+  color: $grey-dk-000;
+  @include fs-2;
 
   @include mq(md) {
     position: static;
     justify-self: end;
   }
 }
+
+.icon {
+  width: $sp-5;
+  height: $sp-5;
+  color: $link-color;
+}

_sass/modules.scss

@@ -17,3 +17,4 @@
 @import "./tables";
 @import "./code";
 @import "./utilities/utilities";
+@import "./print";

_sass/navigation.scss

@@ -1,89 +1,188 @@
 //
 // Main nav, breadcrumb, etc...
 //
-.navigation-list {
+// stylelint-disable selector-no-type, max-nesting-depth, selector-max-compound-selectors, selector-max-type, selector-max-specificity
+
+.nav-list {
   padding: 0;
   margin-top: 0;
   margin-bottom: 0;
   list-style: none;
-}
 
-.navigation-list-child-list {
-  padding-left: $sp-3;
-  list-style: none;
-
-  .navigation-list-link {
-    color: $nav-child-link-color;
-  }
-
-  .navigation-list-item {
-    position: relative;
-
-    &::before {
-      position: absolute;
-      margin-top: 0.3em;
-      margin-left: -0.8em;
-      color: rgba($body-text-color, 0.3);
-      content: "- ";
-    }
-
-    &.active {
-      &::before {
-        color: $body-text-color;
-      }
-    }
-  }
-}
-
-.navigation-list-item {
+  .nav-list-item {
     @include fs-4;
+    position: relative;
     margin: 0;
 
     @include mq(md) {
       @include fs-3;
     }
 
-  .navigation-list-child-list {
-    display: none;
-  }
-
-  &.active {
-    .navigation-list-child-list {
-      display: block;
-    }
-  }
-}
-
-.navigation-list-link {
+    .nav-list-link {
       display: block;
+      min-height: $nav-list-item-height-sm;
       padding-top: $sp-1;
       padding-bottom: $sp-1;
+      line-height: #{$nav-list-item-height-sm - 2 * $sp-1};
+      @if $nav-list-expander-right {
+        padding-right: $nav-list-item-height-sm;
+        padding-left: $gutter-spacing-sm;
+      } @else {
+        padding-right: $gutter-spacing-sm;
+        padding-left: $nav-list-item-height-sm;
+      }
+
+      @include mq(md) {
+        min-height: $nav-list-item-height;
+        line-height: #{$nav-list-item-height - 2 * $sp-1};
+        @if $nav-list-expander-right {
+          padding-right: $nav-list-item-height;
+          padding-left: $gutter-spacing;
+        } @else {
+          padding-right: $gutter-spacing;
+          padding-left: $nav-list-item-height;
+        }
+      }
 
       &.active {
         font-weight: 600;
-    color: $body-heading-color;
         text-decoration: none;
       }
+
+      &:hover,
+      &.active {
+        background-image: linear-gradient(
+          -90deg,
+          rgba($feedback-color, 1) 0%,
+          rgba($feedback-color, 0.8) 80%,
+          rgba($feedback-color, 0) 100%
+        );
+      }
     }
 
-// Small screen nav
-
-.main-nav {
-  display: none;
-
-  &.nav-open {
-    display: block;
+    .nav-list-expander {
+      position: absolute;
+      @if $nav-list-expander-right {
+        right: 0;
       }
+      width: $nav-list-item-height-sm;
+      height: $nav-list-item-height-sm;
+      padding-top: #{$nav-list-item-height-sm / 4};
+      padding-right: #{$nav-list-item-height-sm / 4};
+      padding-bottom: #{$nav-list-item-height-sm / 4};
+      padding-left: #{$nav-list-item-height-sm / 4};
+      color: $link-color;
+
       @include mq(md) {
+        width: $nav-list-item-height;
+        height: $nav-list-item-height;
+        padding-top: #{$nav-list-item-height / 4};
+        padding-right: #{$nav-list-item-height / 4};
+        padding-bottom: #{$nav-list-item-height / 4};
+        padding-left: #{$nav-list-item-height / 4};
+      }
+
+      &:hover {
+        background-image: linear-gradient(
+          -90deg,
+          rgba($feedback-color, 1) 0%,
+          rgba($feedback-color, 0.8) 100%
+        );
+      }
+
+      @if $nav-list-expander-right {
+        svg {
+          transform: rotate(90deg);
+        }
+      }
+    }
+
+    > .nav-list {
+      display: none;
+      padding-left: $sp-3;
+      list-style: none;
+
+      .nav-list-item {
+        position: relative;
+
+        .nav-list-link {
+          color: $nav-child-link-color;
+        }
+
+        .nav-list-expander {
+          color: $nav-child-link-color;
+        }
+      }
+    }
+
+    &.active {
+      > .nav-list-expander svg {
+        @if $nav-list-expander-right {
+          transform: rotate(-90deg);
+        } @else {
+          transform: rotate(90deg);
+        }
+      }
+
+      > .nav-list {
         display: block;
       }
     }
+  }
+}
+
+.nav-category {
+  padding-top: $sp-2;
+  padding-right: $gutter-spacing-sm;
+  padding-bottom: $sp-2;
+  padding-left: $gutter-spacing-sm;
+  font-weight: 600;
+  text-align: end;
+  text-transform: uppercase;
+  border-bottom: $border $border-color;
+  @include fs-2;
+
+  @include mq(md) {
+    padding-right: $gutter-spacing;
+    padding-left: $gutter-spacing;
+    margin-top: $gutter-spacing-sm;
+    text-align: start;
+
+    &:first-child {
+      margin-top: 0;
+    }
+  }
+}
+
+// Aux nav
 
 .aux-nav {
-  align-self: center;
+  height: 100%;
+  overflow-x: auto;
+  @include fs-2;
+
+  .aux-nav-list {
+    display: flex;
+    height: 100%;
+    padding: 0;
+    margin: 0;
+    list-style: none;
+  }
+
+  .aux-nav-list-item {
+    display: inline-block;
+    height: 100%;
+    padding: 0;
+    margin: 0;
+  }
+
+  @include mq(md) {
+    padding-right: $gutter-spacing-sm;
+  }
 }
 
 // Breadcrumb nav
+
 .breadcrumb-nav {
   @include mq(md) {
     margin-top: -$sp-4;

_sass/print.scss

@@ -0,0 +1,40 @@
+// stylelint-disable selector-max-specificity, selector-max-id, selector-max-type, selector-no-qualifying-type, primer/no-override,
+
+@media print {
+  .site-footer,
+  .site-button,
+  #edit-this-page,
+  #back-to-top,
+  .site-nav,
+  .main-header {
+    display: none !important;
+  }
+
+  .side-bar {
+    width: 100%;
+    height: auto;
+    border-right: 0 !important;
+  }
+
+  .site-header {
+    border-bottom: 1px solid $border-color;
+  }
+
+  .site-title {
+    font-size: $root-font-size !important;
+    font-weight: 700 !important;
+  }
+
+  .text-small {
+    font-size: 8pt !important;
+  }
+
+  pre.highlight {
+    border: 1px solid $border-color;
+  }
+
+  .main {
+    max-width: none;
+    margin-left: 0;
+  }
+}

_sass/search.scss

@@ -4,91 +4,115 @@
 
 .search {
   position: relative;
-  z-index: 99;
+  z-index: 2;
   flex-grow: 1;
-  height: 100%;
-  margin-bottom: $sp-3;
+  height: $sp-10;
+  padding: $sp-2;
+  transition: padding linear #{$transition-duration / 2};
 
   @include mq(md) {
-    margin-bottom: 0;
+    position: relative !important;
+    width: auto !important;
+    height: 100% !important;
+    padding: 0;
+    transition: none;
   }
 }
 
 .search-input-wrap {
-  display: flex;
-  height: 100%;
-  padding: $sp-2;
-  background-color: $search-background-color;
+  position: relative;
+  z-index: 1;
+  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);
+  transition: height linear #{$transition-duration / 2};
 
   @include mq(md) {
-    padding-top: 0;
-    padding-right: 0;
-    padding-bottom: 0;
-    padding-left: 0;
-    background-color: $body-background-color;
+    position: absolute;
+    width: 100%;
+    max-width: $search-results-width;
+    height: 100% !important;
     border-radius: 0;
     box-shadow: none;
+    transition: width ease $transition-duration;
   }
 }
 
 .search-input {
-  align-self: center;
+  position: absolute;
   width: 100%;
-  padding-top: $sp-1;
-  padding-bottom: $sp-1;
+  height: 100%;
+  padding-top: $sp-2;
+  padding-right: $gutter-spacing-sm;
+  padding-bottom: $sp-2;
+  padding-left: #{$gutter-spacing-sm + $sp-5};
+  font-size: 16px;
   background-color: $search-background-color;
   border-top: 0;
   border-right: 0;
   border-bottom: 0;
   border-left: 0;
-  order: 2;
-  @include fs-4;
+  border-radius: 0;
+
+  @include mq(md) {
+    padding-top: $gutter-spacing-sm;
+    padding-bottom: $gutter-spacing-sm;
+    padding-left: #{$gutter-spacing + $sp-5};
+    font-size: 14px;
+    background-color: $body-background-color;
+    transition: padding-left linear #{$transition-duration / 2};
+  }
 
   &:focus {
     outline: 0;
-    box-shadow: none;
 
-    + .search-icon {
-      fill: $link-color;
+    + .search-label .search-icon {
+      color: $link-color;
     }
   }
+}
+
+.search-label {
+  position: absolute;
+  display: flex;
+  height: 100%;
+  padding-left: $gutter-spacing-sm;
 
   @include mq(md) {
-    background-color: $body-background-color;
-    @include fs-3;
-  }
+    padding-left: $gutter-spacing;
+    transition: padding-left linear #{$transition-duration / 2};
   }
 
   .search-icon {
+    width: #{$sp-4 * 1.2};
+    height: #{$sp-4 * 1.2};
     align-self: center;
-  margin-right: $sp-2;
-  fill: $grey-dk-000;
-  order: 1;
+    color: $grey-dk-000;
+  }
 }
 
-.search-results-wrap {
+.search-results {
   position: absolute;
-  z-index: 100;
+  left: 0;
   display: none;
   width: 100%;
-  background: $search-background-color;
-  border-radius: $border-radius;
+  max-height: calc(100% - #{$sp-10});
+  overflow-y: auto;
+  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);
 
-  &.active {
-    display: block;
-  }
-
   @include mq(md) {
+    top: 100%;
     width: $search-results-width;
+    max-height: calc(100vh - 200%) !important;
   }
 }
 
 .search-results-list {
   padding-left: 0;
-  margin-top: $sp-1;
   margin-bottom: $sp-1;
   list-style: none;
   @include fs-4;
@@ -112,31 +136,58 @@
 
   &:hover,
   &.active {
-    background-color: $sidebar-color;
-  }
-
-  @include mq(md) {
-    padding-right: $sp-4;
-    padding-left: $sp-4;
+    background-color: $feedback-color;
   }
 }
 
 .search-result-title {
   display: block;
   padding-top: $sp-2;
-  padding-right: $sp-4;
   padding-bottom: $sp-2;
 
   @include mq(sm) {
     display: inline-block;
     width: 40%;
-    word-wrap: break-word;
+    padding-right: $sp-2;
     vertical-align: top;
   }
 }
 
+.search-result-doc {
+  display: flex;
+  align-items: center;
+  word-wrap: break-word;
+
+  &.search-result-doc-parent {
+    opacity: 0.5;
+    @include fs-3;
+
+    @include mq(md) {
+      @include fs-2;
+    }
+  }
+
+  .search-result-icon {
+    width: $sp-4;
+    height: $sp-4;
+    margin-right: $sp-2;
+    color: $link-color;
+    flex-shrink: 0;
+  }
+
+  .search-result-doc-title {
+    overflow: auto;
+  }
+}
+
+.search-result-section {
+  margin-left: #{$sp-4 + $sp-2};
+  word-wrap: break-word;
+}
+
 .search-result-rel-url {
   display: block;
+  margin-left: #{$sp-4 + $sp-2};
   overflow: hidden;
   color: $search-result-preview-color;
   text-overflow: ellipsis;
@@ -144,12 +195,14 @@
   @include fs-1;
 }
 
-.search-result-preview {
+.search-result-previews {
   display: block;
   padding-top: $sp-2;
   padding-bottom: $sp-2;
   padding-left: $sp-4;
+  margin-left: $sp-2;
   color: $search-result-preview-color;
+  word-wrap: break-word;
   border-left: $border;
   border-left-color: $border-color;
   @include fs-2;
@@ -157,11 +210,114 @@
   @include mq(sm) {
     display: inline-block;
     width: 60%;
+    padding-left: $sp-2;
+    margin-left: 0;
     vertical-align: top;
   }
 }
 
+.search-result-preview + .search-result-preview {
+  margin-top: $sp-1;
+}
+
 .search-result-highlight {
   font-weight: bold;
-  color: $link-color;
+}
+
+.search-no-result {
+  padding-top: $sp-2;
+  padding-right: $sp-3;
+  padding-bottom: $sp-2;
+  padding-left: $sp-3;
+  @include fs-3;
+}
+
+.search-button {
+  position: fixed;
+  right: $sp-4;
+  bottom: $sp-4;
+  display: flex;
+  width: $sp-9;
+  height: $sp-9;
+  background-color: $search-background-color;
+  border: 1px solid rgba($link-color, 0.3);
+  border-radius: #{$sp-9 / 2};
+  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;
+}
+
+.search-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 1;
+  width: 0;
+  height: 0;
+  background-color: rgba(0, 0, 0, 0.3);
+  opacity: 0;
+  transition: opacity ease $transition-duration, width 0s $transition-duration,
+    height 0s $transition-duration;
+}
+
+.search-active {
+  .search {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    padding: 0;
+  }
+
+  .search-input-wrap {
+    height: $sp-10;
+    border-radius: 0;
+
+    @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);
+    }
+  }
+
+  .search-input {
+    background-color: $search-background-color;
+
+    @include mq(md) {
+      padding-left: 2.3rem;
+    }
+  }
+
+  .search-label {
+    @include mq(md) {
+      padding-left: 0.6rem;
+    }
+  }
+
+  .search-results {
+    display: block;
+  }
+
+  .search-overlay {
+    width: 100%;
+    height: 100%;
+    opacity: 1;
+    transition: opacity ease $transition-duration, width 0s, height 0s;
+  }
+
+  @include mq(md) {
+    .main {
+      position: fixed;
+      right: 0;
+      left: 0;
+    }
+  }
+
+  .main-header {
+    padding-top: $sp-10;
+
+    @include mq(md) {
+      padding-top: 0;
+    }
+  }
 }

_sass/support/_variables.scss

@@ -2,14 +2,32 @@
 // Typography
 //
 
-$body-font-family: -apple-system, BlinkMacSystemFont, "helvetica neue",
-  helvetica, roboto, noto, "segoe ui", arial, sans-serif !default;
+$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;
 $root-font-size: 16px !default; // Base font-size for rems
 $body-line-height: 1.4 !default;
 $content-line-height: 1.6 !default;
 $body-heading-line-height: 1.25 !default;
 
+//
+// Font size
+// `-sm` suffix is the size at the small (and above) media query
+//
+
+$font-size-1: 9px !default;
+$font-size-1-sm: 10px !default;
+$font-size-2: 11px !default; //h4 - uppercased!, h6 not uppercased, text-small
+$font-size-3: 12px !default; //h5
+$font-size-4: 14px !default;
+$font-size-5: 16px !default; //h3
+$font-size-6: 18px !default; //h2
+$font-size-7: 24px !default;
+$font-size-8: 32px !default; //h1
+$font-size-9: 36px !default;
+$font-size-10: 42px !default;
+$font-size-10-sm: 48px !default;
+
 //
 // Colors
 //
@@ -57,6 +75,7 @@ $sidebar-color: $grey-lt-000 !default;
 $search-background-color: $white !default;
 $table-background-color: $white !default;
 $code-background-color: $grey-lt-000 !default;
+$feedback-color: darken($sidebar-color, 3%) !default;
 
 $body-text-color: $grey-dk-100 !default;
 $body-heading-color: $grey-dk-300 !default;
@@ -94,8 +113,8 @@ $sp-5: map-get($spacers, sp-5) !default; // 1.5  rem == 24px
 $sp-6: map-get($spacers, sp-6) !default; // 2    rem == 32px
 $sp-7: map-get($spacers, sp-7) !default; // 2.5  rem == 40px
 $sp-8: map-get($spacers, sp-8) !default; // 3    rem == 48px
-$sp-9: map-get($spacers, sp-9) !default; // 4    rem == 48px
-$sp-10: map-get($spacers, sp-10) !default; // 4.5  rem == 48px
+$sp-9: map-get($spacers, sp-9) !default; // 3.5  rem == 56px
+$sp-10: map-get($spacers, sp-10) !default; // 4  rem == 64px
 
 //
 // Borders
@@ -113,9 +132,13 @@ $gutter-spacing: $sp-6 !default;
 $gutter-spacing-sm: $sp-4 !default;
 $nav-width: 264px !default;
 $nav-width-md: 248px !default;
+$nav-list-item-height: $sp-6 !default;
+$nav-list-item-height-sm: $sp-8 !default;
+$nav-list-expander-right: true;
 $content-width: 800px !default;
 $header-height: 60px !default;
-$search-results-width: 500px !default;
+$search-results-width: $content-width - $nav-width !default;
+$transition-duration: 400ms;
 
 //
 // Media queries in pixels

_sass/support/mixins/_typography.scss

@@ -1,86 +1,84 @@
-// Font size
-
 @mixin fs-1 {
-  font-size: 9px !important;
+  font-size: $font-size-1 !important;
 
   @include mq(sm) {
-    font-size: 10px !important;
+    font-size: $font-size-1-sm !important;
   }
 }
 
 @mixin fs-2 {
-  font-size: 11px !important;
+  font-size: $font-size-2 !important;
 
   @include mq(sm) {
-    font-size: 12px !important;
+    font-size: $font-size-3 !important;
   }
 }
 
 @mixin fs-3 {
-  font-size: 12px !important;
+  font-size: $font-size-3 !important;
 
   @include mq(sm) {
-    font-size: 14px !important;
+    font-size: $font-size-4 !important;
   }
 }
 
 @mixin fs-4 {
-  font-size: 15px !important;
+  font-size: $font-size-4 !important;
 
   @include mq(sm) {
-    font-size: 16px !important;
+    font-size: $font-size-5 !important;
   }
 }
 
 @mixin fs-5 {
-  font-size: 16px !important;
+  font-size: $font-size-5 !important;
 
   @include mq(sm) {
-    font-size: 18px !important;
+    font-size: $font-size-6 !important;
   }
 }
 
 @mixin fs-6 {
-  font-size: 18px !important;
+  font-size: $font-size-6 !important;
 
   @include mq(sm) {
-    font-size: 24px !important;
+    font-size: $font-size-7 !important;
     line-height: $body-heading-line-height;
   }
 }
 
 @mixin fs-7 {
-  font-size: 24px !important;
+  font-size: $font-size-7 !important;
   line-height: $body-heading-line-height;
 
   @include mq(sm) {
-    font-size: 32px !important;
+    font-size: $font-size-8 !important;
   }
 }
 
 @mixin fs-8 {
-  font-size: 32px !important;
+  font-size: $font-size-8 !important;
   line-height: $body-heading-line-height;
 
   @include mq(sm) {
-    font-size: 36px !important;
+    font-size: $font-size-9 !important;
   }
 }
 
 @mixin fs-9 {
-  font-size: 36px !important;
+  font-size: $font-size-9 !important;
   line-height: $body-heading-line-height;
 
   @include mq(sm) {
-    font-size: 42px !important;
+    font-size: $font-size-10 !important;
   }
 }
 
 @mixin fs-10 {
-  font-size: 42px !important;
+  font-size: $font-size-10 !important;
   line-height: $body-heading-line-height;
 
   @include mq(sm) {
-    font-size: 48px !important;
+    font-size: $font-size-10-sm !important;
   }
 }

_sass/typography.scss

@@ -27,6 +27,10 @@ h4,
   letter-spacing: 0.1em;
 }
 
+h4 code {
+  text-transform: none;
+}
+
 h5,
 .text-epsilon {
   @include fs-3;

assets/js/just-the-docs.js

@@ -24,24 +24,47 @@ jtd.onReady = function(ready) {
 // Show/hide mobile menu
 
 function initNav() {
-  const mainNav = document.querySelector('.js-main-nav');
-  const pageHeader = document.querySelector('.js-page-header');
-  const navTrigger = document.querySelector('.js-main-nav-trigger');
-
-  jtd.addEvent(navTrigger, 'click', function(e){
+  jtd.addEvent(document, 'click', function(e){
+    var target = e.target;
+    while (target && !(target.classList && target.classList.contains('nav-list-expander'))) {
+      target = target.parentNode;
+    }
+    if (target) {
       e.preventDefault();
-    var text = navTrigger.innerText;
-    var textToggle = navTrigger.getAttribute('data-text-toggle');
+      target.parentNode.classList.toggle('active');
+    }
+  });
 
-    mainNav.classList.toggle('nav-open');
-    pageHeader.classList.toggle('nav-open');
-    navTrigger.classList.toggle('nav-open');
-    navTrigger.innerText = textToggle;
-    navTrigger.setAttribute('data-text-toggle', text);
-    textToggle = text;
-  })
+  const siteNav = document.getElementById('site-nav');
+  const mainHeader = document.getElementById('main-header');
+  const menuButton = document.getElementById('menu-button');
+
+  jtd.addEvent(menuButton, 'click', function(e){
+    e.preventDefault();
+
+    if (menuButton.classList.toggle('nav-open')) {
+      siteNav.classList.add('nav-open');
+      mainHeader.classList.add('nav-open');
+    } else {
+      siteNav.classList.remove('nav-open');
+      mainHeader.classList.remove('nav-open');
+    }
+  });
+
+  {%- if site.search_enabled != false and site.search.button %}
+  const searchInput = document.getElementById('search-input');
+  const searchButton = document.getElementById('search-button');
+
+  jtd.addEvent(searchButton, 'click', function(e){
+    e.preventDefault();
+
+    mainHeader.classList.add('nav-open');
+    searchInput.focus();
+  });
+  {%- endif %}
 }
 
+{%- if site.search_enabled != false %}
 // Site search
 
 function initSearch() {
@@ -50,57 +73,326 @@ function initSearch() {
 
   request.onload = function(){
     if (request.status >= 200 && request.status < 400) {
-      // Success!
-      var data = JSON.parse(request.responseText);
+      var docs = JSON.parse(request.responseText);
       
-      {% if site.search_tokenizer_separator != nil %}
-      lunr.tokenizer.separator = {{ site.search_tokenizer_separator }}
-      {% else %}
-      lunr.tokenizer.separator = /[\s\-/]+/
-      {% endif %}
+      lunr.tokenizer.separator = {{ site.search.tokenizer_separator | default: site.search_tokenizer_separator | default: "/[\s\-/]+/" }}
 
       var index = lunr(function(){
         this.ref('id');
         this.field('title', { boost: 200 });
         this.field('content', { boost: 2 });
-        this.field('url');
+        {%- if site.search.rel_url != false %}
+        this.field('relUrl');
+        {%- endif %}
         this.metadataWhitelist = ['position']
 
-        for (var i in data) {
+        for (var i in docs) {
           this.add({
             id: i,
-            title: data[i].title,
-            content: data[i].content,
-            url: data[i].url
+            title: docs[i].title,
+            content: docs[i].content,
+            {%- if site.search.rel_url != false %}
+            relUrl: docs[i].relUrl
+            {%- endif %}
           });
         }
       });
 
-      searchResults(index, data);
+      searchLoaded(index, docs);
     } else {
-      // We reached our target server, but it returned an error
       console.log('Error loading ajax request. Request status:' + request.status);
     }
   };
 
   request.onerror = function(){
-    // There was a connection error of some sort
     console.log('There was a connection error');
   };
 
   request.send();
-
-  function searchResults(index, data) {
-    var index = index;
-    var docs = data;
-    var searchInput = document.querySelector('.js-search-input');
-    var searchResults = document.querySelector('.js-search-results');
-
-    function hideResults() {
-      searchResults.innerHTML = '';
-      searchResults.classList.remove('active');
 }
 
+function searchLoaded(index, docs) {
+  var index = index;
+  var docs = docs;
+  var searchInput = document.getElementById('search-input');
+  var searchResults = document.getElementById('search-results');
+  var mainHeader = document.getElementById('main-header');
+  var currentInput;
+  var currentSearchIndex = 0;
+
+  function showSearch() {
+    document.documentElement.classList.add('search-active');
+  }
+
+  function hideSearch() {
+    document.documentElement.classList.remove('search-active');
+  }
+
+  function update() {
+    currentSearchIndex++;
+
+    var input = searchInput.value;
+    if (input === '') {
+      hideSearch();
+    } else {
+      showSearch();
+      // scroll search input into view, workaround for iOS Safari
+      window.scroll(0, -1);
+      setTimeout(function(){ window.scroll(0, 0); }, 0);
+    }
+    if (input === currentInput) {
+      return;
+    }
+    currentInput = input;
+    searchResults.innerHTML = '';
+    if (input === '') {
+      return;
+    }
+
+    var results = index.query(function (query) {
+      var tokens = lunr.tokenizer(input)
+      query.term(tokens, {
+        boost: 10
+      });
+      query.term(tokens, {
+        wildcard: lunr.Query.wildcard.TRAILING
+      });
+    });
+
+    if ((results.length == 0) && (input.length > 2)) {
+      var tokens = lunr.tokenizer(input).filter(function(token, i) {
+        return token.str.length < 20;
+      })
+      if (tokens.length > 0) {
+        results = index.query(function (query) {
+          query.term(tokens, {
+            editDistance: Math.round(Math.sqrt(input.length / 2 - 1))
+          });
+        });
+      }
+    }
+
+    if (results.length == 0) {
+      var noResultsDiv = document.createElement('div');
+      noResultsDiv.classList.add('search-no-result');
+      noResultsDiv.innerText = 'No results found';
+      searchResults.appendChild(noResultsDiv);
+
+    } else {
+      var resultsList = document.createElement('ul');
+      resultsList.classList.add('search-results-list');
+      searchResults.appendChild(resultsList);
+
+      addResults(resultsList, results, 0, 10, 100, currentSearchIndex);
+    }
+
+    function addResults(resultsList, results, start, batchSize, batchMillis, searchIndex) {
+      if (searchIndex != currentSearchIndex) {
+        return;
+      }
+      for (var i = start; i < (start + batchSize); i++) {
+        if (i == results.length) {
+          return;
+        }
+        addResult(resultsList, results[i]);
+      }
+      setTimeout(function() {
+        addResults(resultsList, results, start + batchSize, batchSize, batchMillis, searchIndex);
+      }, batchMillis);
+    }
+
+    function addResult(resultsList, result) {
+      var doc = docs[result.ref];
+
+      var resultsListItem = document.createElement('li');
+      resultsListItem.classList.add('search-results-list-item');
+      resultsList.appendChild(resultsListItem);
+
+      var resultLink = document.createElement('a');
+      resultLink.classList.add('search-result');
+      resultLink.setAttribute('href', doc.url);
+      resultsListItem.appendChild(resultLink);
+
+      var resultTitle = document.createElement('div');
+      resultTitle.classList.add('search-result-title');
+      resultLink.appendChild(resultTitle);
+
+      var resultDoc = document.createElement('div');
+      resultDoc.classList.add('search-result-doc');
+      resultDoc.innerHTML = '<svg viewBox="0 0 24 24" class="search-result-icon"><use xlink:href="#svg-doc"></use></svg>';
+      resultTitle.appendChild(resultDoc);
+
+      var resultDocTitle = document.createElement('div');
+      resultDocTitle.classList.add('search-result-doc-title');
+      resultDocTitle.innerHTML = doc.doc;
+      resultDoc.appendChild(resultDocTitle);
+      var resultDocOrSection = resultDocTitle;
+
+      if (doc.doc != doc.title) {
+        resultDoc.classList.add('search-result-doc-parent');
+        var resultSection = document.createElement('div');
+        resultSection.classList.add('search-result-section');
+        resultSection.innerHTML = doc.title;
+        resultTitle.appendChild(resultSection);
+        resultDocOrSection = resultSection;
+      }
+
+      var metadata = result.matchData.metadata;
+      var titlePositions = [];
+      var contentPositions = [];
+      for (var j in metadata) {
+        var meta = metadata[j];
+        if (meta.title) {
+          var positions = meta.title.position;
+          for (var k in positions) {
+            titlePositions.push(positions[k]);
+          }
+        }
+        if (meta.content) {
+          var positions = meta.content.position;
+          for (var k in positions) {
+            var position = positions[k];
+            var previewStart = position[0];
+            var previewEnd = position[0] + position[1];
+            var ellipsesBefore = true;
+            var ellipsesAfter = true;
+            for (var k = 0; k < {{ site.search.preview_words_before | default: 5 }}; k++) {
+              var nextSpace = doc.content.lastIndexOf(' ', previewStart - 2);
+              var nextDot = doc.content.lastIndexOf('. ', previewStart - 2);
+              if ((nextDot >= 0) && (nextDot > nextSpace)) {
+                previewStart = nextDot + 1;
+                ellipsesBefore = false;
+                break;
+              }
+              if (nextSpace < 0) {
+                previewStart = 0;
+                ellipsesBefore = false;
+                break;
+              }
+              previewStart = nextSpace + 1;
+            }
+            for (var k = 0; k < {{ site.search.preview_words_after | default: 10 }}; k++) {
+              var nextSpace = doc.content.indexOf(' ', previewEnd + 1);
+              var nextDot = doc.content.indexOf('. ', previewEnd + 1);
+              if ((nextDot >= 0) && (nextDot < nextSpace)) {
+                previewEnd = nextDot;
+                ellipsesAfter = false;
+                break;
+              }
+              if (nextSpace < 0) {
+                previewEnd = doc.content.length;
+                ellipsesAfter = false;
+                break;
+              }
+              previewEnd = nextSpace;
+            }
+            contentPositions.push({
+              highlight: position,
+              previewStart: previewStart, previewEnd: previewEnd,
+              ellipsesBefore: ellipsesBefore, ellipsesAfter: ellipsesAfter
+            });
+          }
+        }
+      }
+
+      if (titlePositions.length > 0) {
+        titlePositions.sort(function(p1, p2){ return p1[0] - p2[0] });
+        resultDocOrSection.innerHTML = '';
+        addHighlightedText(resultDocOrSection, doc.title, 0, doc.title.length, titlePositions);
+      }
+
+      if (contentPositions.length > 0) {
+        contentPositions.sort(function(p1, p2){ return p1.highlight[0] - p2.highlight[0] });
+        var contentPosition = contentPositions[0];
+        var previewPosition = {
+          highlight: [contentPosition.highlight],
+          previewStart: contentPosition.previewStart, previewEnd: contentPosition.previewEnd,
+          ellipsesBefore: contentPosition.ellipsesBefore, ellipsesAfter: contentPosition.ellipsesAfter
+        };
+        var previewPositions = [previewPosition];
+        for (var j = 1; j < contentPositions.length; j++) {
+          contentPosition = contentPositions[j];
+          if (previewPosition.previewEnd < contentPosition.previewStart) {
+            previewPosition = {
+              highlight: [contentPosition.highlight],
+              previewStart: contentPosition.previewStart, previewEnd: contentPosition.previewEnd,
+              ellipsesBefore: contentPosition.ellipsesBefore, ellipsesAfter: contentPosition.ellipsesAfter
+            }
+            previewPositions.push(previewPosition);
+          } else {
+            previewPosition.highlight.push(contentPosition.highlight);
+            previewPosition.previewEnd = contentPosition.previewEnd;
+            previewPosition.ellipsesAfter = contentPosition.ellipsesAfter;
+          }
+        }
+
+        var resultPreviews = document.createElement('div');
+        resultPreviews.classList.add('search-result-previews');
+        resultLink.appendChild(resultPreviews);
+
+        var content = doc.content;
+        for (var j = 0; j < Math.min(previewPositions.length, {{ site.search.previews | default: 3 }}); j++) {
+          var position = previewPositions[j];
+
+          var resultPreview = document.createElement('div');
+          resultPreview.classList.add('search-result-preview');
+          resultPreviews.appendChild(resultPreview);
+
+          if (position.ellipsesBefore) {
+            resultPreview.appendChild(document.createTextNode('... '));
+          }
+          addHighlightedText(resultPreview, content, position.previewStart, position.previewEnd, position.highlight);
+          if (position.ellipsesAfter) {
+            resultPreview.appendChild(document.createTextNode(' ...'));
+          }
+        }
+      }
+
+      {%- if site.search.rel_url != false %}
+      var resultRelUrl = document.createElement('span');
+      resultRelUrl.classList.add('search-result-rel-url');
+      resultRelUrl.innerText = doc.relUrl;
+      resultTitle.appendChild(resultRelUrl);
+      {%- endif %}
+    }
+
+    function addHighlightedText(parent, text, start, end, positions) {
+      var index = start;
+      for (var i in positions) {
+        var position = positions[i];
+        var span = document.createElement('span');
+        span.innerHTML = text.substring(index, position[0]);
+        parent.appendChild(span);
+        index = position[0] + position[1];
+        var highlight = document.createElement('span');
+        highlight.classList.add('search-result-highlight');
+        highlight.innerHTML = text.substring(position[0], index);
+        parent.appendChild(highlight);
+      }
+      var span = document.createElement('span');
+      span.innerHTML = text.substring(index, end);
+      parent.appendChild(span);
+    }
+  }
+
+  jtd.addEvent(searchInput, 'focus', function(){
+    setTimeout(update, 0);
+  });
+
+  jtd.addEvent(searchInput, 'keyup', function(e){
+    switch (e.keyCode) {
+      case 27: // When esc key is pressed, hide the results and clear the field
+        searchInput.value = '';
+        break;
+      case 38: // arrow up
+      case 40: // arrow down
+      case 13: // enter
+        e.preventDefault();
+        return;
+    }
+    update();
+  });
+
   jtd.addEvent(searchInput, 'keydown', function(e){
     switch (e.keyCode) {
       case 38: // arrow up
@@ -145,146 +437,13 @@ function initSearch() {
     }
   });
 
-    jtd.addEvent(searchInput, 'keyup', function(e){
-      switch (e.keyCode) {
-        case 27: // When esc key is pressed, hide the results and clear the field
-          hideResults();
-          searchInput.value = '';
-          return;
-        case 38: // arrow up
-        case 40: // arrow down
-        case 13: // enter
-          e.preventDefault();
-          return;
-      }
-
-      hideResults();
-
-      var input = this.value;
-      if (input === '') {
-        return;
-      }
-
-      var results = index.query(function (query) {
-        var tokens = lunr.tokenizer(input)
-        query.term(tokens, {
-          boost: 10
-        });
-        query.term(tokens, {
-          wildcard: lunr.Query.wildcard.TRAILING
-        });
-      });
-
-      if (results.length > 0) {
-        searchResults.classList.add('active');
-        var resultsList = document.createElement('ul');
-        resultsList.classList.add('search-results-list');
-        searchResults.appendChild(resultsList);
-
-        for (var i in results) {
-          var result = results[i];
-          var doc = docs[result.ref];
-
-          var resultsListItem = document.createElement('li');
-          resultsListItem.classList.add('search-results-list-item');
-          resultsList.appendChild(resultsListItem);
-
-          var resultLink = document.createElement('a');
-          resultLink.classList.add('search-result');
-          resultLink.setAttribute('href', doc.url);
-          resultsListItem.appendChild(resultLink);
-
-          var resultTitle = document.createElement('div');
-          resultTitle.classList.add('search-result-title');
-          resultTitle.innerText = doc.title;
-          resultLink.appendChild(resultTitle);
-
-          var resultRelUrl = document.createElement('span');
-          resultRelUrl.classList.add('search-result-rel-url');
-          resultRelUrl.innerText = doc.relUrl;
-          resultTitle.appendChild(resultRelUrl);
-
-          var metadata = result.matchData.metadata;
-          var contentFound = false;
-          for (var j in metadata) {
-            if (metadata[j].title) {
-              var position = metadata[j].title.position[0];
-              var start = position[0];
-              var end = position[0] + position[1];
-              resultTitle.innerHTML = doc.title.substring(0, start) + '<span class="search-result-highlight">' + doc.title.substring(start, end) + '</span>' + doc.title.substring(end, doc.title.length)+'<span class="search-result-rel-url">'+doc.relUrl+'</span>';
-
-            } else if (metadata[j].content && !contentFound) {
-              contentFound = true;
-
-              var position = metadata[j].content.position[0];
-              var start = position[0];
-              var end = position[0] + position[1];
-              var previewStart = start;
-              var previewEnd = end;
-              var ellipsesBefore = true;
-              var ellipsesAfter = true;
-              for (var k = 0; k < 3; k++) {
-                var nextSpace = doc.content.lastIndexOf(' ', previewStart - 2);
-                var nextDot = doc.content.lastIndexOf('.', previewStart - 2);
-                if ((nextDot > 0) && (nextDot > nextSpace)) {
-                  previewStart = nextDot + 1;
-                  ellipsesBefore = false;
-                  break;
-                }
-                if (nextSpace < 0) {
-                  previewStart = 0;
-                  ellipsesBefore = false;
-                  break;
-                }
-                previewStart = nextSpace + 1;
-              }
-              for (var k = 0; k < 10; k++) {
-                var nextSpace = doc.content.indexOf(' ', previewEnd + 1);
-                var nextDot = doc.content.indexOf('.', previewEnd + 1);
-                if ((nextDot > 0) && (nextDot < nextSpace)) {
-                  previewEnd = nextDot;
-                  ellipsesAfter = false;
-                  break;
-                }
-                if (nextSpace < 0) {
-                  previewEnd = doc.content.length;
-                  ellipsesAfter = false;
-                  break;
-                }
-                previewEnd = nextSpace;
-              }
-              var preview = doc.content.substring(previewStart, start);
-              if (ellipsesBefore) {
-                preview = '... ' + preview;
-              }
-              preview += '<span class="search-result-highlight">' + doc.content.substring(start, end) + '</span>';
-              preview += doc.content.substring(end, previewEnd);
-              if (ellipsesAfter) {
-                preview += ' ...';
-              }
-
-              var resultPreview = document.createElement('div');
-              resultPreview.classList.add('search-result-preview');
-              resultPreview.innerHTML = preview;
-              resultLink.appendChild(resultPreview);
-            }
-          }
-        }
+  jtd.addEvent(document, 'click', function(e){
+    if (e.target != searchInput) {
+      hideSearch();
     }
   });
-
-    jtd.addEvent(searchInput, 'blur', function(){
-      setTimeout(function(){ hideResults() }, 300);
-    });
-  }
-}
-
-// Focus
-
-function pageFocus() {
-  var mainContent = document.querySelector('.js-main-content');
-  mainContent.focus();
 }
+{%- endif %}
 
 // Switch theme
 
@@ -302,10 +461,9 @@ jtd.setTheme = function(theme) {
 
 jtd.onReady(function(){
   initNav();
-  pageFocus();
-  if (typeof lunr !== 'undefined') {
+  {%- if site.search_enabled != false %}
   initSearch();
-  }
+  {%- endif %}
 });
 
 })(window.jtd = window.jtd || {});

assets/js/search-data.json

@@ -1,12 +0,0 @@
----
----
-{
-  {% assign comma = false %}
-  {% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": {
-    "title": "{{ page.title | replace: '&', '&' }}",
-    "content": "{{ page.content | markdownify | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '</ul', ' . </ul' | replace: '</tr', ' . </tr' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | strip_html | escape_once | remove: 'Table of contents' | remove: '```'  | remove: '---' | replace: '\', ' ' | replace: ' .  .  . ', ' . ' | replace: ' .  . ', ' . ' | normalize_whitespace }}",
-    "url": "{{ page.url | absolute_url }}",
-    "relUrl": "{{ page.url }}"
-  }{% assign comma = true %}
-  {% endif %}{% endfor %}
-}

assets/js/zzzz-search-data.json

@@ -0,0 +1,72 @@
+---
+permalink: /assets/js/search-data.json
+---
+{
+{%- assign i = 0 -%}
+{%- assign pages_array = '' | split: '' -%}
+{%- assign pages_array = pages_array | push: site.html_pages -%}
+{%- if site.just_the_docs.collections -%}
+  {%- 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.search_exclude != true -%}
+      {%- assign pages_array = pages_array | push: collection -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+{%- for pages in pages_array -%}
+  {%- for page in pages -%}
+    {%- if page.title and page.search_exclude != true -%}
+      {%- assign page_content = page.content -%}
+      {%- assign heading_level = site.search.heading_level | default: 2 -%}
+      {%- for j in (2..heading_level) -%}
+        {%- assign tag = '<h' | append: j -%}
+        {%- assign closing_tag = '</h' | append: j -%}
+        {%- assign page_content = page_content | replace: tag, '<h1' | replace: closing_tag, '</h1' -%}
+      {%- endfor -%}
+      {%- assign parts = page_content | split: '<h1' -%}
+      {%- assign title_found = false -%}
+      {%- for part in parts offset: 1 -%}
+        {%- assign titleAndContent = part | split: '</h1>' -%}
+        {%- assign title = titleAndContent[0] | replace_first: '>', '<h1>' | split: '<h1>' -%}
+        {%- assign title = title[1] | strip_html -%}
+        {%- assign content = titleAndContent[1] -%}
+        {%- assign url = page.url -%}
+        {%- if title == page.title and parts[0] == '' -%}
+          {%- assign title_found = true -%}
+        {%- else -%}
+          {%- assign id = titleAndContent[0] -%}
+          {%- assign id = id | split: 'id="' -%}
+          {%- if id.size == 2 -%}
+            {%- assign id = id[1] -%}
+            {%- assign id = id | split: '"' -%}
+            {%- assign id = id[0] -%}
+            {%- capture url -%}{{ url | append: '#' | append: id }}{%- endcapture -%}
+          {%- endif -%}
+        {%- endif -%}
+  {%- unless i == 0 -%},{%- endunless -%}
+  "{{ i }}": {
+    "doc": {{ page.title | jsonify }},
+    "title": {{ title | jsonify }},
+    "content": {{ content | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '<ul', ' . <ul' | replace: '</ul', ' . </ul' | replace: '<ol', ' . <ol' | replace: '</ol', ' . </ol' | replace: '</tr', ' . </tr' | replace: '<li', ' | <li' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | replace: '<td', ' | <td' | replace: '</th', ' | </th' | replace: '<th', ' | <th' | strip_html | remove: 'Table of contents' | normalize_whitespace | replace: '. . .', '.' | replace: '. .', '.' | replace: '| |', '|' | append: ' ' | jsonify }},
+    "url": "{{ url | absolute_url }}",
+    "relUrl": "{{ url }}"
+  }
+        {%- assign i = i | plus: 1 -%}
+      {%- endfor -%}
+      {%- unless title_found -%}
+  {%- unless i == 0 -%},{%- endunless -%}
+  "{{ i }}": {
+    "doc": {{ page.title | jsonify }},
+    "title": {{ page.title | jsonify }},
+    "content": {{ parts[0] | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '<ul', ' . <ul' | replace: '</ul', ' . </ul' | replace: '<ol', ' . <ol' | replace: '</ol', ' . </ol' | replace: '</tr', ' . </tr' | replace: '<li', ' | <li' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | replace: '<td', ' | <td' | replace: '</th', ' | </th' | replace: '<th', ' | <th' | strip_html | remove: 'Table of contents' | normalize_whitespace | replace: '. . .', '.' | replace: '. .', '.' | replace: '| |', '|' | append: ' ' | jsonify }},
+    "url": "{{ page.url | absolute_url }}",
+    "relUrl": "{{ page.url }}"
+  }
+        {%- assign i = i | plus: 1 -%}
+      {%- endunless -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endfor %}
+}

docker-compose.yml

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

docs/configuration.md

@@ -22,6 +22,7 @@ Just the Docs has some specific configuration parameters that can be defined in
 
 View this site's [_config.yml](https://github.com/pmarsceill/just-the-docs/tree/master/_config.yml) file as an example.
 
+
 ## Site logo
 
 ```yaml
@@ -36,8 +37,29 @@ logo: "/assets/images/just-the-docs.png"
 # Supports true (default) or false
 search_enabled: true
 
-# Enable support for hyphenated search words:
-search_tokenizer_separator: /[\s/]+/
+search:
+  # Split pages into sections that can be searched individually
+  # Supports 1 - 6, default: 2
+  heading_level: 2
+  # Maximum amount of previews per search result
+  # Default: 3
+  previews: 3
+  # Maximum amount of words to display before a matched word in the preview
+  # Default: 5
+  preview_words_before: 5
+  # Maximum amount of words to display after a matched word in the preview
+  # Default: 10
+  preview_words_after: 10
+  # Set the search token separator
+  # Default: /[\s\-/]+/
+  # Example: enable support for hyphenated search words
+  tokenizer_separator: /[\s/]+/
+  # Display the relative url in search results
+  # Supports true (default) or false
+  rel_url: true
+  # Enable or disable the search button that appears in the bottom right corner of every page
+  # Supports true or false (default)
+  button: false
 ```
 
 ## Aux links
@@ -78,6 +100,7 @@ gh_edit_link: true # show or hide edit this page link
 gh_edit_link_text: "Edit this page on GitHub."
 gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
 gh_edit_branch: "master" # the branch that your docs is served from
+# gh_edit_source: docs # the source that your files originate from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
 ```
 
@@ -85,6 +108,7 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
 - `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime)
 - `gh_edit_repository` is the URL of the project's GitHub repository
 - `gh_edit_branch` is the branch that the docs site is served from; defaults to `master`
+- `gh_edit_source` is the source directory that your project files are stored in (should be the same as [site.source](https://jekyllrb.com/docs/configuration/options/))
 - `gh_edit_view_mode` is `"tree"` by default, which brings the user to the github page; switch to `"edit"` to bring the user directly into editing mode
 
 ## Color scheme
@@ -119,3 +143,52 @@ See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more
 ga_tracking: UA-5555555-55
 ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default)
 ```
+
+## Document collections
+
+By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/).
+Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
+
+For example, put all your documentation files in the `_docs` folder and create the `docs` collection:
+```yaml
+# Define Jekyll collections
+collections:
+  # Define a collection named "docs", its documents reside in the "_docs" directory
+  docs:
+    permalink: "/:collection/:path/"
+    output: true
+
+just_the_docs:
+  # Define which collections are used in just-the-docs
+  collections:
+    # Reference the "docs" collection
+    docs:
+      # Give the collection a name
+      name: Documentation
+      # Exclude the collection from the navigation
+      # Supports true or false (default)
+      nav_exclude: false
+      # Exclude the collection from the search
+      # Supports true or false (default)
+      search_exclude: false
+```
+
+You can reference multiple collections.
+This creates categories in the navigation with the configured names.
+```yaml
+collections:
+  docs:
+    permalink: "/:collection/:path/"
+    output: true
+  tutorials:
+    permalink: "/:collection/:path/"
+    output: true
+
+just_the_docs:
+  collections:
+    docs:
+      name: Documentation
+    tutorials:
+      name: Tutorials
+```
+

docs/index-test.md

@@ -39,7 +39,7 @@ GitHubPages::Dependencies.gems.each do |gem, version|
 end
 ```
 
-#### [](#header-4)Header 4
+#### [](#header-4)Header 4 `with code not transformed`
 
 *   This is an unordered list following a header.
 *   This is an unordered list following a header.
@@ -140,6 +140,37 @@ end
 <dd>Green</dd>
 </dl>
 
+#### Multiple description terms and values
+
+Term
+: Brief description of Term
+
+Longer Term
+: Longer description of Term,
+  possibly more than one line
+
+Term
+: First description of Term,
+  possibly more than one line
+
+: Second description of Term,
+  possibly more than one line
+
+Term1
+Term2
+: Single description of Term1 and Term2,
+  possibly more than one line
+
+Term1
+Term2
+: First description of Term1 and Term2,
+  possibly more than one line
+
+: Second description of Term1 and Term2,
+  possibly more than one line
+  
+### More code
+
 ```
 Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this.
 ```

docs/navigation-structure.md

@@ -7,11 +7,14 @@ nav_order: 5
 # Navigation Structure
 {: .no_toc }
 
-## Table of contents
-{: .no_toc .text-delta }
-
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
 1. TOC
 {:toc}
+</details>
 
 ---
 
@@ -25,7 +28,7 @@ By default, all pages will appear as top level pages in the main nav unless a pa
 
 ## Ordering pages
 
-To specify a page order, use the `nav_order` parameter in your pages' YAML front matter.
+To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
 
 #### Example
 {: .no_toc }
@@ -38,12 +41,13 @@ nav_order: 4
 ---
 ```
 
-The specified `nav_order` parameters on a site should be all integers or all strings.
-Pages without a `nav_order` parameter are ordered alphabetically by their `title`,
-and appear after the explicitly-ordered pages at each level.
-By default, all Capital letters are sorted before all lowercase letters;
-adding `nav_sort: case_insensitive` in the configuration file ignores case
-when sorting strings (but also sorts numbers lexicographically: `10` comes before `1`).
+The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents.
+
+The parameter values can be numbers (integers, floats) and/or strings. When you omit `nav_order` parameters, they default to the titles of the pages, which are ordered alphabetically. Pages with numerical `nav_order` parameters always come before those with strings or default `nav_order` parameters. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages.
+
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in quotation marks is optional.
+
+> *Note for users of previous versions:* `nav_sort: case_insensitive` previously affected the ordering of numerical `nav_order` parameters: e.g., `10` came before `2`. Also, all pages with explicit `nav_order` parameters previously came before all pages with default parameters. Both were potentially confusing, and they have now been eliminated. 
 
 ---
 
@@ -62,6 +66,8 @@ nav_exclude: true
 ---
 ```
 
+Pages with no `title` are automatically excluded from the navigation.
+
 ---
 
 ## Pages with children
@@ -231,4 +237,21 @@ To generate a Table of Contents on your docs pages, you can use the `{:toc}` met
 {:toc}
 ```
 
-This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself.
+This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. To get an unordered list, replace  `1. TOC` above by `- TOC`.
+
+### 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.
+
+```markdown
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+1. TOC
+{:toc}
+</details>
+```
+
+The result is shown at [the top of this page](#navigation-structure) (`{:toc}` can be used only once on each page).

docs/search.md

@@ -15,62 +15,90 @@ nav_order: 7
 
 ---
 
-Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates. All search results are shown in an auto-complete style interface (there is no search results page). By default, all generated HTML pages are indexed using the following data points:
+Just the Docs uses [lunr.js](http://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates.
+All search results are shown in an auto-complete style interface (there is no search results page).
+By default, all generated HTML pages are indexed using the following data points:
 
 - Page title
 - Page content
 - Page URL
 
-## Set up search
-
-### Generate search index
-
-Before you can use search, you must initialize the feature by running this `rake` command that comes with `just-the-docs`:
-
-```bash
-$ bundle exec just-the-docs rake search:init
-```
-
-This command creates the `search-data.json` file that Jekyll uses to create your search index. Alternatively, you can create the file manually in the `assets/js/` directory of your Jekyll site with this content:
-
-```liquid
-{% raw %}---
----
-{
-  {% assign comma = false %}
-  {% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": {
-    "title": "{{ page.title | replace: '&', '&' }}",
-    "content": "{{ page.content | markdownify | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '</ul', ' . </ul' | replace: '</tr', ' . </tr' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | strip_html | escape_once | remove: 'Table of contents' | remove: '```'  | remove: '---' | replace: '\', ' ' | replace: ' .  .  . ', ' . ' | replace: ' .  . ', ' . ' | normalize_whitespace }}",
-    "url": "{{ page.url | absolute_url }}",
-    "relUrl": "{{ page.url }}"
-  }{% assign comma = true %}
-  {% endif %}{% endfor %}
-}{% endraw %}
-```
-
-_Note: If you don't run this rake command or create this file manually, search will not work (or it will use the search index data from this docs site, not your site's content)._
-
-### Enable search in configuration
+## Enable search in configuration
 
 In your site's `_config.yml`, enable search:
 
 ```yaml
 # Enable or disable the site search
+# Supports true (default) or false
 search_enabled: true
 ```
 
+### Search granularity
+
+Pages are split into sections that can be searched individually.
+The sections are defined by the headings on the page.
+Each section is displayed in a separate search result.
+
+```yaml
+# Split pages into sections that can be searched individually
+# Supports 1 - 6, default: 2
+search.heading_level: 2
+```
+
+### Search previews
+
+A search result can contain previews that show where the search words are found in the specific section.
+
+```yaml
+# Maximum amount of previews per search result
+# Default: 3
+search.previews: 3
+
+# Maximum amount of words to display before a matched word in the preview
+# Default: 5
+search.preview_words_before: 5
+
+# Maximum amount of words to display after a matched word in the preview
+# Default: 10
+search.preview_words_after: 10
+```
+
+### Search tokenizer
+
 The default is for hyphens to separate tokens in search terms:
 `gem-based` is equivalent to `gem based`, matching either word.
 To allow search for hyphenated words:
 
 ```yaml
 # Set the search token separator
-search_tokenizer_separator: /[\s/]+/
+# Default: /[\s\-/]+/
+# Example: enable support for hyphenated search words
+search.tokenizer_separator: /[\s/]+/
 ```
 
+### Display URL in search results 
+
+```yaml
+# Display the relative url in search results
+# Supports true (default) or false
+search.rel_url: false
+```
+
+### Display search button
+
+The search button displays in the bottom right corner of the screen and triggers the search input when clicked.
+
+```yaml
+# Enable or disable the search button that appears in the bottom right corner of every page
+# Supports true or false (default)
+search.button: true
+```
+
+
 ## Hiding pages from search
 
-Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page. To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
+Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g, a 404 page.
+To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter:
 
 #### Example
 {: .no_toc }
@@ -83,3 +111,17 @@ nav_exclude: true
 search_exclude: true
 ---
 ```
+
+
+## Generate search index when used as a gem
+
+If you use Just the Docs as a remote theme, you do not need the following steps.
+
+If you use the theme as a gem, you must initialize the search by running this `rake` command that comes with `just-the-docs`:
+
+```bash
+$ bundle exec just-the-docs rake search:init
+```
+
+This command creates the `assets/js/zzzz-search-data.json` file that Jekyll uses to create your search index.
+Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/master/assets/js/zzzz-search-data.json).

docs/tests/index.md

@@ -0,0 +1,22 @@
+---
+layout: default
+title: Tests
+has_children: true
+nav_order: 100
+---
+
+# Tests
+
+ The main documentation pages of this theme illustrate the use of many of its features, which to some extent tests their implementation. The pages linked below provide further test cases for particular features, and may be useful for regression testing when developing new features.
+ 
+The default configuration does not include the test pages. To include them, *commment-out* the following line in `_config.yml`:
+
+```yaml
+, "docs/tests/"
+```
+so that it is:
+```yaml
+# , "docs/tests/"
+```
+
+(Apparently Jekyll's `include` does *not* override `exclude`  for the same folder...)

docs/tests/navigation/exclude/excluded-child.md

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Excluded Child
+parent: Not Excluded
+nav_exclude: true
+---
+# Excluded Child
+
+This child page is explicitly excluded, and should not appear in the navigation.
+
+```yaml
+title: Excluded Child
+parent: Not Excluded
+nav_exclude: true
+```

docs/tests/navigation/exclude/excluded-grandchild.md

@@ -0,0 +1,17 @@
+---
+layout: default
+title: Excluded Grandchild
+parent: Non-excluded Child
+grand_parent: Non-excluded
+nav_exclude: true
+---
+# Excluded Grandchild
+
+This grandchild page is explicitly excluded, and should not appear in the navigation.
+
+```yaml
+title: Excluded Grandchild
+parent: Non-excluded Child
+grand_parent: Non-excluded
+nav_exclude: true
+```

docs/tests/navigation/exclude/excluded.md

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Excluded
+has_children: true
+nav_exclude: true
+---
+# Excluded
+
+This top-level page is explicitly excluded, and should not appear in the navigation. Any child pages are implicitly excluded.
+
+```yaml
+title: Excluded
+has_children: true
+nav_exclude: true
+```

docs/tests/navigation/exclude/non-excluded-child-of-excluded.md

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Non-excluded Child of Excluded
+parent: Excluded
+nav_exclude: false
+---
+# Non-excluded Child of Excluded
+
+This child page is explicitly not excluded, but its parent page is excluded, so it should not appear in the navigation.
+
+```yaml
+title: Non-excluded Child of Excluded
+parent: Excluded
+nav_exclude: false
+```

docs/tests/navigation/exclude/non-excluded-child.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: Non-excluded Child
+parent: Non-excluded
+has_children: true
+nav_exclude: false
+---
+# Non-excluded Child
+
+This child page is explicitly not excluded, and should appear in the navigation.
+
+```yaml
+title: Non-excluded Child
+parent: Non-excluded
+nav_exclude: false
+```

docs/tests/navigation/exclude/non-excluded-grandchild-of-excluded.md

@@ -0,0 +1,17 @@
+---
+layout: default
+title: Non-excluded Grandchild of Excluded
+parent: Non-excluded Child
+grand_parent: Excluded
+nav_exclude: false
+---
+# Non-excluded Grandchild of Excluded
+
+This grandchild page is explicitly not excluded, and neither is its parent page; but its grandparent page is excluded, so it should not appear in the navigation.
+
+```yaml
+title: Non-excluded Grandchild of Excluded
+parent: Non-excluded Child
+grand_parent: Excluded
+nav_exclude: false
+```

docs/tests/navigation/exclude/non-excluded-grandchild.md

@@ -0,0 +1,17 @@
+---
+layout: default
+title: Non-excluded Grandchild
+parent: Non-excluded Child
+grand_parent: Non-excluded
+nav_exclude: false
+---
+# Non-excluded Grandchild
+
+This grandchild page is explicitly not excluded, and neither is its parent page nor its grandparent page, so it should appear in the navigation.
+
+```yaml
+title: Non-excluded Grandchild of Excluded
+parent: Non-excluded Child
+grand_parent: Excluded
+nav_exclude: false
+```

docs/tests/navigation/exclude/non-excluded.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Non-excluded
+has_children: true
+nav_exclude: false
+---
+# Non-excluded
+
+This top-level page is explicitly not excluded, and should appear in the navigation.
+
+```yaml
+title: Non-excluded
+nav_exclude: false
+```

docs/tests/navigation/exclude/untitled.md

@@ -0,0 +1,6 @@
+---
+layout: default
+---
+# Untitled
+
+This page does not have a `title`, and it is excluded from the navigation -- unless it is located in a Jekyll collection (which provides default titles). To exclude a title-less page from the navigation, regardless of whether it is located in a collection, set `nav_exclude: true`.

docs/tests/navigation/grandparent/a.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: A
+has_children: true
+---
+
+# A
+
+A top-level page
+
+```yaml
+title: A
+has_children: true
+```

docs/tests/navigation/grandparent/b.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: B
+has_children: true
+---
+
+# B
+
+A top-level page
+
+```yaml
+title: B
+has_children: true
+```

docs/tests/navigation/grandparent/ca.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: C
+parent: A
+has_children: true
+---
+
+# C
+
+A child of page A, and parent of page D
+
+```yaml
+title: C
+parent: A
+has_children: true
+```

docs/tests/navigation/grandparent/cb.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: C
+parent: B
+has_children: true
+---
+
+# C
+
+A child of page B, and parent of page D
+
+```yaml
+title: C
+parent: B
+has_children: true
+```

docs/tests/navigation/grandparent/dca.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: D
+parent: C
+grand_parent: A
+---
+
+# D
+
+A grandchild of page A
+
+```yaml
+title: D
+parent: C
+grand_parent: A
+```

docs/tests/navigation/grandparent/dcb.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: D
+parent: C
+grand_parent: B
+---
+
+# D
+
+A grandchild of page B
+
+```yaml
+title: D
+parent: C
+grand_parent: B
+```

docs/tests/navigation/index.md

@@ -0,0 +1,28 @@
+---
+layout: default
+title: Navigation
+parent: Tests
+---
+
+# Navigation
+
+## Parent page disambiguation
+
+- [Page A](grandparent/a/) has a child [page with title C](grandparent/ca/), and a grandchild [page with title D](grandparent/dca/).
+- [Page B](grandparent/b/) has a child [page with title C](grandparent/cb/), and a grandchild [page with title D](grandparent/dcb/).
+- The grandchild pages specify their parent and grandparent pages, so there is no ambiguity.
+
+## Page exclusion
+
+- An [untitled page](exclude/untitled/) is excluded from the navigation.
+- An excluded [top level page](exclude/excluded/), [child page](exclude/excluded-child/), or [grandchild page](exclude/excluded-grandchild/) does not appear.
+- A non-excluded [top level page](exclude/non-excluded/) appears; and a non-excluded [child page](exclude/non-excluded-child/) or [grandchild page](exclude/non-excluded-grandchild/) appears if its parent appears.
+- A non-excluded child page or grandchild page does not appear if its parent is excluded.
+
+## Page order
+
+- [Default](order/default/), using `title` instead of `nav_order` fields.
+- [Strings](order/strings/), lexicographically ordered, possibly case-insensitively.
+- [Integers](order/integers/), numerically ordered.
+- [Floats](order/floats/), numerically ordered.
+- [Mixture](order/mixture/), with numbers before strings.

docs/tests/navigation/order/default/10.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: "10"
+parent: Default
+grand_parent: Order
+---
+
+# 10
+
+```yaml
+title: "10"
+parent: Default
+grand_parent: Order
+```

docs/tests/navigation/order/default/2.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: "2"
+parent: Default
+grand_parent: Order
+---
+
+# 2
+
+```yaml
+title: "2"
+parent: Default
+grand_parent: Order
+```

docs/tests/navigation/order/default/a.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: A
+parent: Default
+grand_parent: Order
+---
+
+# A
+
+```yaml
+title: A
+parent: Default
+grand_parent: Order
+```

docs/tests/navigation/order/default/aa-lower.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: aa
+parent: Default
+grand_parent: Order
+---
+
+# aa
+
+```yaml
+title: aa
+parent: Default
+grand_parent: Order
+```

docs/tests/navigation/order/default/aa.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: Aa
+parent: Default
+grand_parent: Order
+---
+
+# Aa
+
+```yaml
+title: Aa
+parent: Default
+grand_parent: Order
+```

docs/tests/navigation/order/default/index.md

@@ -0,0 +1,15 @@
+---
+layout: default
+title: Default
+parent: Order
+nav_order: 1
+has_children: true
+---
+
+# Default Order
+
+When `nav_order` fields are omitted, the pages are ordered alphabetically by their titles.
+
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case).
+
+Digits precede letters, and numeric titles are ordered lexicographically: `10` precedes `2` (in contrast to explicit numeric `nav_order` values).

docs/tests/navigation/order/floats/-1.1.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "-1.1"
+nav_order: -1.1
+parent: Floats
+grand_parent: Order
+---
+
+# -1.1
+
+```yaml
+title: "-1.1"
+nav_order: -1.1
+parent: Floats
+grand_parent: Order
+```

docs/tests/navigation/order/floats/0.0.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "0.0"
+nav_order: 0.0
+parent: Floats
+grand_parent: Order
+---
+
+# 0.0
+
+```yaml
+title: "0.0"
+nav_order: 0.0
+parent: Floats
+grand_parent: Order
+```

docs/tests/navigation/order/floats/10.0.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "10.0"
+nav_order: 10.0
+parent: Floats
+grand_parent: Order
+---
+
+# 10.0
+
+```yaml
+title: "10.0"
+nav_order: 10.0
+parent: Floats
+grand_parent: Order
+```

docs/tests/navigation/order/floats/2.2222.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "2.2222"
+nav_order: 2.2222
+parent: Floats
+grand_parent: Order
+---
+
+# 2.2222
+
+```yaml
+title: "2.2222"
+nav_order: 2.2222
+parent: Floats
+grand_parent: Order
+```

docs/tests/navigation/order/floats/index.md

@@ -0,0 +1,13 @@
+---
+layout: default
+title: Floats
+parent: Order
+nav_order: 4
+has_children: true
+---
+
+# Floating-Point Order
+
+When `nav_order` fields are floating-point numbers, the pages are ordered in increasing order of the numerical values.
+
+Floats include `0.0` and negative values. 

docs/tests/navigation/order/index.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Order
+has_children: true
+nav_order: 110
+---
+
+# Order

docs/tests/navigation/order/integers/-1.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "-1"
+nav_order: -1
+parent: Integers
+grand_parent: Order
+---
+
+# -1
+
+```yaml
+title: "-1"
+nav_order: -1
+parent: Integers
+grand_parent: Order
+```

docs/tests/navigation/order/integers/0.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "0"
+nav_order: 0
+parent: Integers
+grand_parent: Order
+---
+
+# 0
+
+```yaml
+title: "0"
+nav_order: 0
+parent: Integers
+grand_parent: Order
+```

docs/tests/navigation/order/integers/10.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "10"
+nav_order: 10
+parent: Integers
+grand_parent: Order
+---
+
+# 10
+
+```yaml
+title: "10"
+nav_order: 10
+parent: Integers
+grand_parent: Order
+```

docs/tests/navigation/order/integers/2.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "2"
+nav_order: 2
+parent: Integers
+grand_parent: Order
+---
+
+# 2
+
+```yaml
+title: "2"
+nav_order: 2
+parent: Integers
+grand_parent: Order
+```

docs/tests/navigation/order/integers/index.md

@@ -0,0 +1,13 @@
+---
+layout: default
+title: Integers
+parent: Order
+nav_order: 3
+has_children: true
+---
+
+# Integer Order
+
+When `nav_order` fields are integers, the pages are ordered in increasing order of the numerical values.
+
+Integers include `0` and negative values. Integers can be reused for top-level pages and for different sets of child pages. 

docs/tests/navigation/order/mixture/-1.1.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "-1.1"
+nav_order: -1.1
+parent: Mixture
+grand_parent: Order
+---
+
+# -1.1
+
+```yaml
+title: "-1.1"
+nav_order: -1.1
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/-1.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "-1"
+nav_order: -1
+parent: Mixture
+grand_parent: Order
+---
+
+# -1
+
+```yaml
+title: "-1"
+nav_order: -1
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/0.0.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "0.0"
+nav_order: 0.0
+parent: Mixture
+grand_parent: Order
+---
+
+# 0.0
+
+```yaml
+title: "0.0"
+nav_order: 0.0
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/0.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "0"
+nav_order: 0
+parent: Mixture
+grand_parent: Order
+---
+
+# 0
+
+```yaml
+title: "0"
+nav_order: 0
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/10.0.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "10.0"
+nav_order: 10.0
+parent: Mixture
+grand_parent: Order
+---
+
+# 10.0
+
+```yaml
+title: "10.0"
+nav_order: 10.0
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/10.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: "10"
+parent: Mixture
+grand_parent: Order
+---
+
+# 10
+
+```yaml
+title: "10"
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/2.2222.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "2.2222"
+nav_order: 2.2222
+parent: Mixture
+grand_parent: Order
+---
+
+# 2.2222
+
+```yaml
+title: "2.2222"
+nav_order: 2.2222
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/2.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: "2"
+parent: Mixture
+grand_parent: Order
+---
+
+# 2
+
+```yaml
+title: "2"
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/a.md

@@ -0,0 +1,14 @@
+---
+layout: default
+title: A
+parent: Mixture
+grand_parent: Order
+---
+
+# A
+
+```yaml
+title: A
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/aa-lower.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: aa
+nav_order: "aa"
+parent: Mixture
+grand_parent: Order
+---
+
+# aa
+
+```yaml
+title: aa
+nav_order: "aa"
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/aa.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: Aa
+nav_order: "Aa"
+parent: Mixture
+grand_parent: Order
+---
+
+# Aa
+
+```yaml
+title: Aa
+nav_order: "Aa"
+parent: Mixture
+grand_parent: Order
+```

docs/tests/navigation/order/mixture/index.md

@@ -0,0 +1,11 @@
+---
+layout: default
+title: Mixture
+parent: Order
+nav_order: 5
+has_children: true
+---
+
+# Mixed Order
+
+It seems unlikely that different types of `nav_order` values are needed for the children of the same parent.

docs/tests/navigation/order/strings/10.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "10"
+nav_order: "10"
+parent: Strings
+grand_parent: Order
+---
+
+# 10
+
+```yaml
+title: "10"
+nav_order: "10"
+parent: Strings
+grand_parent: Order
+```

docs/tests/navigation/order/strings/2.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: "2"
+nav_order: "2"
+parent: Strings
+grand_parent: Order
+---
+
+# 2
+
+```yaml
+title: "2"
+nav_order: "2"
+parent: Strings
+grand_parent: Order
+```

docs/tests/navigation/order/strings/a.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: A
+nav_order: A
+parent: Strings
+grand_parent: Order
+---
+
+# A
+
+```yaml
+title: A
+nav_order: A
+parent: Strings
+grand_parent: Order
+```

docs/tests/navigation/order/strings/aa-lower.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: aa
+nav_order: "aa"
+parent: Strings
+grand_parent: Order
+---
+
+# aa
+
+```yaml
+title: aa
+nav_order: "aa"
+parent: Strings
+grand_parent: Order
+```

docs/tests/navigation/order/strings/aa.md

@@ -0,0 +1,16 @@
+---
+layout: default
+title: Aa
+nav_order: "Aa"
+parent: Strings
+grand_parent: Order
+---
+
+# Aa
+
+```yaml
+title: Aa
+nav_order: "Aa"
+parent: Strings
+grand_parent: Order
+```

docs/tests/navigation/order/strings/index.md

@@ -0,0 +1,13 @@
+---
+layout: default
+title: Strings
+parent: Order
+nav_order: 2
+has_children: true
+---
+
+# String Order
+
+By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case).
+
+Digits precede letters, and numeric titles are ordered lexicographically: `"10"` precedes `"2"` (in contrast to explicit numeric `nav_order` values).

docs/ui-components/code.md

@@ -2,6 +2,7 @@
 layout: default
 title: Code
 parent: UI Components
+has_children: true
 nav_order: 6
 ---
 

docs/ui-components/line-nos.md

@@ -0,0 +1,115 @@
+---
+layout: default
+title: Code with line numbers
+parent: Code
+grand_parent: UI Components
+permalink: /docs/ui-components/code/line-numbers/
+---
+
+# Code snippets with line numbers
+
+The default settings for HTML compression are incompatible with the HTML
+produced by Jekyll (4.1.1 or earlier) for line numbers from highlighted code
+-- both when using Kramdown code fences and when using Liquid highlight tags.
+
+To avoid non-conforming HTML and unsatisfactory layout, HTML compression
+can be turned off by using the following configuration option:
+
+{% highlight yaml %}
+compress_html:
+  ignore:
+    envs: all
+{% endhighlight %}
+
+When using Kramdown code fences, line numbers are turned on globally by the
+following configuration option:
+
+{% highlight yaml %}
+kramdown:
+  syntax_highlighter_opts:
+    block:
+      line_numbers: true
+{% endhighlight %}
+
+Line numbers can then be suppressed locally using Liquid tags (_without_ the
+`linenos` option) instead of fences:
+
+{% highlight yaml %}
+{% raw %}{% highlight some_language %}
+Some code
+{% endhighlight %}{% endraw %}
+{% endhighlight %}
+
+## Workarounds
+
+To use HTML compression together with line numbers, all highlighted code
+needs to be wrapped using one of the following workarounds.
+(The variable name `some_var` can be changed to avoid clashes; it can also
+be replaced by `code` -- but note that `code=code` cannot be removed).
+
+### Code fences (three backticks)
+
+{% highlight default %}
+{% raw %}{% capture some_var %}
+```some_language
+Some code
+```
+{% endcapture %}
+{% assign some_var = some_var | markdownify %}
+{% include fix_linenos.html code=some_var %}{% endraw %}
+{% endhighlight %}
+
+### Liquid highlighting
+
+{% highlight default %}
+{% raw %}{% capture some_var %}
+{% highlight some_language linenos %}
+Some code
+{% endhighlight %}
+{% endcapture %}
+{% include fix_linenos.html code=some_var %}{% endraw %}
+{% endhighlight %}
+
+_Credit:_ The original version of the above workaround was suggested by
+Dmitry Hrabrov at
+<https://github.com/penibelst/jekyll-compress-html/issues/71#issuecomment-188144901>.
+
+## Examples
+
+✅ Using code fences + workaround (will only show line numbers if enabled globally in `_config.yml`):
+
+{% capture code_fence %}
+```js
+// Javascript code with syntax highlighting in fences
+var fun = function lang(l) {
+  dateformat.i18n = require('./lang/' + l)
+  return true;
+}
+```
+{% endcapture %}
+{% assign code_fence = code_fence | markdownify %}
+{% include fix_linenos.html code=code_fence %}
+
+✅ Using liquid highlighting + workaround:
+
+{% capture code %}
+{% highlight ruby linenos %}
+# Ruby code with syntax highlighting and fixed line numbers using Liquid
+GitHubPages::Dependencies.gems.each do |gem, version|
+  s.add_dependency(gem, "= #{version}")
+end
+{% endhighlight %}
+{% endcapture %}
+{% include fix_linenos.html code=code %}
+{% assign code = nil %}
+
+❌ With the default configuration options, the following example illustrates
+the **incorrect** formatting arising from the incompatibility of HTML compression
+and the non-conforming HTML produced by Jekyll for line numbers:
+
+{% highlight ruby linenos %}
+# Ruby code with syntax highlighting and unfixed line numbers using Liquid
+GitHubPages::Dependencies.gems.each do |gem, version|
+  s.add_dependency(gem, "= #{version}")
+end
+{% endhighlight %}

docs/ui-components/typography.md

@@ -21,7 +21,7 @@ nav_order: 1
 By default, Just the Docs uses a native system font stack for sans-serif fonts:
 
 ```scss
--apple-system, BlinkMacSystemFont, "helvetica neue", helvetica, roboto, noto, "segoe ui", arial, sans-serif
+system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
 ```
 
 ABCDEFGHIJKLMNOPQRSTUVWXYZ

index.md

@@ -4,7 +4,6 @@ title: Home
 nav_order: 1
 description: "Just the Docs is a responsive Jekyll theme with built-in search that is easily customizable and hosted on GitHub Pages."
 permalink: /
-last_modified_date: 2020-04-27T17:54:08+0000
 ---
 
 # Focus on writing good documentation

just-the-docs.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name          = "just-the-docs"
-  spec.version       = "0.2.9"
+  spec.version       = "0.3.2"
   spec.authors       = ["Patrick Marsceill"]
   spec.email         = ["patrick.marsceill@gmail.com"]
 
@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.executables   << 'just-the-docs'
 
   spec.add_development_dependency "bundler", "~> 2.1.4"
-  spec.add_runtime_dependency "jekyll", ">= 3.8.5", "< 4.1.0"
+  spec.add_runtime_dependency "jekyll", ">= 3.8.5"
   spec.add_runtime_dependency "jekyll-seo-tag", "~> 2.0"
   spec.add_runtime_dependency "rake", ">= 12.3.1", "< 13.1.0"
 

lib/tasks/search.rake

@@ -3,23 +3,82 @@ namespace :search do
   task :init do
     puts 'Creating search data json file...'
     mkdir_p 'assets/js'
-    touch 'assets/js/search-data.json'
-    content = %Q[{{ page.content | markdownify | replace: '</h', ' . </h' | replace: '<hr', ' . <hr' | replace: '</p', ' . </p' | replace: '</ul', ' . </ul' | replace: '</tr', ' . </tr' | replace: '</li', ' | </li' | replace: '</td', ' | </td' | strip_html | escape_once | remove: 'Table of contents' | remove: '```'  | remove: '---' | replace: '\\', ' ' | replace: ' .  .  . ', ' . ' | replace: ' .  . ', ' . ' | normalize_whitespace }}]
+    touch 'assets/js/zzzz-search-data.json'
     puts 'Done.'
     puts 'Generating content...'
 
-    File.open('assets/js/search-data.json', 'w') do |f|
+    File.open('assets/js/zzzz-search-data.json', 'w') do |f|
       f.puts '---
+permalink: /assets/js/search-data.json
 ---
 {
-  {% assign comma = false %}
-  {% for page in site.html_pages %}{% if page.search_exclude != true %}{% if comma == true%},{% endif %}"{{ forloop.index0 }}": {
-    "title": "{{ page.title | replace: \'&amp;\', \'&\' }}",
-    "content": "'+content+'",
-    "url": "{{ page.url | absolute_url }}",
+{%- assign i = 0 -%}
+{%- assign pages_array = '' | split: '' -%}
+{%- assign pages_array = pages_array | push: site.html_pages -%}
+{%- if site.just_the_docs.collections -%}
+  {%- 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.search_exclude != true -%}
+      {%- assign pages_array = pages_array | push: collection -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+{%- for pages in pages_array -%}
+  {%- for page in pages -%}
+    {%- if page.title and page.search_exclude != true -%}
+      {%- assign page_content = page.content -%}
+      {%- assign heading_level = site.search.heading_level | default: 2 -%}
+      {%- for j in (2..heading_level) -%}
+        {%- assign tag = \'<h\' | append: j -%}
+        {%- assign closing_tag = \'</h\' | append: j -%}
+        {%- assign page_content = page_content | replace: tag, \'<h1\' | replace: closing_tag, \'</h1\' -%}
+      {%- endfor -%}
+      {%- assign parts = page_content | split: \'<h1\' -%}
+      {%- assign title_found = false -%}
+      {%- for part in parts offset: 1 -%}
+        {%- assign titleAndContent = part | split: \'</h1>\' -%}
+        {%- assign title = titleAndContent[0] | replace_first: \'>\', \'<h1>\' | split: \'<h1>\' -%}
+        {%- assign title = title[1] | strip_html -%}
+        {%- assign content = titleAndContent[1] -%}
+        {%- assign url = page.url -%}
+        {%- if title == page.title and parts[0] == \'\' -%}
+          {%- assign title_found = true -%}
+        {%- else -%}
+          {%- assign id = titleAndContent[0] -%}
+          {%- assign id = id | split: \'id="\' -%}
+          {%- if id.size == 2 -%}
+            {%- assign id = id[1] -%}
+            {%- assign id = id | split: \'"\' -%}
+            {%- assign id = id[0] -%}
+            {%- capture url -%}{{ url | append: \'#\' | append: id }}{%- endcapture -%}
+          {%- endif -%}
+        {%- endif -%}
+  {%- unless i == 0 -%},{%- endunless -%}
+  "{{ i }}": {
+    "doc": {{ page.title | jsonify }},
+    "title": {{ title | jsonify }},
+    "content": {{ content | replace: \'</h\', \' . </h\' | replace: \'<hr\', \' . <hr\' | replace: \'</p\', \' . </p\' | replace: \'<ul\', \' . <ul\' | replace: \'</ul\', \' . </ul\' | replace: \'<ol\', \' . <ol\' | replace: \'</ol\', \' . </ol\' | replace: \'</tr\', \' . </tr\' | replace: \'<li\', \' | <li\' | replace: \'</li\', \' | </li\' | replace: \'</td\', \' | </td\' | replace: \'<td\', \' | <td\' | replace: \'</th\', \' | </th\' | replace: \'<th\', \' | <th\' | strip_html | remove: \'Table of contents\' | normalize_whitespace | replace: \'. . .\', \'.\' | replace: \'. .\', \'.\' | replace: \'| |\', \'|\' | append: \' \' | jsonify }},
+    "url": "{{ url | relative_url }}",
+    "relUrl": "{{ url }}"
+  }
+        {%- assign i = i | plus: 1 -%}
+      {%- endfor -%}
+      {%- unless title_found -%}
+  {%- unless i == 0 -%},{%- endunless -%}
+  "{{ i }}": {
+    "doc": {{ page.title | jsonify }},
+    "title": {{ page.title | jsonify }},
+    "content": {{ parts[0] | replace: \'</h\', \' . </h\' | replace: \'<hr\', \' . <hr\' | replace: \'</p\', \' . </p\' | replace: \'<ul\', \' . <ul\' | replace: \'</ul\', \' . </ul\' | replace: \'<ol\', \' . <ol\' | replace: \'</ol\', \' . </ol\' | replace: \'</tr\', \' . </tr\' | replace: \'<li\', \' | <li\' | replace: \'</li\', \' | </li\' | replace: \'</td\', \' | </td\' | replace: \'<td\', \' | <td\' | replace: \'</th\', \' | </th\' | replace: \'<th\', \' | <th\' | strip_html | remove: \'Table of contents\' | normalize_whitespace | replace: \'. . .\', \'.\' | replace: \'. .\', \'.\' | replace: \'| |\', \'|\' | append: \' \' | jsonify }},
+    "url": "{{ page.url | relative_url }}",
     "relUrl": "{{ page.url }}"
-  }{% assign comma = true %}
-  {% endif %}{% endfor %}
+  }
+        {%- assign i = i | plus: 1 -%}
+      {%- endunless -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endfor %}
 }'
     end
     puts 'Done.'

package.json

@@ -1,15 +1,15 @@
 {
   "name": "just-the-docs",
-  "version": "0.2.9",
+  "version": "0.3.2",
   "description": "A modern Jekyll theme for documentation",
   "repository": "pmarsceill/just-the-docs",
   "license": "MIT",
   "bugs": "https://github.com/pmarsceill/just-the-docs/issues",
   "devDependencies": {
-    "@primer/css": "^14.3.0",
-    "prettier": "^2.0.5",
-    "stylelint": "^13.3.3",
-    "stylelint-config-prettier": "^8.0.1",
+    "@primer/css": "^15.1.0",
+    "prettier": "^2.1.1",
+    "stylelint": "^13.6.1",
+    "stylelint-config-prettier": "^8.0.2",
     "stylelint-config-primer": "^9.0.0",
     "stylelint-prettier": "^1.1.2",
     "stylelint-selector-no-utility": "^4.0.0"