Skip to content

Commit 696126e

Browse files
authored
Merge branch 'just-the-docs:main' into a11y-specs
2 parents 7f9bf33 + 26be7e9 commit 696126e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

57 files changed

+1232
-937
lines changed

CHANGELOG.md

+8-3
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,16 @@ This website is built from the `HEAD` of the `main` branch of the theme reposito
1717

1818
Code changes to `main` that are *not* in the latest release:
1919

20-
- N/A
20+
### New Features
21+
22+
- Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1431]
2123

2224
Docs changes made since the latest release:
2325

24-
- N/A
26+
- Added: Allow unlimited multi-level navigation by [@pdmosses] in [#1440]
27+
28+
[#1431]: https://github.com/just-the-docs/just-the-docs/pull/1431
29+
[#1440]: https://github.com/just-the-docs/just-the-docs/pull/1440
2530

2631
## Release v0.9.0
2732

@@ -601,7 +606,7 @@ We're so excited to release Just the Docs `v0.4.0`. This release has been almost
601606
- [callouts](https://just-the-docs.com/docs/ui-components/callouts/), a new design component to highlight content
602607
- [configuring mermaid.js](https://just-the-docs.com/docs/ui-components/code/#mermaid-diagram-code-blocks), a markdown-native diagram visualization library
603608
- [copy code button](https://just-the-docs.com/docs/ui-components/code/#copy-button) for code snippets
604-
- [external navigation links](https://just-the-docs.com/docs/navigation-structure/#external-navigation-links)
609+
- external navigation links
605610
- major improvements to nav generation efficiency and robustness
606611
- minor improvements to built-in accessibility (SVG icons, nav titles, skip to main content)
607612
- [modularized site components](https://just-the-docs.com/docs/customization/#custom-layouts-and-includes) (advanced feature)

MIGRATION.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ This document contains instructions on how to migrate and upgrade Just the Docs
4141
> and pull the changes of a new release to your clone,
4242
> you may need to resolve merge conflicts.
4343
44-
[CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
44+
[CHANGELOG]: {% link CHANGELOG.md %}
4545

4646
## v0.6.x - v0.7.0
4747

@@ -373,7 +373,7 @@ For changes since v0.3.3, the log usually references the merged PR that made the
373373

374374
#### Configuration
375375

376-
- Mermaid support: first-class support for [Mermaid](https://mermaid.js.org/) - a JavaScript-based diagram and charting tool supported by GitHub - has been added to the theme. **This feature is opt-in.** See the new doc subsections in [Configuration]({% link docs/configuration.md %}#mermaid-diagrams) and [Code]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more.
376+
- Mermaid support: first-class support for [Mermaid](https://mermaid.js.org/) - a JavaScript-based diagram and charting tool supported by GitHub - has been added to the theme. **This feature is opt-in.** See the new doc subsections in [Configuration]({% link docs/configuration.md %}#mermaid-diagrams) and [Code]({% link docs/ui-components/code/index.md %}#mermaid-diagram-code-blocks) for more.
377377
- Multiple Google Analytics tags are now supported. PR: [#1029]
378378

379379
#### Customization

_config.yml

+11
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,14 @@ repository: just-the-docs/just-the-docs # for github-metadata
2121

2222
permalink: pretty
2323

24+
defaults:
25+
-
26+
scope:
27+
path: "docs" # an empty string here means all files in the project
28+
type: "pages"
29+
values:
30+
layout: "default"
31+
2432
exclude:
2533
# from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml:
2634
- .sass-cache/
@@ -125,6 +133,9 @@ nav_external_links:
125133
- title: Just the Docs on GitHub
126134
url: https://github.com/just-the-docs/just-the-docs
127135

136+
# Show navigation error report
137+
nav_error_report: true # default is false/nil.
138+
128139
liquid:
129140
error_mode: strict
130141
strict_filters: true

_includes/components/breadcrumbs.html

+60-108
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,96 @@
11
{%- comment -%}
22
Include as: {%- include components/breadcrumbs.html -%}
33
Depends on: page, site.
4+
Includes: components/site_nav.html.
45
Results in: HTML for the breadcrumbs component.
56
Overwrites:
6-
node, pages_list, parent_page, grandparent_page.
7+
nav_list_link, site_nav, nav_list_simple, nav_list_link_class, nav_category,
8+
nav_anchor_splits, nav_breadcrumbs, nav_split, nav_split_next, nav_split_test,
9+
nav_breadcrumb_link, nav_list_end_less, nav_list_end_count, nav_end_index, nav_breadcrumb.
710
{%- endcomment -%}
811

9-
{%- if page.url != "/" and page.parent -%}
12+
{%- if page.url != "/" and page.parent and page.title -%}
1013

1114
{%- capture nav_list_link -%}
1215
<a href="{{ page.url | relative_url }}" class="nav-list-link">
1316
{%- endcapture -%}
1417

1518
{%- capture site_nav -%}
16-
{%- include_cached components/site_nav.html -%}
19+
{%- include_cached components/site_nav.html all=true -%}
1720
{%- endcapture -%}
1821

19-
{%- if site_nav contains nav_list_link -%}
20-
21-
{%- capture nav_list_simple -%}
22-
<ul class="nav-list">
23-
{%- endcapture -%}
24-
25-
{%- capture nav_list_link_class %} class="nav-list-link">
26-
{%- endcapture -%}
27-
28-
{%- capture nav_category -%}
29-
<div class="nav-category">
30-
{%- endcapture -%}
31-
32-
{%- assign nav_anchor_splits =
33-
site_nav | split: nav_list_link |
34-
first | split: nav_category |
35-
last | split: "</a>" -%}
36-
37-
{%- comment -%}
38-
The ordinary pages (if any) and the collections pages (if any) are separated by
39-
occurrences of nav_category.
40-
41-
Any ancestor nav-links of the page are contained in the last group of pages,
42-
immediately preceding nav-lists. After splitting at "</a>", the anchor that
43-
was split is a potential ancestor link when the following split starts with
44-
a nav-list.
45-
46-
The array nav_breadcrumbs is the stack of current potential ancestors of the
47-
current page. A split that contains one or more "</ul>"s requires that number
48-
of potential ancestors to be popped from the stack.
49-
50-
The number of occurrences of a string in nav_split_next is computed by removing
51-
them all, then dividing the resulting size difference by the length of the string.
52-
{%- endcomment %}
53-
54-
{%- assign nav_breadcrumbs = "" | split: "" -%}
55-
56-
{%- for nav_split in nav_anchor_splits -%}
57-
{%- unless forloop.last -%}
58-
59-
{%- assign nav_split_next = nav_anchor_splits[forloop.index] | strip -%}
60-
61-
{%- assign nav_split_test =
62-
nav_split_next | remove_first: nav_list_simple | prepend: nav_list_simple -%}
63-
{%- if nav_split_test == nav_split_next -%}
64-
{%- assign nav_breadcrumb_link =
65-
nav_split | split: "<a " | last | prepend: "<a " |
66-
replace: nav_list_link_class, ">" | append: "</a>" -%}
67-
{%- assign nav_breadcrumbs = nav_breadcrumbs | push: nav_breadcrumb_link -%}
68-
{%- endif -%}
69-
70-
{%- if nav_split_next contains "</ul>" -%}
71-
{%- assign nav_list_end_less = nav_split_next | remove: "</ul>" -%}
72-
{%- assign nav_list_end_count =
73-
nav_split_next.size | minus: nav_list_end_less.size | divided_by: 5 -%}
74-
{% for nav_end_index in (1..nav_list_end_count) %}
75-
{%- assign nav_breadcrumbs = nav_breadcrumbs | pop -%}
76-
{%- endfor -%}
77-
{%- endif -%}
78-
79-
{%- endunless -%}
80-
{%- endfor -%}
22+
{%- capture nav_list_simple -%}
23+
<ul class="nav-list">
24+
{%- endcapture -%}
8125

82-
{%- assign nav_parent_link = nav_breadcrumbs[-1] -%}
83-
{%- assign nav_grandparent_link = nav_breadcrumbs[-2] -%}
26+
{%- capture nav_list_link_class %} class="nav-list-link">
27+
{%- endcapture -%}
8428

85-
{%- else -%}
29+
{%- capture nav_category -%}
30+
<div class="nav-category">
31+
{%- endcapture -%}
8632

87-
{%- comment -%}
88-
Pages whose links are excluded from the main navigation may still have
89-
breadcrumbs. Determining them appears to require inspecting the front matter
90-
of all the pages in the same group. For sites with 100s of pages, this is too
91-
inefficient in Jekyll 3 (also when the for-loop is replaced by where-filters).
92-
{%- endcomment -%}
33+
{%- assign nav_anchor_splits =
34+
site_nav | split: nav_list_link |
35+
first | split: nav_category |
36+
last | split: "</a>" -%}
9337

94-
{%- assign pages_list = site[page.collection] | default: site.html_pages -%}
38+
{%- comment -%}
39+
The ordinary pages (if any) and the collections pages (if any) are separated by
40+
occurrences of nav_category.
9541

96-
{%- assign parent_page = nil -%}
97-
{%- assign grandparent_page = nil -%}
98-
99-
{%- for node in pages_list -%}
42+
Any ancestor nav-links of the page are contained in the last group of pages,
43+
immediately preceding nav-lists. After splitting at "</a>", the anchor that
44+
was split is a potential ancestor link when the following split starts with
45+
a nav-list.
46+
47+
The array nav_breadcrumbs is the stack of current potential ancestors of the
48+
current page. A split that contains one or more "</ul>"s requires that number
49+
of potential ancestors to be popped from the stack.
10050

101-
{%- if node.has_children and page.grand_parent -%}
51+
The number of occurrences of a string in nav_split_next is computed by removing
52+
them all, then dividing the resulting size difference by the length of the string.
53+
{%- endcomment %}
10254

103-
{%- if node.title == page.parent and node.parent == page.grand_parent -%}
104-
{%- assign parent_page = node -%}
105-
{%- endif -%}
106-
{%- if node.title == page.grand_parent -%}
107-
{%- assign grandparent_page = node -%}
108-
{%- endif -%}
109-
{%- if parent_page and grandparent_page -%}
110-
{%- break -%}
111-
{%- endif -%}
55+
{%- assign nav_breadcrumbs = "" | split: "" -%}
11256

113-
{%- elsif node.has_children and node.title == page.parent and node.parent == nil -%}
57+
{%- for nav_split in nav_anchor_splits -%}
58+
{%- unless forloop.last -%}
11459

115-
{%- assign parent_page = node -%}
116-
{%- break -%}
60+
{%- assign nav_split_next = nav_anchor_splits[forloop.index] | strip -%}
11761

118-
{%- endif -%}
62+
{%- assign nav_split_test =
63+
nav_split_next | remove_first: nav_list_simple | prepend: nav_list_simple -%}
64+
{%- if nav_split_test == nav_split_next -%}
65+
{%- assign nav_breadcrumb_link =
66+
nav_split | split: "<a " | last | prepend: "<a " |
67+
replace: nav_list_link_class, ">" | append: "</a>" -%}
68+
{%- assign nav_breadcrumbs = nav_breadcrumbs | push: nav_breadcrumb_link -%}
69+
{%- endif -%}
11970

71+
{%- if nav_split_next contains "</ul>" -%}
72+
{%- assign nav_list_end_less = nav_split_next | remove: "</ul>" -%}
73+
{%- assign nav_list_end_count =
74+
nav_split_next.size | minus: nav_list_end_less.size | divided_by: 5 -%}
75+
{% for nav_end_index in (1..nav_list_end_count) %}
76+
{%- assign nav_breadcrumbs = nav_breadcrumbs | pop -%}
12077
{%- endfor -%}
121-
122-
{%- capture nav_parent_link -%}
123-
<a href="{{ parent_page.url | relative_url }}">{{ page.parent }}</a>
124-
{%- endcapture -%}
125-
126-
{%- if page.grand_parent %}
127-
{%- capture nav_grandparent_link -%}
128-
<a href="{{ grandparent_page.url | relative_url }}">{{ page.grand_parent }}</a>
129-
{%- endcapture -%}
130-
{%- endif -%}
131-
13278
{%- endif -%}
13379

80+
{%- endunless -%}
81+
{%- endfor -%}
82+
13483
<nav aria-label="Breadcrumb" class="breadcrumb-nav">
13584
<ol class="breadcrumb-nav-list">
136-
{%- if nav_grandparent_link %}
137-
<li class="breadcrumb-nav-list-item">{{ nav_grandparent_link }}</li>
138-
{%- endif %}
139-
<li class="breadcrumb-nav-list-item">{{ nav_parent_link }}</li>
85+
{%- for nav_breadcrumb in nav_breadcrumbs %}
86+
<li class="breadcrumb-nav-list-item">{{ nav_breadcrumb }}</li>
87+
{%- endfor %}
14088
<li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
14189
</ol>
14290
</nav>
14391

92+
{% if site.nav_error_report %}
93+
{{ nav_error_report }}
94+
{% endif %}
95+
14496
{%- endif -%}
+72-16
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,89 @@
11
{%- comment -%}
22
Include as: {%- include components/children_nav.html -%}
3-
Depends on: page, site.
3+
Depends on: page, site, nav_breadcrumbs.
44
Results in: HTML for the children-navigation component.
5-
Includes:
6-
sorted_pages.html
7-
toc_heading_custom.html
5+
Includes: components/nav/sorted.html, toc_heading_custom.html.
86
Overwrites:
9-
child_pages.
7+
nav_ancestor_links, nav_top_node_titles, nav_child_candidates, nav_children,
8+
nav_child, nav_child_ok, nav_child_ancestor, nav_sorted.
109
{%- endcomment -%}
1110

12-
{%- if page.has_children == true and page.has_toc != false -%}
13-
{%- assign child_pages = site[page.collection]
14-
| default: site.html_pages
15-
| where: "parent", page.title
16-
| where: "grand_parent", page.parent -%}
11+
{%- comment -%}
12+
Whether a page has any children is checked efficiently by inspecting the cached
13+
site_nav. If the page has no children, nav_children is set to an empty array;
14+
otherwise nav_children is left unset.
15+
{%- endcomment -%}
1716

18-
{%- include sorted_pages.html pages = child_pages -%}
17+
{%- if page.has_children == false -%}
18+
{%- assign nav_children = "" | split: "" -%}
19+
{%- else -%}
1920

20-
{%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
21-
{%- assign sorted_pages = sorted_pages | reverse -%}
21+
{%- assign nav_children = nil -%}
22+
23+
{%- capture nav_list_link -%}
24+
<a href="{{ page.url | relative_url }}" class="nav-list-link">
25+
{%- endcapture -%}
26+
27+
{%- capture site_nav -%}
28+
{%- include_cached components/site_nav.html all=true -%}
29+
{%- endcapture -%}
30+
31+
{%- capture nav_list_simple -%}
32+
<ul class="nav-list">
33+
{%- endcapture -%}
34+
35+
{%- assign nav_child_start = site_nav
36+
| split: nav_list_link | last
37+
| split: "</a>" | slice: 1 | first -%}
38+
39+
{%- assign nav_child_test = nav_child_start
40+
| remove_first: nav_list_simple | prepend: nav_list_simple -%}
41+
42+
{%- if nav_child_start != nav_child_test -%}
43+
{%- assign nav_children = "" | split: "" -%}
2244
{%- endif -%}
45+
2346
{%- endif -%}
2447

48+
{%- unless nav_children -%}
49+
50+
{%- comment -%}
51+
The layout is assumed to include components/breadcrumbs.html before this file,
52+
otherwise it needs to be included here.
53+
{%- endcomment -%}
54+
55+
{%- assign nav_ancestors = "" | split: "" -%}
56+
{%- for nav_link in nav_breadcrumbs -%}
57+
{%- assign nav_title = nav_link | split: ">" | slice: 1 | first | append: ">" | remove: "</a>" -%}
58+
{%- assign nav_ancestors = nav_ancestors | push: nav_title -%}
59+
{%- endfor -%}
60+
61+
{%- assign nav_parenthood = site[page.collection] | default: site.html_pages
62+
| where_exp: "item", "item.title != nil" | group_by: "parent" -%}
63+
64+
{%- assign nav_top_nodes = nav_parenthood
65+
| where_exp: "item", "item.name == ''" | map: "items" | first -%}
66+
67+
{% assign nav_top_node_titles = nav_top_nodes | map: "title" -%}
68+
69+
{%- include components/nav/children.html node=page ancestors=nav_ancestors all=true -%}
70+
71+
{%- endunless -%}
72+
73+
{%- if nav_children.size >= 1 -%}
74+
75+
{%- if page.child_nav_order == 'desc' or page.child_nav_order == 'reversed' -%}
76+
{%- assign nav_children = nav_children | reverse -%}
77+
{%- endif -%}
78+
2579
<hr>
2680
{% include toc_heading_custom.html %}
2781
<ul>
28-
{% for child in sorted_pages %}
82+
{% for nav_child in nav_children %}
2983
<li>
30-
<a href="{{ child.url | relative_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
84+
<a href="{{ nav_child.url | relative_url }}">{{ nav_child.title }}</a>{% if nav_child.summary %} - {{ nav_child.summary }}{% endif %}
3185
</li>
32-
{% endfor %}
86+
{% endfor %}
3387
</ul>
88+
89+
{%- endif -%}

0 commit comments

Comments
 (0)