From a7dd9018c5a52a7685993803e4b3d45b18abbb13 Mon Sep 17 00:00:00 2001
From: Chris Bateman <chris-bateman@users.noreply.github.com>
Date: Tue, 13 Aug 2024 12:23:02 +1000
Subject: [PATCH] chore: (mkdocs) upgrade mkdocs and material to latest
 versions (#158)

* Update mkdocs and material

* override

* Update material
---
 mkdocs.yml                       |   2 +
 overrides/partials/header.html   |  22 +--
 overrides/partials/nav-item.html | 259 +++++++++++++++++++++++++++++++
 overrides/partials/nav.html      |  31 +++-
 requirements.txt                 |   6 +-
 5 files changed, 298 insertions(+), 22 deletions(-)
 create mode 100644 overrides/partials/nav-item.html

diff --git a/mkdocs.yml b/mkdocs.yml
index ee8649bd..8ab0f36d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -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:
diff --git a/overrides/partials/header.html b/overrides/partials/header.html
index 236c82fd..cf4a4466 100644
--- a/overrides/partials/header.html
+++ b/overrides/partials/header.html
@@ -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 %}
@@ -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 %}
diff --git a/overrides/partials/nav-item.html b/overrides/partials/nav-item.html
new file mode 100644
index 00000000..bc098872
--- /dev/null
+++ b/overrides/partials/nav-item.html
@@ -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 %}
\ No newline at end of file
diff --git a/overrides/partials/nav.html b/overrides/partials/nav.html
index 564981be..42e25fb6 100644
--- a/overrides/partials/nav.html
+++ b/overrides/partials/nav.html
@@ -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>
\ No newline at end of file
diff --git a/requirements.txt b/requirements.txt
index 8eff9877..c98c07d2 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -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