steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-09-14 05:43:33 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into custom-schemes

Browse Source
This commit is contained in:
Matt Wang
2023-10-25 14:52:10 -07:00
committed by GitHub
parent a2fcb2120e 870a6a4ff6
commit 720b0ebf9f
64 changed files with 2305 additions and 1153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
_includes/components/breadcrumbs.html
View File

@@ -1,15 +1,51 @@
{% unless page.url == "/" %}
{% if page.parent %}
<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>
<li class="breadcrumb-nav-list-item"><a href="{{ second_level_url }}">{{ page.parent }}</a></li>
{% else %}
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.parent }}</a></li>
{% endif %}
<li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
</ol>
</nav>
{% endif %}
{% endunless %}
{%- comment -%}
Include as: {%- include components/breadcrumbs.html -%}
Depends on: page, site.
Results in: HTML for the breadcrumbs component.
Overwrites:
node, pages_list, parent_page, grandparent_page.
{%- endcomment -%}
{%- if page.url != "/" and page.parent -%}
{%- assign pages_list = site[page.collection] | default: site.html_pages -%}
{%- assign parent_page = nil -%}
{%- assign grandparent_page = nil -%}
{%- for node in pages_list -%}
{%- if node.has_children and page.grand_parent -%}
{%- if node.title == page.parent and node.parent == page.grand_parent -%}
{%- assign parent_page = node -%}
{%- endif -%}
{%- if node.title == page.grand_parent -%}
{%- assign grandparent_page = node -%}
{%- endif -%}
{%- if parent_page and grandparent_page -%}
{%- break -%}
{%- endif -%}
{%- elsif node.has_children and node.title == page.parent and node.parent == nil -%}
{%- assign parent_page = node -%}
{%- break -%}
{%- endif -%}
{%- endfor -%}
<nav aria-label="Breadcrumb" class="breadcrumb-nav">
<ol class="breadcrumb-nav-list">
{% if page.parent -%}
{%- if page.grand_parent %}
<li class="breadcrumb-nav-list-item"><a href="{{ grandparent_page.url | relative_url }}">{{ page.grand_parent }}</a></li>
{%- endif %}
<li class="breadcrumb-nav-list-item"><a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a></li>
{% endif -%}
<li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
</ol>
</nav>
{%- endif -%}

34
_includes/components/children_nav.html
View File

@@ -1,9 +1,33 @@
{%- comment -%}
Include as: {%- include components/children_nav.html -%}
Depends on: page, site.
Results in: HTML for the children-navigation component.
Includes:
sorted_pages.html
toc_heading_custom.html
Overwrites:
child_pages.
{%- endcomment -%}
{%- if page.has_children == true and page.has_toc != false -%}
{%- assign child_pages = site[page.collection]
| default: site.html_pages
| where: "parent", page.title
| where: "grand_parent", page.parent -%}
{%- include sorted_pages.html pages = child_pages -%}
{%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
{%- assign sorted_pages = sorted_pages | reverse -%}
{%- endif -%}
{%- endif -%}
<hr>
{% include toc_heading_custom.html %}
<ul>
{% for child in include.toc_list %}
<li>
<a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
</li>
{% endfor %}
{% for child in sorted_pages %}
<li>
<a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
</li>
{% endfor %}
</ul>

75
_includes/components/nav.html Normal file
View File

@@ -0,0 +1,75 @@
{%- comment -%}
Include as: {%- include components/nav.html pages=pages -%}
Depends on: include.pages.
Results in: HTML for the navigation panel.
Includes:
sorted_pages.html
Overwrites:
nav_pages, first_level_pages, second_level_pages, third_level_pages,
node, children_list, child, grand_children_list, grand_child.
{%- endcomment -%}
{%- assign nav_pages = include.pages
| where_exp: "item", "item.title != nil"
| where_exp: "item", "item.nav_exclude != true" -%}
{%- include sorted_pages.html pages = nav_pages -%}
{%- comment -%}
It might be more efficient to sort the pages at each level separately.
{%- endcomment -%}
{%- assign first_level_pages = sorted_pages
| where_exp: "item", "item.parent == nil" -%}
{%- assign second_level_pages = sorted_pages
| where_exp: "item", "item.parent != nil"
| where_exp: "item", "item.grand_parent == nil" -%}
{%- assign third_level_pages = sorted_pages
| where_exp: "item", "item.grand_parent != nil" -%}
<ul class="nav-list">
{%- for node in first_level_pages -%}
<li class="nav-list-item">
{%- if node.has_children -%}
<button class="nav-list-expander btn-reset" aria-label="toggle items in {{ node.title }} category" aria-pressed="false">
<svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
</button>
{%- endif -%}
<a href="{{ node.url | relative_url }}" class="nav-list-link">{{ node.title }}</a>
{%- if node.has_children -%}
{%- assign children_list = second_level_pages
| where: "parent", node.title -%}
{%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
{%- assign children_list = children_list | reverse -%}
{%- endif -%}
<ul class="nav-list">
{%- for child in children_list -%}
<li class="nav-list-item">
{%- if child.has_children -%}
<button class="nav-list-expander btn-reset" aria-label="toggle items in {{ child.title }} category" aria-pressed="false">
<svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>
</button>
{%- endif -%}
<a href="{{ child.url | relative_url }}" class="nav-list-link">{{ child.title }}</a>
{%- if child.has_children -%}
{%- assign grand_children_list = third_level_pages
| where: "parent", child.title
| where: "grand_parent", node.title -%}
{%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
{%- assign grand_children_list = grand_children_list | reverse -%}
{%- endif -%}
<ul class="nav-list">
{%- for grand_child in grand_children_list -%}
<li class="nav-list-item">
<a href="{{ grand_child.url | relative_url }}" class="nav-list-link">{{ grand_child.title }}</a>
</li>
{%- endfor -%}
</ul>
{%- endif -%}
</li>
{%- endfor -%}
</ul>
{%- endif -%}
</li>
{%- endfor -%}
</ul>

6
_includes/components/search_footer.html
View File

@@ -1,7 +1,7 @@
{% 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>
<button id="search-button" class="search-button btn-reset" aria-label="Focus on search">
<svg viewBox="0 0 24 24" class="icon" aria-hidden="true"><use xlink:href="#svg-search"></use></svg>
</button>
{% endif %}
<div class="search-overlay"></div>

2
_includes/components/search_header.html
View File

@@ -1,6 +1,6 @@
{% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %}
<div class="search">
<div class="search" role="search">
<div class="search-input-wrap">
<input type="text" id="search-input" class="search-input" tabindex="0" placeholder="{{ search_placeholder | strip_html | strip }}" aria-label="{{ search_placeholder | strip_html| strip }}" 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>

71
_includes/components/sidebar.html
View File

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

67
_includes/components/site_nav.html Normal file
View File

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

281
_includes/css/activation.scss.liquid Normal file
View File

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

23
_includes/favicon.html Normal file
View File

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

27
_includes/head.html
View File

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

251
_includes/nav.html
View File

@@ -1,251 +0,0 @@
{%- comment -%}
The `nav_order` values of pages affect the order in which they are shown in
the navigation panel and in the automatically generated tables of contents.
Sibling pages with the same `nav_order` value may be shown in any order.
Sibling pages with no `nav_order` value are shown after all pages that have
explicit `nav_order` values, ordered by their `title` values.
The `nav_order` and `title` values can be numbers or strings. To avoid build
failures, we sort numbers and strings separately. We sort numbers by their
values, and strings lexicographically. The case-sensitivity of string sorting
is determined by the configuration setting of `nav_sort`. Pages with no `title`
value are excluded from the navigation.
Note: Numbers used as `title` or `nav_order` values should not be in quotes,
unless you intend them to be lexicographically ordered. Numbers are written
without spaces or thousands-separators. Negative numbers are preceded by `-`.
Floats are written with the integral and fractional parts separated by `.`.
(Bounds on the magnitude and precision are presumably the same as in Liquid.)
{%- endcomment -%}
{%- assign title_pages = include.pages
| where_exp: "item", "item.title != nil" -%}
{%- comment -%}
A page with `nav_exclude: true` does not appear in the main navigation.
If it has a `parent`, it may appear in the parent's table of contents.
If it specifies `has_children: true`, it should appear in the breadcrumbs
of the child pages, but its order in relation to other pages is irrelevant.
Pages that never appear can be removed from the pages that need to be sorted.
This optimisation can be significant on a site with many pages.
In Jekyll 4, the pages to be sorted can be filtered by:
{%- assign title_pages = title_pages
| where_exp: "item", "item.nav_exclude != true or item.parent != nil" -%}
That filter is not allowed in Jekyll 3. The following iterative code gives the
same effect, but it is activated only when it will filter more than 50% of the
pages.
{%- endcomment -%}
{%- unless title_pages == empty -%}
{%- assign unsorted_pages = title_pages
| where_exp: "item", "item.parent == nil"
| where_exp: "item", "item.nav_exclude == true" -%}
{%- assign title_pages_size = title_pages.size -%}
{%- assign unsorted_pages_percent = unsorted_pages.size
| times: 100 | divided_by: title_pages_size -%}
{%- if unsorted_pages_percent > 50 -%}
{%- assign sorted_pages = "" | split: "" -%}
{%- for item in title_pages -%}
{%- if item.nav_exclude != true or item.parent -%}
{%- assign sorted_pages = sorted_pages | push: item -%}
{%- endif -%}
{%- endfor -%}
{%- assign title_pages = sorted_pages -%}
{%- endif -%}
{%- endunless -%}
{%- assign nav_order_pages = title_pages
| where_exp: "item", "item.nav_order != nil" -%}
{%- assign title_order_pages = title_pages
| where_exp: "item", "item.nav_order == nil" -%}
{%- comment -%}
Divide the arrays of `nav_order_pages` and `title_order_pages` according to
the type of value.
The first character of the result of `jsonify` is `"` only for strings.
Grouping by a single character also ensures the number of groups is small.
{%- endcomment -%}
{%- assign nav_number_pages = "" | split: "" -%}
{%- assign nav_string_pages = "" | split: "" -%}
{%- assign nav_order_groups = nav_order_pages
| group_by_exp: "item", "item.nav_order | jsonify | slice: 0" -%}
{%- for group in nav_order_groups -%}
{%- if group.name == '"' -%}
{%- assign nav_string_pages = group.items -%}
{%- else -%}
{%- assign nav_number_pages = nav_number_pages | concat: group.items -%}
{%- endif -%}
{%- endfor -%}
{%- unless nav_number_pages == empty -%}
{%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
{%- endunless -%}
{%- unless nav_string_pages == empty -%}
{%- if site.nav_sort == 'case_insensitive' -%}
{%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%}
{%- else -%}
{%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%}
{%- endif -%}
{%- endunless -%}
{%- assign title_number_pages = "" | split: "" -%}
{%- assign title_string_pages = "" | split: "" -%}
{%- assign title_order_groups = title_order_pages
| group_by_exp: "item", "item.title | jsonify | slice: 0" -%}
{%- for group in title_order_groups -%}
{%- if group.name == '"' -%}
{%- assign title_string_pages = group.items -%}
{%- else -%}
{%- assign title_number_pages = title_number_pages | concat: group.items -%}
{%- endif -%}
{%- endfor -%}
{%- unless title_number_pages == empty -%}
{%- assign title_number_pages = title_number_pages | sort: "title" -%}
{%- endunless -%}
{%- unless title_string_pages == empty -%}
{%- if site.nav_sort == 'case_insensitive' -%}
{%- assign title_string_pages = title_string_pages | sort_natural: "title" -%}
{%- else -%}
{%- assign title_string_pages = title_string_pages | sort: "title" -%}
{%- endif -%}
{%- endunless -%}
{%- assign pages_list = nav_number_pages | concat: nav_string_pages
| concat: title_number_pages | concat: title_string_pages -%}
{%- assign first_level_pages = pages_list
| where_exp: "item", "item.parent == nil" -%}
{%- assign second_level_pages = pages_list
| where_exp: "item", "item.parent != nil"
| where_exp: "item", "item.grand_parent == nil" -%}
{%- assign third_level_pages = pages_list
| where_exp: "item", "item.grand_parent != nil" -%}
{%- comment -%}
The order of sibling pages in `pages_list` determines the order of display of
links to them in lists of navigation links and in auto-generated TOCs.
Note that Liquid evaluates conditions from right to left (and it does not allow
the use of parentheses). Some conditions are not so easy to express clearly...
For example, consider the following condition:
C: page.collection = = include.key and
page.url = = node.url or
page.grand_parent = = node.title or
page.parent = = node.title and
page.grand_parent = = nil
Here, `node` is a first-level page. The last part of the condition
-- namely: `page.parent = = node.title and page.grand_parent = = nil` --
is evaluated first; it holds if and only if `page` is a child of `node`.
The condition `page.grand_parent = = node.title or ...` holds when
`page` is a grandchild of node, OR `...` holds.
The condition `page.url = = node.url or ...` holds when
`page` is `node`, OR `...` holds.
The condition C: `page.collection = = include.key and ...` holds when we are
generating the nav links for a collection that includes `page`, AND `...` holds.
{%- endcomment -%}
<ul class="nav-list">
{%- for node in first_level_pages -%}
{%- unless node.nav_exclude -%}
<li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil %} active{% endif %}">
{%- if node.has_children -%}
<a href="#" class="nav-list-expander" aria-label="toggle links in {{ node.title }} category">
<svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
</a>
{%- endif -%}
<a href="{{ node.url | relative_url }}" class="nav-list-link{% if page.url == node.url %} active{% endif %}">{{ node.title }}</a>
{%- if node.has_children -%}
{%- assign children_list = second_level_pages
| where: "parent", node.title -%}
{%- if node.child_nav_order == 'desc' or node.child_nav_order == 'reversed' -%}
{%- assign children_list = children_list | reverse -%}
{%- endif -%}
<ul class="nav-list">
{%- for child in children_list -%}
{%- unless child.nav_exclude -%}
<li class="nav-list-item {% if page.url == child.url or page.parent == child.title %} active{% endif %}">
{%- if child.has_children -%}
<a href="#" class="nav-list-expander" aria-label="toggle links in {{ child.title }} category">
<svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg>
</a>
{%- endif -%}
<a href="{{ child.url | relative_url }}" class="nav-list-link{% if page.url == child.url %} active{% endif %}">{{ child.title }}</a>
{%- if child.has_children -%}
{%- assign grand_children_list = third_level_pages
| where: "parent", child.title
| where: "grand_parent", node.title -%}
{%- if child.child_nav_order == 'desc' or child.child_nav_order == 'reversed' -%}
{%- assign grand_children_list = grand_children_list | reverse -%}
{%- endif -%}
<ul class="nav-list">
{%- for grand_child in grand_children_list -%}
{%- unless grand_child.nav_exclude -%}
<li class="nav-list-item {% if page.url == grand_child.url %} active{% endif %}">
<a href="{{ grand_child.url | relative_url }}" class="nav-list-link{% if page.url == grand_child.url %} active{% endif %}">{{ grand_child.title }}</a>
</li>
{%- endunless -%}
{%- endfor -%}
</ul>
{%- endif -%}
</li>
{%- endunless -%}
{%- endfor -%}
</ul>
{%- endif -%}
</li>
{%- endunless -%}
{%- endfor -%}
</ul>
{%- comment -%}
`page.collection` is the name of the Jekyll collection that contains the page,
if any, and otherwise nil. Similarly for `include.key`.
If the current page is in the collection (if any) whose navigation is currently
being generated, the following code sets `first_level_url` to the URL used in
the page's top-level breadcrumb (if any), and `second_level_url` to that used
in the page's second-level breadcrumb (if any).
For pages with children, the code also sets `toc_list` to the list of child pages,
reversing the order if needed.
{%- endcomment -%}
{%- if page.collection == include.key -%}
{%- for node in first_level_pages -%}
{%- if page.grand_parent == node.title or page.parent == node.title and page.grand_parent == nil -%}
{%- assign first_level_url = node.url | relative_url -%}
{%- endif -%}
{%- if node.has_children -%}
{%- assign children_list = second_level_pages | where: "parent", node.title -%}
{%- for child in children_list -%}
{%- if child.has_children -%}
{%- if page.url == child.url or page.parent == child.title and page.grand_parent == child.parent -%}
{%- assign second_level_url = child.url | relative_url -%}
{%- endif -%}
{%- endif -%}
{%- endfor -%}
{%- endif -%}
{%- endfor -%}
{%- if page.has_children == true and page.has_toc != false -%}
{%- assign toc_list = pages_list
| where: "parent", page.title
| where_exp: "item", "item.grand_parent == page.parent" -%}
{%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
{%- assign toc_list = toc_list | reverse -%}
{%- endif -%}
{%- endif -%}
{%- endif -%}

109
_includes/sorted_pages.html Normal file
View File

@@ -0,0 +1,109 @@
{%- comment -%}
Include as: {%- include sorted_pages.html pages=array_of_pages -%}
Depends on: include.pages.
Assigns to: sorted_pages.
Overwrites:
nav_order_pages, title_order_pages, double_quote, empty_array,
nav_number_pages, nav_string_pages, nav_order_groups, group,
title_number_pages, title_string_pages, title_order_groups.
{%- endcomment -%}
{%- comment -%}
The `nav_order` values of pages affect the order in which they are shown in
the navigation panel and in the automatically generated tables of contents.
Sibling pages with the same `nav_order` value may be shown in any order.
Sibling pages with no `nav_order` value are shown after all pages that have
explicit `nav_order` values, ordered by their `title` values.
The `nav_order` and `title` values can be numbers or strings. To avoid build
failures, we sort numbers and strings separately. We sort numbers by their
values, and strings lexicographically. The case-sensitivity of string sorting
is determined by the configuration setting of `nav_sort`. Pages with no `title`
value are excluded from the navigation.
Note: Numbers used as `title` or `nav_order` values should not be in quotes,
unless you intend them to be lexicographically ordered. Numbers are written
without spaces or thousands-separators. Negative numbers are preceded by `-`.
Floats are written with the integral and fractional parts separated by `.`.
(Bounds on the magnitude and precision are presumably the same as in Liquid.)
{%- endcomment -%}
{%- assign nav_order_pages = include.pages
| where_exp: "item", "item.nav_order != nil" -%}
{%- assign title_order_pages = include.pages
| where_exp: "item", "item.nav_order == nil" -%}
{%- comment -%}
First, filter `nav_order_pages` and `title_order_pages` according to the type
of value to be used for sorting.
The first character of the result of filtering with `jsonify` is `"` only for
strings. Removing `"` from its `slice : 0` has size 0 for strings and 1 for
numbers, so grouping the pages gives at most two groups.
{%- endcomment -%}
{%- assign double_quote = '"' -%}
{%- assign empty_array = "" | split: "" -%}
{%- assign nav_string_pages = empty_array -%}
{%- assign nav_number_pages = empty_array -%}
{%- unless nav_order_pages == empty -%}
{%- assign nav_order_groups = nav_order_pages
| group_by_exp: "item",
"item.nav_order | jsonify | slice: 0 | remove: double_quote | size" -%}
{%- for group in nav_order_groups -%}
{%- if group.name == 0 -%}
{%- assign nav_string_pages = group.items -%}
{%- elsif group.name == 1 -%}
{%- assign nav_number_pages = group.items -%}
{%- endif -%}
{%- endfor -%}
{%- endunless -%}
{%- assign title_string_pages = empty_array -%}
{%- assign title_number_pages = empty_array -%}
{%- unless title_order_pages == empty -%}
{%- assign title_order_groups = title_order_pages
| group_by_exp: "item",
"item.title | jsonify | slice: 0 | remove: double_quote | size" -%}
{%- for group in title_order_groups -%}
{%- if group.name == 0 -%}
{%- assign title_string_pages = group.items -%}
{%- elsif group.name == 1 -%}
{%- assign title_number_pages = group.items -%}
{%- endif -%}
{%- endfor -%}
{%- endunless -%}
{%- comment -%}
Now sort each array of pages separately, then concatenate the sorted arrays.
{%- endcomment -%}
{%- unless nav_number_pages == empty -%}
{%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
{%- endunless -%}
{%- unless nav_string_pages == empty -%}
{%- if site.nav_sort == 'case_insensitive' -%}
{%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%}
{%- else -%}
{%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%}
{%- endif -%}
{%- endunless -%}
{%- unless title_number_pages == empty -%}
{%- assign title_number_pages = title_number_pages | sort: "title" -%}
{%- endunless -%}
{%- unless title_string_pages == empty -%}
{%- if site.nav_sort == 'case_insensitive' -%}
{%- assign title_string_pages = title_string_pages | sort_natural: "title" -%}
{%- else -%}
{%- assign title_string_pages = title_string_pages | sort: "title" -%}
{%- endif -%}
{%- endunless -%}
{%- assign sorted_pages = nav_number_pages
| concat: nav_string_pages
| concat: title_number_pages
| concat: title_string_pages -%}

2
_includes/title.html
View File

@@ -1,5 +1,5 @@
{% if site.logo %}
<div class="site-logo"></div>
<div class="site-logo" role="img" aria-label="{{ site.title }}"></div>
{% else %}
{{ site.title }}
{% endif %}