nav: add breadcrumb trail

docs/assets/extra.css

@@ -26,6 +26,17 @@
     text-decoration: underline;
 }
 
+/* .md-tags' own margin/padding are tuned for sitting below the page title,
+   which is where upstream renders it by default. This site renders tags
+   first (see overrides/partials/content.html), directly under the
+   breadcrumb path, so that spacing left a gap far bigger than the one
+   between the path and a title. Zero it out so the gap matches the
+   baseline space `.md-content__inner` already puts above its first child. */
+.md-content__inner > .md-tags:first-child {
+    margin-top: 0;
+    padding-top: 0;
+}
+
 /* Comment out this section if the header should not be light colored */
 
 [data-md-color-scheme="eccenca-light"] .md-header,

mkdocs.yml

@@ -130,6 +130,8 @@ theme:
     # documents can be directly attached to sections, which is particularly
     # useful for providing overview pages.
     - navigation.indexes
+    # renders a breadcrumb trail above the content
+    - navigation.path
     # clicks on all internal links will be intercepted and dispatched via XHR
     # without fully reloading the page
     - navigation.instant

overrides/partials/path.html

@@ -0,0 +1,24 @@
+{#-
+  Override of Zensical's partials/path.html.
+
+  Drops the leading "Welcome to the eccenca Corporate Memory documentation"
+  homepage crumb that Zensical's (and Material for MkDocs') stock template
+  always prepends via `nav.homepage`. Everything else is copied verbatim from
+  Zensical's own version, with the homepage branch removed and the
+  `depth > 1` guard lowered to `depth > 0` to match: without the homepage
+  crumb padding the count, one real ancestor is enough to show the trail.
+-#}
+{% import "partials/path-item.html" as item with context %}
+{% if page.meta and page.meta.hide %}
+  {% set hidden = "hidden" if "path" in page.meta.hide %}
+{% endif %}
+{% set depth = page.ancestors | length %}
+{% if depth > 0 %}
+  <nav class="md-path" aria-label="{{ lang.t('nav') }}" {{ hidden }}>
+    <ol class="md-path__list">
+      {% for nav_item in page.ancestors | reverse %}
+        {{ item.render(nav_item) }}
+      {% endfor %}
+    </ol>
+  </nav>
+{% endif %}