Skip to content

Commit a7dd901

Browse files
chris-batemanchris-bateman
authored
chore: (mkdocs) upgrade mkdocs and material to latest versions (#158)
* Update mkdocs and material * override * Update material
1 parent 4239ecf commit a7dd901

5 files changed

Lines changed: 298 additions & 22 deletions

File tree

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ theme:
66
logo: img/sos.png
77
favicon: img/favicon.ico
88
custom_dir: overrides
9+
features:
10+
- navigation.sections
911
extra_css:
1012
- stylesheets/custom.css
1113
nav:

‎overrides/partials/header.html‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,30 +13,30 @@
1313
{% set site_url = site_url ~ "/index.html" %}
1414
{% endif %}
1515
<header class="md-header" data-md-component="header">
16-
<nav class="md-header-nav md-grid" aria-label="{{ lang.t('header.title') }}">
17-
<a href="{{ site_url }}" title="{{ config.site_name | e }}" class="md-header-nav__button md-logo" aria-label="{{ config.site_name }}">
16+
<nav class="md-header__inner md-grid" aria-label="{{ lang.t('header.title') }}">
17+
<a href="{{ site_url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}">
1818
{% include "partials/logo.html" %}
1919
</a>
2020
<!-- Button to open drawer -->
21-
<label class="md-header-nav__button md-icon" for="__drawer">
21+
<label class="md-header__button md-icon" for="__drawer">
2222
{% include ".icons/material/menu" ~ ".svg" %}
2323
</label>
24-
<div class="md-header-nav__title" data-md-component="header-title">
24+
<div class="md-header__title" data-md-component="header-title">
2525
{% if config.site_name == page.title %}
26-
<div class="md-header-nav__ellipsis md-ellipsis">
26+
<div class="md-header__ellipsis md-ellipsis">
2727
<a href="{{ site_url }}" title="{{ config.site_name | e }}">
2828

2929
{{ config.site_name }}
3030
</a>
3131
</div>
3232
{% else %}
33-
<div class="md-header-nav__ellipsis">
34-
<span class="md-header-nav__topic md-ellipsis">
33+
<div class="md-header__ellipsis">
34+
<span class="md-header__topic md-ellipsis">
3535
<a href="{{ site_url }}" title="{{ config.site_name | e }}" >
3636
{{ config.site_name }}
3737
</a>
3838
</span>
39-
<span class="md-header-nav__topic md-ellipsis">
39+
<span class="md-header__topic md-ellipsis">
4040
{% if page and page.meta and page.meta.title %}
4141
{{ page.meta.title }}
4242
{% else %}
@@ -46,14 +46,14 @@
4646
</div>
4747
{% endif %}
4848
</div>
49-
{% if "search" in config["plugins"] %}
50-
<label class="md-header-nav__button md-icon" for="__search">
49+
{% if "material/search" in config["plugins"] %}
50+
<label class="md-header__button md-icon" for="__search">
5151
{% include ".icons/material/magnify.svg" %}
5252
</label>
5353
{% include "partials/search.html" %}
5454
{% endif %}
5555
{% if config.repo_url %}
56-
<div class="md-header-nav__source">
56+
<div class="md-header__source">
5757
{% include "partials/source.html" %}
5858
</div>
5959
{% endif %}

‎overrides/partials/nav-item.html‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
<!-- Render navigation link status -->
2+
{% macro render_status(nav_item, type) %}
3+
{% set class = "md-status md-status--" ~ type %}
4+
5+
<!-- Render icon with title (or tooltip), if given -->
6+
{% if config.extra.status and config.extra.status[type] %}
7+
<span
8+
class="{{ class }}"
9+
title="{{ config.extra.status[type] }}"
10+
>
11+
</span>
12+
13+
<!-- Render icon only -->
14+
{% else %}
15+
<span class="{{ class }}"></span>
16+
{% endif %}
17+
{% endmacro %}
18+
19+
<!-- Render navigation link content -->
20+
{% macro render_content(nav_item, ref = nav_item) %}
21+
22+
<!-- Navigation link icon -->
23+
{% if nav_item.is_page and nav_item.meta.icon %}
24+
{% include ".icons/" ~ nav_item.meta.icon ~ ".svg" %}
25+
{% endif %}
26+
27+
<!-- Navigation link title -->
28+
<span class="md-ellipsis">
29+
{{ ref.title }}
30+
</span>
31+
32+
<!-- Navigation link status -->
33+
{% if nav_item.is_page and nav_item.meta.status %}
34+
{{ render_status(nav_item, nav_item.meta.status) }}
35+
{% endif %}
36+
{% endmacro %}
37+
38+
<!-- Render navigation item (pruned) -->
39+
{% macro render_pruned(nav_item, ref = nav_item) %}
40+
{% set first = nav_item.children | first %}
41+
42+
<!-- Recurse, if the first item has further nested items -->
43+
{% if first and first.children %}
44+
{{ render_pruned(first, ref) }}
45+
46+
<!-- Navigation link -->
47+
{% else %}
48+
<a href="{{ first.url | url }}" class="md-nav__link">
49+
{{ render_content(ref) }}
50+
51+
<!-- Only render toggle if there's at least one nested item -->
52+
{% if nav_item.children | length > 0 %}
53+
<span class="md-nav__icon md-icon"></span>
54+
{% endif %}
55+
</a>
56+
{% endif %}
57+
{% endmacro %}
58+
59+
<!-- Render navigation item -->
60+
{% macro render(nav_item, path, level) %}
61+
62+
<!-- Determine classes -->
63+
{% set class = "md-nav__item" %}
64+
{% if nav_item.active %}
65+
{% set class = class ~ " md-nav__item--active" %}
66+
{% endif %}
67+
68+
<!-- Determine active page for paginated views -->
69+
{% if nav_item.pages %}
70+
{% if page in nav_item.pages %}
71+
{% set nav_item = page %}
72+
{% endif %}
73+
{% endif %}
74+
75+
<!-- Navigation item with nested items -->
76+
{% if nav_item.children %}
77+
78+
<!-- Determine all nested items that are index pages -->
79+
{% set indexes = [] %}
80+
{% if "navigation.indexes" in features %}
81+
{% for nav_item in nav_item.children %}
82+
{% if nav_item.is_index and not index is defined %}
83+
{% set _ = indexes.append(nav_item) %}
84+
{% endif %}
85+
{% endfor %}
86+
{% endif %}
87+
88+
<!-- Navigation tabs -->
89+
{% if "navigation.tabs" in features %}
90+
91+
<!-- Render 1st level active item as section -->
92+
{% if level == 1 and nav_item.active %}
93+
{% set class = class ~ " md-nav__item--section" %}
94+
{% set is_section = true %}
95+
{% endif %}
96+
97+
<!-- Navigation tabs + sections -->
98+
{% if "navigation.sections" in features %}
99+
100+
<!-- Render 2nd level items with nested items as sections -->
101+
{% if level == 2 and nav_item.parent.active %}
102+
{% set class = class ~ " md-nav__item--section" %}
103+
{% set is_section = true %}
104+
{% endif %}
105+
{% endif %}
106+
107+
<!-- Navigation sections -->
108+
{% elif "navigation.sections" in features %}
109+
110+
<!-- Render 1st level items with nested items as sections -->
111+
{% if level == 1 %}
112+
{% set class = class ~ " md-nav__item--section" %}
113+
{% set is_section = true %}
114+
{% endif %}
115+
{% endif %}
116+
117+
<!-- Navigation pruning -->
118+
{% if "navigation.prune" in features %}
119+
120+
<!-- Prune item if it is not a section and not active -->
121+
{% if not is_section and not nav_item.active %}
122+
{% set class = class ~ " md-nav__item--pruned" %}
123+
{% set is_pruned = true %}
124+
{% endif %}
125+
{% endif %}
126+
127+
<!-- Nested navigation item -->
128+
<li class="{{ class }} md-nav__item--nested">
129+
{% if not is_pruned %}
130+
{% set checked = "checked" if nav_item.active %}
131+
132+
<!-- Determine checked and indeterminate state -->
133+
{% if "navigation.expand" in features and not checked %}
134+
{% set indeterminate = "md-toggle--indeterminate" %}
135+
{% endif %}
136+
137+
<!-- Active checkbox expands items contained within nested section -->
138+
<input
139+
class="md-nav__toggle md-toggle {{ indeterminate }}"
140+
type="checkbox"
141+
id="{{ path }}"
142+
{{ checked }}
143+
/>
144+
145+
<!-- Toggle to expand nested items -->
146+
{% if not indexes %}
147+
{% set tabindex = "0" if not is_section %}
148+
<label
149+
class="md-nav__link"
150+
for="{{ path }}"
151+
id="{{ path }}_label"
152+
tabindex="{{ tabindex }}"
153+
>
154+
{{ render_content(nav_item) }}
155+
<span class="md-nav__icon md-icon"></span>
156+
</label>
157+
158+
<!-- Toggle to expand nested items with link to index page -->
159+
{% else %}
160+
{% set index = indexes | first %}
161+
{% set class = "md-nav__link--active" if index == page %}
162+
<div class="md-nav__link md-nav__container">
163+
<a
164+
href="{{ index.url | url }}"
165+
class="md-nav__link {{ class }}"
166+
>
167+
{{ render_content(index, nav_item) }}
168+
</a>
169+
170+
<!-- Only render toggle if there's at least one more page -->
171+
{% if nav_item.children | length > 1 %}
172+
{% set tabindex = "0" if not is_section %}
173+
<label
174+
class="md-nav__link {{ class }}"
175+
for="{{ path }}"
176+
id="{{ path }}_label"
177+
tabindex="{{ tabindex }}"
178+
>
179+
<span class="md-nav__icon md-icon"></span>
180+
</label>
181+
{% endif %}
182+
</div>
183+
{% endif %}
184+
185+
<!-- Nested navigation -->
186+
<nav
187+
class="md-nav"
188+
data-md-level="{{ level }}"
189+
aria-labelledby="{{ path }}_label"
190+
aria-expanded="{{ nav_item.active | tojson }}"
191+
>
192+
<label class="md-nav__title" for="{{ path }}">
193+
<span class="md-nav__icon md-icon"></span>
194+
{{ nav_item.title }}
195+
</label>
196+
<ul class="md-nav__list" data-md-scrollfix>
197+
198+
<!-- Nested navigation item -->
199+
{% for nav_item in nav_item.children %}
200+
{% if not indexes or nav_item != indexes | first %}
201+
{{ render(nav_item, path ~ "_" ~ loop.index, level + 1) }}
202+
{% endif %}
203+
{% endfor %}
204+
</ul>
205+
</nav>
206+
207+
<!-- Pruned navigation item -->
208+
{% else %}
209+
{{ render_pruned(nav_item) }}
210+
{% endif %}
211+
</li>
212+
213+
<!-- Currently active page -->
214+
{% elif nav_item == page %}
215+
<li class="{{ class }}">
216+
{% set toc = page.toc %}
217+
218+
<!-- State toggle -->
219+
<input
220+
class="md-nav__toggle md-toggle"
221+
type="checkbox"
222+
id="__toc"
223+
/>
224+
225+
<!-- Hack: see partials/toc.html for more information -->
226+
{% set first = toc | first %}
227+
{% if first and first.level == 1 %}
228+
{% set toc = first.children %}
229+
{% endif %}
230+
231+
<!-- Navigation link to table of contents -->
232+
{% if toc %}
233+
<label class="md-nav__link md-nav__link--active" for="__toc">
234+
{{ render_content(nav_item) }}
235+
<span class="md-nav__icon md-icon"></span>
236+
</label>
237+
{% endif %}
238+
<a
239+
href="{{ nav_item.url | url }}"
240+
class="md-nav__link md-nav__link--active"
241+
>
242+
{{ render_content(nav_item) }}
243+
</a>
244+
245+
<!-- Table of contents -->
246+
{% if toc %}
247+
{% include "partials/toc.html" %}
248+
{% endif %}
249+
</li>
250+
251+
<!-- Navigation item -->
252+
{% else %}
253+
<li class="{{ class }}">
254+
<a href="{{ nav_item.url | url }}" class="md-nav__link">
255+
{{ render_content(nav_item) }}
256+
</a>
257+
</li>
258+
{% endif %}
259+
{% endmacro %}

‎overrides/partials/nav.html‎

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,33 @@
1-
{% set site_url = config.site_url | default(nav.homepage.url, true) | url %}
2-
{% if not config.use_directory_urls and site_url[0] == site_url[-1] == "." %}
3-
{% set site_url = site_url ~ "/index.html" %}
1+
{% import "partials/nav-item.html" as item with context %}
2+
3+
<!-- Determine classes -->
4+
{% set class = "md-nav md-nav--primary" %}
5+
{% if "navigation.tabs" in features %}
6+
{% set class = class ~ " md-nav--lifted" %}
47
{% endif %}
5-
<nav class="md-nav md-nav--primary" aria-label="{{ lang.t('nav.title') }}" data-md-level="0">
8+
{% if "toc.integrate" in features %}
9+
{% set class = class ~ " md-nav--integrated" %}
10+
{% endif %}
11+
12+
<!-- Navigation -->
13+
<nav
14+
class="{{ class }}"
15+
aria-label="{{ lang.t('nav') }}"
16+
data-md-level="0"
17+
>
18+
19+
<!-- Repository information -->
620
{% if config.repo_url %}
721
<div class="md-nav__source">
822
{% include "partials/source.html" %}
923
</div>
1024
{% endif %}
25+
26+
<!-- Navigation list -->
1127
<ul class="md-nav__list" data-md-scrollfix>
1228
{% for nav_item in nav %}
13-
{% set path = "nav-" + loop.index | string %}
14-
{% set level = 1 %}
15-
{% include "partials/nav-item.html" %}
29+
{% set path = "__nav_" ~ loop.index %}
30+
{{ item.render(nav_item, path, 1) }}
1631
{% endfor %}
1732
</ul>
18-
</nav>
33+
</nav>

‎requirements.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
mkdocs==1.2.3
2-
mkdocs-material==6.2.8
3-
jinja2<3.1.0
1+
mkdocs==1.5.3
2+
mkdocs-material==9.5.12
3+
jinja2>=3.0.2

0 commit comments

Comments
 (0)