Skip to content

Commit

Permalink
chore: (mkdocs) upgrade mkdocs and material to latest versions (#158)
Browse files Browse the repository at this point in the history 
* Update mkdocs and material

* override

* Update material
  • Loading branch information
@chris-bateman
chris-bateman authored Aug 13, 2024
1 parent 4239ecf commit a7dd901
Show file tree
Hide file tree
Showing 5 changed files with 298 additions and 22 deletions.
2 changes: 2 additions & 0 deletions mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ theme:
logo: img/sos.png
favicon: img/favicon.ico
custom_dir: overrides
features:
- navigation.sections
extra_css:
- stylesheets/custom.css
nav:
Expand Down
22 changes: 11 additions & 11 deletions overrides/partials/header.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,30 +13,30 @@
{% set site_url = site_url ~ "/index.html" %}
{% endif %}
<header class="md-header" data-md-component="header">
<nav class="md-header-nav md-grid" aria-label="{{ lang.t('header.title') }}">
<a href="{{ site_url }}" title="{{ config.site_name | e }}" class="md-header-nav__button md-logo" aria-label="{{ config.site_name }}">
<nav class="md-header__inner md-grid" aria-label="{{ lang.t('header.title') }}">
<a href="{{ site_url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}">
{% include "partials/logo.html" %}
</a>
<!-- Button to open drawer -->
<label class="md-header-nav__button md-icon" for="__drawer">
<label class="md-header__button md-icon" for="__drawer">
{% include ".icons/material/menu" ~ ".svg" %}
</label>
<div class="md-header-nav__title" data-md-component="header-title">
<div class="md-header__title" data-md-component="header-title">
{% if config.site_name == page.title %}
<div class="md-header-nav__ellipsis md-ellipsis">
<div class="md-header__ellipsis md-ellipsis">
<a href="{{ site_url }}" title="{{ config.site_name | e }}">

{{ config.site_name }}
</a>
</div>
{% else %}
<div class="md-header-nav__ellipsis">
<span class="md-header-nav__topic md-ellipsis">
<div class="md-header__ellipsis">
<span class="md-header__topic md-ellipsis">
<a href="{{ site_url }}" title="{{ config.site_name | e }}" >
{{ config.site_name }}
</a>
</span>
<span class="md-header-nav__topic md-ellipsis">
<span class="md-header__topic md-ellipsis">
{% if page and page.meta and page.meta.title %}
{{ page.meta.title }}
{% else %}
Expand All @@ -46,14 +46,14 @@
</div>
{% endif %}
</div>
{% if "search" in config["plugins"] %}
<label class="md-header-nav__button md-icon" for="__search">
{% if "material/search" in config["plugins"] %}
<label class="md-header__button md-icon" for="__search">
{% include ".icons/material/magnify.svg" %}
</label>
{% include "partials/search.html" %}
{% endif %}
{% if config.repo_url %}
<div class="md-header-nav__source">
<div class="md-header__source">
{% include "partials/source.html" %}
</div>
{% endif %}
Expand Down
259 changes: 259 additions & 0 deletions overrides/partials/nav-item.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,259 @@
<!-- Render navigation link status -->
{% macro render_status(nav_item, type) %}
{% set class = "md-status md-status--" ~ type %}

<!-- Render icon with title (or tooltip), if given -->
{% if config.extra.status and config.extra.status[type] %}
<span
class="{{ class }}"
title="{{ config.extra.status[type] }}"
>
</span>

<!-- Render icon only -->
{% else %}
<span class="{{ class }}"></span>
{% endif %}
{% endmacro %}

<!-- Render navigation link content -->
{% macro render_content(nav_item, ref = nav_item) %}

<!-- Navigation link icon -->
{% if nav_item.is_page and nav_item.meta.icon %}
{% include ".icons/" ~ nav_item.meta.icon ~ ".svg" %}
{% endif %}

<!-- Navigation link title -->
<span class="md-ellipsis">
{{ ref.title }}
</span>

<!-- Navigation link status -->
{% if nav_item.is_page and nav_item.meta.status %}
{{ render_status(nav_item, nav_item.meta.status) }}
{% endif %}
{% endmacro %}

<!-- Render navigation item (pruned) -->
{% macro render_pruned(nav_item, ref = nav_item) %}
{% set first = nav_item.children | first %}

<!-- Recurse, if the first item has further nested items -->
{% if first and first.children %}
{{ render_pruned(first, ref) }}

<!-- Navigation link -->
{% else %}
<a href="{{ first.url | url }}" class="md-nav__link">
{{ render_content(ref) }}

<!-- Only render toggle if there's at least one nested item -->
{% if nav_item.children | length > 0 %}
<span class="md-nav__icon md-icon"></span>
{% endif %}
</a>
{% endif %}
{% endmacro %}

<!-- Render navigation item -->
{% macro render(nav_item, path, level) %}

<!-- Determine classes -->
{% set class = "md-nav__item" %}
{% if nav_item.active %}
{% set class = class ~ " md-nav__item--active" %}
{% endif %}

<!-- Determine active page for paginated views -->
{% if nav_item.pages %}
{% if page in nav_item.pages %}
{% set nav_item = page %}
{% endif %}
{% endif %}

<!-- Navigation item with nested items -->
{% if nav_item.children %}

<!-- Determine all nested items that are index pages -->
{% set indexes = [] %}
{% if "navigation.indexes" in features %}
{% for nav_item in nav_item.children %}
{% if nav_item.is_index and not index is defined %}
{% set _ = indexes.append(nav_item) %}
{% endif %}
{% endfor %}
{% endif %}

<!-- Navigation tabs -->
{% if "navigation.tabs" in features %}

<!-- Render 1st level active item as section -->
{% if level == 1 and nav_item.active %}
{% set class = class ~ " md-nav__item--section" %}
{% set is_section = true %}
{% endif %}

<!-- Navigation tabs + sections -->
{% if "navigation.sections" in features %}

<!-- Render 2nd level items with nested items as sections -->
{% if level == 2 and nav_item.parent.active %}
{% set class = class ~ " md-nav__item--section" %}
{% set is_section = true %}
{% endif %}
{% endif %}

<!-- Navigation sections -->
{% elif "navigation.sections" in features %}

<!-- Render 1st level items with nested items as sections -->
{% if level == 1 %}
{% set class = class ~ " md-nav__item--section" %}
{% set is_section = true %}
{% endif %}
{% endif %}

<!-- Navigation pruning -->
{% if "navigation.prune" in features %}

<!-- Prune item if it is not a section and not active -->
{% if not is_section and not nav_item.active %}
{% set class = class ~ " md-nav__item--pruned" %}
{% set is_pruned = true %}
{% endif %}
{% endif %}

<!-- Nested navigation item -->
<li class="{{ class }} md-nav__item--nested">
{% if not is_pruned %}
{% set checked = "checked" if nav_item.active %}

<!-- Determine checked and indeterminate state -->
{% if "navigation.expand" in features and not checked %}
{% set indeterminate = "md-toggle--indeterminate" %}
{% endif %}

<!-- Active checkbox expands items contained within nested section -->
<input
class="md-nav__toggle md-toggle {{ indeterminate }}"
type="checkbox"
id="{{ path }}"
{{ checked }}
/>

<!-- Toggle to expand nested items -->
{% if not indexes %}
{% set tabindex = "0" if not is_section %}
<label
class="md-nav__link"
for="{{ path }}"
id="{{ path }}_label"
tabindex="{{ tabindex }}"
>
{{ render_content(nav_item) }}
<span class="md-nav__icon md-icon"></span>
</label>

<!-- Toggle to expand nested items with link to index page -->
{% else %}
{% set index = indexes | first %}
{% set class = "md-nav__link--active" if index == page %}
<div class="md-nav__link md-nav__container">
<a
href="{{ index.url | url }}"
class="md-nav__link {{ class }}"
>
{{ render_content(index, nav_item) }}
</a>

<!-- Only render toggle if there's at least one more page -->
{% if nav_item.children | length > 1 %}
{% set tabindex = "0" if not is_section %}
<label
class="md-nav__link {{ class }}"
for="{{ path }}"
id="{{ path }}_label"
tabindex="{{ tabindex }}"
>
<span class="md-nav__icon md-icon"></span>
</label>
{% endif %}
</div>
{% endif %}

<!-- Nested navigation -->
<nav
class="md-nav"
data-md-level="{{ level }}"
aria-labelledby="{{ path }}_label"
aria-expanded="{{ nav_item.active | tojson }}"
>
<label class="md-nav__title" for="{{ path }}">
<span class="md-nav__icon md-icon"></span>
{{ nav_item.title }}
</label>
<ul class="md-nav__list" data-md-scrollfix>

<!-- Nested navigation item -->
{% for nav_item in nav_item.children %}
{% if not indexes or nav_item != indexes | first %}
{{ render(nav_item, path ~ "_" ~ loop.index, level + 1) }}
{% endif %}
{% endfor %}
</ul>
</nav>

<!-- Pruned navigation item -->
{% else %}
{{ render_pruned(nav_item) }}
{% endif %}
</li>

<!-- Currently active page -->
{% elif nav_item == page %}
<li class="{{ class }}">
{% set toc = page.toc %}

<!-- State toggle -->
<input
class="md-nav__toggle md-toggle"
type="checkbox"
id="__toc"
/>

<!-- Hack: see partials/toc.html for more information -->
{% set first = toc | first %}
{% if first and first.level == 1 %}
{% set toc = first.children %}
{% endif %}

<!-- Navigation link to table of contents -->
{% if toc %}
<label class="md-nav__link md-nav__link--active" for="__toc">
{{ render_content(nav_item) }}
<span class="md-nav__icon md-icon"></span>
</label>
{% endif %}
<a
href="{{ nav_item.url | url }}"
class="md-nav__link md-nav__link--active"
>
{{ render_content(nav_item) }}
</a>

<!-- Table of contents -->
{% if toc %}
{% include "partials/toc.html" %}
{% endif %}
</li>

<!-- Navigation item -->
{% else %}
<li class="{{ class }}">
<a href="{{ nav_item.url | url }}" class="md-nav__link">
{{ render_content(nav_item) }}
</a>
</li>
{% endif %}
{% endmacro %}
31 changes: 23 additions & 8 deletions overrides/partials/nav.html
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,33 @@
{% set site_url = config.site_url | default(nav.homepage.url, true) | url %}
{% if not config.use_directory_urls and site_url[0] == site_url[-1] == "." %}
{% set site_url = site_url ~ "/index.html" %}
{% import "partials/nav-item.html" as item with context %}

<!-- Determine classes -->
{% set class = "md-nav md-nav--primary" %}
{% if "navigation.tabs" in features %}
{% set class = class ~ " md-nav--lifted" %}
{% endif %}
<nav class="md-nav md-nav--primary" aria-label="{{ lang.t('nav.title') }}" data-md-level="0">
{% if "toc.integrate" in features %}
{% set class = class ~ " md-nav--integrated" %}
{% endif %}

<!-- Navigation -->
<nav
class="{{ class }}"
aria-label="{{ lang.t('nav') }}"
data-md-level="0"
>

<!-- Repository information -->
{% if config.repo_url %}
<div class="md-nav__source">
{% include "partials/source.html" %}
</div>
{% endif %}

<!-- Navigation list -->
<ul class="md-nav__list" data-md-scrollfix>
{% for nav_item in nav %}
{% set path = "nav-" + loop.index | string %}
{% set level = 1 %}
{% include "partials/nav-item.html" %}
{% set path = "__nav_" ~ loop.index %}
{{ item.render(nav_item, path, 1) }}
{% endfor %}
</ul>
</nav>
</nav>
6 changes: 3 additions & 3 deletions requirements.txt
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
mkdocs==1.2.3
mkdocs-material==6.2.8
jinja2<3.1.0
mkdocs==1.5.3
mkdocs-material==9.5.12
jinja2>=3.0.2

0 comments on commit a7dd901

Please sign in to comment.