[PATCH v2 1/3] Documentation: align Jekyll page style to rest of website

[Valentin Gagarin <valentin@gagarin.work>]

- Render a sitemap and link it on every page

- Show the sitemap for the documentation subtree at the documentation
  entry point

  This replaces the sidebar.

- Show breadcrumb navigation at the top of every documentation page

- Use the global stylesheet for all documentatio pages

  Recreate a minimal style for admonitions and code blocks.

Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
---
 Documentation/_includes/footer_custom.html    |  4 ++
 Documentation/_includes/sitemap.html          | 55 ++++++++++++++++++
 Documentation/_layouts/page.html              | 31 ++++++++++
 ...architecture-decision-record-template.adoc |  2 +-
 Documentation/doc/index.adoc                  |  7 +++
 Documentation/sitemap.adoc                    |  8 +++
 Documentation/style.css                       | 58 +++++++++++++++++++
 7 files changed, 164 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/_includes/sitemap.html
 create mode 100644 Documentation/_layouts/page.html
 create mode 100644 Documentation/sitemap.adoc

diff --git a/Documentation/_includes/footer_custom.html b/Documentation/_includes/footer_custom.html
index a8f2edb..2477920 100644
--- a/Documentation/_includes/footer_custom.html
+++ b/Documentation/_includes/footer_custom.html
@@ -14,3 +14,7 @@ Commons Attribution-ShareAlike 4.0 International License</a>, or the
 Documentation License, Version 1.3</a> or any later version published
 by the Free Software Foundation; with no Invariant Sections, no
 Front-Cover Texts, and no Back-Cover Texts.</small>
+
+<p>
+<a href="/sitemap.html"><small>Sitemap</small></a>
+<a href="/impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/_includes/sitemap.html b/Documentation/_includes/sitemap.html
new file mode 100644
index 0000000..cd493f8
--- /dev/null
+++ b/Documentation/_includes/sitemap.html
@@ -0,0 +1,55 @@
+{% comment %}
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
+
+Render a nested sitemap rooted at a given URL prefix.  Hierarchy is
+derived from URL structure: a page is a direct child of prefix P iff
+its URL starts with P, is not P itself, and contains no further path
+segments below P.
+{% endcomment %}
+
+{%- assign default_root = "/" -%}
+{% comment %}
+`prefix` is the URL of the section to list children of.  It must end with "/",
+which we assume if it is constructed by a directory and contains an index file.
+{% endcomment %}
+{%- assign prefix = include.prefix | default: default_root -%}
+{%- capture inner -%}
+  {%- assign candidates = site.html_pages
+        | where_exp: "p", "p.url contains prefix"
+        | where_exp: "p", "p.url != prefix" -%}
+  {%- comment %}
+  Ordered pages first, ascending.  The rest after, in URL order, so output is deterministic.
+  {%- endcomment %}
+  {%- assign ordered = candidates | where_exp: "p", "p.nav_order" | sort: "nav_order" -%}
+  {%- assign unordered = candidates | where_exp: "p", "p.nav_order == nil" | sort: "url" -%}
+  {%- assign sorted = ordered | concat: unordered -%}
+  {%- for p in sorted -%}
+    {%- comment %}
+    `assign` is page-global.  A recursive include below may have overwritten `prefix`.
+    {%- endcomment %}
+    {%- assign prefix = include.prefix | default: default_root -%}
+    {%- assign suffix = p.url | remove_first: prefix -%}
+    {%- assign without_slashes = suffix | replace: "/", "" -%}
+    {%- assign slashes = suffix.size | minus: without_slashes.size -%}
+    {%- assign is_index = false -%}
+    {%- if p.name == "index.adoc" -%}{%- assign is_index = true -%}{%- endif -%}
+    {%- assign is_page = false -%}
+    {%- if is_index == false and slashes == 0 -%}{%- assign is_page = true -%}{%- endif -%}
+    {%- assign is_section = false -%}
+    {%- if is_index and slashes == 1 -%}{%- assign is_section = true -%}{%- endif -%}
+    {%- if is_page or is_section %}
+    <li>
+      <a href="{{ p.url | relative_url }}">{{ p.title }}</a>{% if p.description %} — {{ p.description }}{% endif %}
+      {%- if is_section -%}
+        {%- include sitemap.html prefix=p.url -%}
+      {%- endif -%}
+    </li>
+    {%- endif -%}
+  {%- endfor -%}
+{%- endcapture -%}
+{%- assign trimmed = inner | strip -%}
+{%- if trimmed != "" %}
+<ul>{{ inner }}
+</ul>
+{%- endif -%}
diff --git a/Documentation/_layouts/page.html b/Documentation/_layouts/page.html
new file mode 100644
index 0000000..230b601
--- /dev/null
+++ b/Documentation/_layouts/page.html
@@ -0,0 +1,31 @@
+{% comment %}
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
+{% endcomment %}
+<!doctype html>
+<html lang="en">
+
+<head>
+
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+
+{% include favicon.html %}
+<link rel="stylesheet" href="/style.css">
+
+<title>{{ page.title }}</title>
+
+<body>
+
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Spectrum</a></li>
+    <li><a href="/doc/">Documentation</a></li>
+    <li aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+
+{{ content }}
+
+{% include footer_custom.html %}
+</html>
diff --git a/Documentation/doc/decisions/000-lightweight-architecture-decision-record-template.adoc b/Documentation/doc/decisions/000-lightweight-architecture-decision-record-template.adoc
index 2535cb3..dcec7c6 100644
--- a/Documentation/doc/decisions/000-lightweight-architecture-decision-record-template.adoc
+++ b/Documentation/doc/decisions/000-lightweight-architecture-decision-record-template.adoc
@@ -1,4 +1,4 @@
-# Title
+= 000 Template
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/index.adoc b/Documentation/doc/index.adoc
index cc25fd3..3bf3934 100644
--- a/Documentation/doc/index.adoc
+++ b/Documentation/doc/index.adoc
@@ -1,5 +1,6 @@
 = Spectrum Documentation
 :page-nav_exclude: true
+:page-liquid:
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
@@ -30,3 +31,9 @@ Once you are up and running, see
 
 If you are thinking of contributing to the Spectrum code or docs, see
  xref:contributing/index.adoc[Contributing].
+
+== Documentation index
+
+++++
+{% include sitemap.html prefix="/doc/" %}
+++++
diff --git a/Documentation/sitemap.adoc b/Documentation/sitemap.adoc
new file mode 100644
index 0000000..65198a4
--- /dev/null
+++ b/Documentation/sitemap.adoc
@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
+= Sitemap
+:page-liquid:
+
+++++
+{% include sitemap.html %}
+++++
diff --git a/Documentation/style.css b/Documentation/style.css
index f4d4c4e..44060b3 100644
--- a/Documentation/style.css
+++ b/Documentation/style.css
@@ -25,3 +25,61 @@ var {
 :target {
     background: yellow;
 }
+
+nav[aria-label="Breadcrumb"] ol {
+	list-style: none;
+	padding: 0;
+	display: flex;
+	flex-wrap: wrap;
+}
+
+nav[aria-label="Breadcrumb"] li + li::before {
+	content: "/";
+	padding: 0 0.5em;
+}
+
+:root {
+	--bg: Canvas;
+	--code-bg: whitesmoke;
+}
+
+code {
+	background: var(--code-bg);
+	padding: 0.1em 0.3em;
+}
+
+pre {
+	background: var(--code-bg);
+	padding: 1rem;
+	line-height: 1.5;
+	overflow-x: auto;
+}
+
+pre code {
+	background: none;
+	padding: 0;
+	border-radius: 0;
+}
+
+.admonitionblock {
+	border-left: 0.5rem solid var(--callout-accent, --bg);
+	background: var(--callout-bg, --code-bg);
+	margin: 1rem 0;
+}
+
+.admonitionblock td {
+	padding: 1rem;
+	vertical-align: top;
+}
+
+.admonitionblock td.icon {
+	white-space: nowrap;
+	color: var(--callout-accent);
+	font-weight: bold;
+}
+
+.admonitionblock.note      { --callout-accent: steelblue; --callout-bg: aliceblue; }
+.admonitionblock.tip       { --callout-accent: seagreen; --callout-bg: honeydew; }
+.admonitionblock.important { --callout-accent: indigo; --callout-bg: ghostwhite; }
+.admonitionblock.warning   { --callout-accent: orangered; --callout-bg: seashell; }
+.admonitionblock.caution   { --callout-accent: red; --callout-bg: mistyrose; }
-- 
2.51.2