[PATCH 0/3] Documentation: render all pages in one style

patches and low-level development discussion
 help / color / mirror / code / Atom feed

* [PATCH 0/3] Documentation: render all pages in one style
@ 2026-06-08 16:49 Valentin Gagarin
  2026-06-08 16:49 ` [PATCH 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
                   ` (7 more replies)
  0 siblings, 8 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-08 16:49 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

This is a textually large but mostly mechanical change:
- Use the same stylesheet for all pages rendered with Jekyll
- Render a sitemap
- Render breadcrumbs on each page
- Drop Just the Docs
- Provide a minimal admonition style

I adapted some of the page titles to read better within the sitemap and
the breadcrumbs, by removing the "Spectrum " prefix.

Valentin Gagarin (3):
  Documentation: align Jekyll page style to rest of website
  Documentation: drop Just the Docs
  Documentation: uniform navigation across all pages

 Documentation/Gemfile                         |  1 -
 Documentation/Gemfile.lock                    | 12 +---
 Documentation/_config.yml                     |  7 ---
 Documentation/_includes/breadcrumb.html       | 23 ++++++++
 Documentation/_includes/footer_custom.html    |  8 ++-
 Documentation/_includes/sitemap.html          | 55 ++++++++++++++++++
 Documentation/_includes/title.html            | 13 -----
 Documentation/_layouts/page.html              | 28 +++++++++
 Documentation/_plugins/site_title_link.rb     | 10 ----
 Documentation/_sass/custom/custom.scss        | 43 --------------
 Documentation/bibliography.html               | 38 ++----------
 Documentation/contributing.html               | 38 ++----------
 Documentation/design.html                     | 38 ++----------
 Documentation/doc/about/architecture.adoc     |  1 -
 Documentation/doc/about/index.adoc            |  1 -
 Documentation/doc/about/requirements.adoc     |  1 -
 Documentation/doc/contributing/b4.adoc        |  2 -
 .../contributing/building-documentation.adoc  |  1 -
 .../doc/contributing/communication.adoc       |  1 -
 .../doc/contributing/first-patch.adoc         |  2 -
 Documentation/doc/contributing/index.adoc     |  1 -
 Documentation/doc/contributing/replying.adoc  |  2 -
 .../doc/contributing/reviewing-patches.adoc   |  2 -
 .../doc/contributing/testing-patches.adoc     |  2 -
 .../contributing/working-with-patches.adoc    |  2 -
 .../contributing/writing_documentation.adoc   |  3 +-
 ...architecture-decision-record-template.adoc |  2 +-
 .../decisions/001-host-update-mechanism.adoc  |  2 -
 .../doc/decisions/002-install-options.adoc    |  2 -
 .../doc/decisions/003-partitioning.adoc       |  2 -
 .../004-data-at-rest-encryption.adoc          |  2 -
 .../005-virtual-machine-monitor.adoc          |  2 -
 .../doc/decisions/006-drivers-on-host.adoc    |  2 -
 .../decisions/007-usb-virtual-machines.adoc   |  2 -
 ...008-inter-vm-communication-mechanisms.adoc |  2 -
 Documentation/doc/decisions/index.adoc        |  2 -
 .../doc/development/build-configuration.adoc  |  1 -
 .../doc/development/built-in-vms.adoc         |  1 -
 Documentation/doc/development/checks.adoc     |  1 -
 Documentation/doc/development/debugging.adoc  |  1 -
 Documentation/doc/development/index.adoc      |  1 -
 .../doc/development/persistent-storage.adoc   |  1 -
 Documentation/doc/development/release.adoc    |  1 -
 Documentation/doc/development/updates.adoc    |  1 -
 .../doc/development/uuid-reference.adoc       |  1 -
 Documentation/doc/index.adoc                  | 11 +++-
 .../doc/installation/binary-cache.adoc        |  1 -
 .../doc/installation/getting-spectrum.adoc    |  1 -
 Documentation/doc/installation/index.adoc     |  1 -
 .../using-spectrum/creating-custom-vms.adoc   |  1 -
 Documentation/doc/using-spectrum/index.adoc   |  1 -
 .../doc/using-spectrum/running-vms.adoc       |  1 -
 .../doc/using-spectrum/vm-file-access.adoc    |  1 -
 Documentation/gemset.nix                      | 33 -----------
 Documentation/impressum.html                  | 35 ++---------
 Documentation/index.html                      | 33 ++---------
 Documentation/logo/index.html                 | 38 ++----------
 Documentation/motivation.html                 | 38 ++----------
 Documentation/sitemap.adoc                    |  8 +++
 .../software/cloud-hypervisor/index.html      | 39 ++-----------
 Documentation/software/index.html             | 38 ++----------
 Documentation/style.css                       | 58 +++++++++++++++++++
 62 files changed, 234 insertions(+), 468 deletions(-)
 create mode 100644 Documentation/_includes/breadcrumb.html
 create mode 100644 Documentation/_includes/sitemap.html
 delete mode 100644 Documentation/_includes/title.html
 create mode 100644 Documentation/_layouts/page.html
 delete mode 100644 Documentation/_plugins/site_title_link.rb
 delete mode 100644 Documentation/_sass/custom/custom.scss
 create mode 100644 Documentation/sitemap.adoc

-- 
2.51.2


^ permalink raw reply	[flat|nested] 28+ messages in thread

* [PATCH 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-08 16:49 [PATCH 0/3] Documentation: render all pages in one style Valentin Gagarin
@ 2026-06-08 16:49 ` Valentin Gagarin
  2026-06-08 16:49 ` [PATCH 2/3] Documentation: drop Just the Docs Valentin Gagarin
                   ` (6 subsequent siblings)
  7 siblings, 0 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-08 16:49 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

- 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..7f51a0a 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


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH 2/3] Documentation: drop Just the Docs
  2026-06-08 16:49 [PATCH 0/3] Documentation: render all pages in one style Valentin Gagarin
  2026-06-08 16:49 ` [PATCH 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
@ 2026-06-08 16:49 ` Valentin Gagarin
  2026-06-08 16:49 ` [PATCH 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
                   ` (5 subsequent siblings)
  7 siblings, 0 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-08 16:49 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
---
 Documentation/Gemfile                         |  1 -
 Documentation/Gemfile.lock                    | 12 +-----
 Documentation/_config.yml                     |  7 ---
 Documentation/_includes/title.html            | 13 ------
 Documentation/_plugins/site_title_link.rb     | 10 -----
 Documentation/_sass/custom/custom.scss        | 43 -------------------
 Documentation/doc/about/architecture.adoc     |  1 -
 Documentation/doc/about/index.adoc            |  1 -
 Documentation/doc/about/requirements.adoc     |  1 -
 Documentation/doc/contributing/b4.adoc        |  2 -
 .../contributing/building-documentation.adoc  |  1 -
 .../doc/contributing/communication.adoc       |  1 -
 .../doc/contributing/first-patch.adoc         |  2 -
 Documentation/doc/contributing/index.adoc     |  1 -
 Documentation/doc/contributing/replying.adoc  |  2 -
 .../doc/contributing/reviewing-patches.adoc   |  2 -
 .../doc/contributing/testing-patches.adoc     |  2 -
 .../contributing/working-with-patches.adoc    |  2 -
 .../contributing/writing_documentation.adoc   |  3 +-
 .../decisions/001-host-update-mechanism.adoc  |  2 -
 .../doc/decisions/002-install-options.adoc    |  2 -
 .../doc/decisions/003-partitioning.adoc       |  2 -
 .../004-data-at-rest-encryption.adoc          |  2 -
 .../005-virtual-machine-monitor.adoc          |  2 -
 .../doc/decisions/006-drivers-on-host.adoc    |  2 -
 .../decisions/007-usb-virtual-machines.adoc   |  2 -
 ...008-inter-vm-communication-mechanisms.adoc |  2 -
 Documentation/doc/decisions/index.adoc        |  2 -
 .../doc/development/build-configuration.adoc  |  1 -
 .../doc/development/built-in-vms.adoc         |  1 -
 Documentation/doc/development/checks.adoc     |  1 -
 Documentation/doc/development/debugging.adoc  |  1 -
 Documentation/doc/development/index.adoc      |  1 -
 .../doc/development/persistent-storage.adoc   |  1 -
 Documentation/doc/development/release.adoc    |  1 -
 Documentation/doc/development/updates.adoc    |  1 -
 .../doc/development/uuid-reference.adoc       |  1 -
 Documentation/doc/index.adoc                  |  1 -
 .../doc/installation/binary-cache.adoc        |  1 -
 .../doc/installation/getting-spectrum.adoc    |  1 -
 Documentation/doc/installation/index.adoc     |  1 -
 .../using-spectrum/creating-custom-vms.adoc   |  1 -
 Documentation/doc/using-spectrum/index.adoc   |  1 -
 .../doc/using-spectrum/running-vms.adoc       |  1 -
 .../doc/using-spectrum/vm-file-access.adoc    |  1 -
 Documentation/gemset.nix                      | 33 --------------
 46 files changed, 2 insertions(+), 173 deletions(-)
 delete mode 100644 Documentation/_includes/title.html
 delete mode 100644 Documentation/_plugins/site_title_link.rb
 delete mode 100644 Documentation/_sass/custom/custom.scss

diff --git a/Documentation/Gemfile b/Documentation/Gemfile
index 3c3f59d..a6396da 100644
--- a/Documentation/Gemfile
+++ b/Documentation/Gemfile
@@ -6,4 +6,3 @@ source "https://rubygems.org"
 
 gem "jekyll"
 gem "jekyll-asciidoc"
-gem "just-the-docs", "~> 0.10.0"
diff --git a/Documentation/Gemfile.lock b/Documentation/Gemfile.lock
index e7b515e..992e6da 100644
--- a/Documentation/Gemfile.lock
+++ b/Documentation/Gemfile.lock
@@ -43,20 +43,11 @@ GEM
     jekyll-asciidoc (3.0.1)
       asciidoctor (>= 1.5.0, < 3.0.0)
       jekyll (>= 3.0.0)
-    jekyll-include-cache (0.2.1)
-      jekyll (>= 3.7, < 5.0)
     jekyll-sass-converter (3.1.0)
       sass-embedded (~> 1.75)
-    jekyll-seo-tag (2.8.0)
-      jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     json (2.13.0)
-    just-the-docs (0.10.1)
-      jekyll (>= 3.8.5)
-      jekyll-include-cache
-      jekyll-seo-tag (>= 2.0)
-      rake (>= 12.3.1)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
@@ -90,7 +81,6 @@ PLATFORMS
 DEPENDENCIES
   jekyll
   jekyll-asciidoc
-  just-the-docs (~> 0.10.0)
 
 BUNDLED WITH
-   2.6.9
+   2.7.2
diff --git a/Documentation/_config.yml b/Documentation/_config.yml
index b11c399..cc3e8ea 100644
--- a/Documentation/_config.yml
+++ b/Documentation/_config.yml
@@ -2,13 +2,6 @@
 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 ---
 title: Spectrum documentation
-logo: /logo/logo_html.svg
-theme: just-the-docs
-aux_links:
-  Home:
-    - /
-  Git:
-    - "https://spectrum-os.org/git/"
 plugins:
   - jekyll-asciidoc
 exclude:
diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html
deleted file mode 100644
index 90ef71b..0000000
--- a/Documentation/_includes/title.html
+++ /dev/null
@@ -1,13 +0,0 @@
-{% comment %}
-SPDX-License-Identifier: MIT
-SPDX-FileCopyrightText: 2016 Patrick Marsceill
-SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-Override of: https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_includes/title.html
-{% endcomment %}
-{% if site.logo %}
-  <div class="site-logo" role="img" aria-label="{{ site.title }}"></div>
-{% endif %}
-{% if site.title %}
-  {{ site.title }}
-{% endif %}
diff --git a/Documentation/_plugins/site_title_link.rb b/Documentation/_plugins/site_title_link.rb
deleted file mode 100644
index 4095701..0000000
--- a/Documentation/_plugins/site_title_link.rb
+++ /dev/null
@@ -1,10 +0,0 @@
-# SPDX-License-Identifier: EUPL-1.2+
-# SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-# Just the Docs hardcodes the site header link to `/`.
-# https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_includes/components/sidebar.html#L14
-# Make it point to the docs root, not the top-level site.
-Jekyll::Hooks.register [:pages, :documents], :post_render do |item|
-  item.output.sub!('<a href="/" class="site-title',
-                   '<a href="/doc/" class="site-title')
-end
diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss
deleted file mode 100644
index 48b1d41..0000000
--- a/Documentation/_sass/custom/custom.scss
+++ /dev/null
@@ -1,43 +0,0 @@
-// SPDX-License-Identifier: MIT
-// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
-// SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-.main-content {
-	// Just the Docs puts titles next to definitions, rather than on
-	// the line before.  This makes the definitions too horizontally
-	// compressed.
-	dl {
-		display: block;
-	}
-	dt {
-		text-align: left;
-		font-weight: bold;
-
-		&::after {
-			content: none;
-		}
-	}
-	dd {
-		margin-left: 2ch;
-	}
-}
-
-// Make the logo and title fit the site header.
-.site-header {
-  .site-logo {
-    width: 3rem;
-  }
-
-  // Just the Docs displays a sidebar at the "medium size" `md` breakpoint and above.
-  // Use the upstream `mq` media query mixin to target that breakpoint.
-  // https://just-the-docs.com/docs/utilities/responsive-modifiers/
-  // https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_sass/support/mixins/_layout.scss#L3-L8
-  @include mq(md) {
-    .site-logo {
-      width: 5.5rem;
-    }
-    .site-title {
-      font-size: 1.25rem !important;
-    }
-  }
-}
diff --git a/Documentation/doc/about/architecture.adoc b/Documentation/doc/about/architecture.adoc
index 2b86616..bbc927d 100644
--- a/Documentation/doc/about/architecture.adoc
+++ b/Documentation/doc/about/architecture.adoc
@@ -1,5 +1,4 @@
 = Architecture
-:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/about/index.adoc b/Documentation/doc/about/index.adoc
index 6961b6a..65f7f7c 100644
--- a/Documentation/doc/about/index.adoc
+++ b/Documentation/doc/about/index.adoc
@@ -1,7 +1,6 @@
 = About Spectrum
 :description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum.
 :page-nav_order: 1
-:page-has_children: true
 
 // 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/about/requirements.adoc b/Documentation/doc/about/requirements.adoc
index 40f802f..6c32c31 100644
--- a/Documentation/doc/about/requirements.adoc
+++ b/Documentation/doc/about/requirements.adoc
@@ -1,5 +1,4 @@
 = Hardware and firmware requirements
-:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/contributing/b4.adoc b/Documentation/doc/contributing/b4.adoc
index 81f2519..3734c3a 100644
--- a/Documentation/doc/contributing/b4.adoc
+++ b/Documentation/doc/contributing/b4.adoc
@@ -1,6 +1,4 @@
 = Installing and Configuring b4
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/building-documentation.adoc b/Documentation/doc/contributing/building-documentation.adoc
index 919a021..b691d4d 100644
--- a/Documentation/doc/contributing/building-documentation.adoc
+++ b/Documentation/doc/contributing/building-documentation.adoc
@@ -1,5 +1,4 @@
 = Building Documentation
-:page-parent: Contributing
 :page-nav_order: 4
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/contributing/communication.adoc b/Documentation/doc/contributing/communication.adoc
index 874ad4e..5099c9c 100644
--- a/Documentation/doc/contributing/communication.adoc
+++ b/Documentation/doc/contributing/communication.adoc
@@ -1,7 +1,6 @@
 = Communication in Spectrum
 :description: Channels, announcements and so on.
 :page-nav_order: 1
-:page-parent: Contributing
 
 // SPDX-FileCopyrightText: 2019-2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2023 Unikie
diff --git a/Documentation/doc/contributing/first-patch.adoc b/Documentation/doc/contributing/first-patch.adoc
index 38326c0..2625888 100644
--- a/Documentation/doc/contributing/first-patch.adoc
+++ b/Documentation/doc/contributing/first-patch.adoc
@@ -1,6 +1,4 @@
 = Sending Your Patch
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/contributing/index.adoc b/Documentation/doc/contributing/index.adoc
index 5ae6811..2607b35 100644
--- a/Documentation/doc/contributing/index.adoc
+++ b/Documentation/doc/contributing/index.adoc
@@ -1,7 +1,6 @@
 = Contributing
 :description: How to contribute changes to the Spectrum source repository.
 :page-nav_order: 5
-:page-has_children: true
 
 // SPDX-FileCopyrightText: 2023 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/contributing/replying.adoc b/Documentation/doc/contributing/replying.adoc
index c478afb..c6ec4b8 100644
--- a/Documentation/doc/contributing/replying.adoc
+++ b/Documentation/doc/contributing/replying.adoc
@@ -1,6 +1,4 @@
 = Replying to Messages in the Mailing List Archives
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/reviewing-patches.adoc b/Documentation/doc/contributing/reviewing-patches.adoc
index 0e73b0e..224e314 100644
--- a/Documentation/doc/contributing/reviewing-patches.adoc
+++ b/Documentation/doc/contributing/reviewing-patches.adoc
@@ -1,6 +1,4 @@
 = Reviewing Patches
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/testing-patches.adoc b/Documentation/doc/contributing/testing-patches.adoc
index d98b738..031855d 100644
--- a/Documentation/doc/contributing/testing-patches.adoc
+++ b/Documentation/doc/contributing/testing-patches.adoc
@@ -1,6 +1,4 @@
 = Testing Patches
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/working-with-patches.adoc b/Documentation/doc/contributing/working-with-patches.adoc
index 8e22343..6e1e83e 100644
--- a/Documentation/doc/contributing/working-with-patches.adoc
+++ b/Documentation/doc/contributing/working-with-patches.adoc
@@ -1,7 +1,5 @@
 = Working with Patches
-:page-parent: Contributing
 :page-nav_order: 2
-:page-has_children: true
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-FileCopyrightText: 2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/writing_documentation.adoc b/Documentation/doc/contributing/writing_documentation.adoc
index cb09241..33e4480 100644
--- a/Documentation/doc/contributing/writing_documentation.adoc
+++ b/Documentation/doc/contributing/writing_documentation.adoc
@@ -1,7 +1,6 @@
 = Documentation Style Guide
 :description: Channels, announcements and so on.
 :page-nav_order: 3
-:page-parent: Contributing
 
 // SPDX-FileCopyrightText: 2023 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -12,7 +11,7 @@ Please follow these guidelines and conventions
 when editing the documentation.
 
 We use https://nixos.org/manual/nix/stable/introduction.html[Nix] and
-https://github.com/just-the-docs/just-the-docs[Just the Docs] for
+https://jekyllrb.com/[Jekyll] for
 building the documentation. Sources are written in AsciiDoc If you are
 new with it, see
 https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation].
diff --git a/Documentation/doc/decisions/001-host-update-mechanism.adoc b/Documentation/doc/decisions/001-host-update-mechanism.adoc
index 39f9f28..d0ab341 100644
--- a/Documentation/doc/decisions/001-host-update-mechanism.adoc
+++ b/Documentation/doc/decisions/001-host-update-mechanism.adoc
@@ -1,6 +1,4 @@
 = 001 Host Update Mechanism
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/002-install-options.adoc b/Documentation/doc/decisions/002-install-options.adoc
index 4a745eb..f56a626 100644
--- a/Documentation/doc/decisions/002-install-options.adoc
+++ b/Documentation/doc/decisions/002-install-options.adoc
@@ -1,6 +1,4 @@
 = 002 Install Options
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/003-partitioning.adoc b/Documentation/doc/decisions/003-partitioning.adoc
index 8e538c3..39f0ee2 100644
--- a/Documentation/doc/decisions/003-partitioning.adoc
+++ b/Documentation/doc/decisions/003-partitioning.adoc
@@ -1,6 +1,4 @@
 = 003 Partitioning
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/004-data-at-rest-encryption.adoc b/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
index 5b0f518..8f4d430 100644
--- a/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
+++ b/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
@@ -1,6 +1,4 @@
 = 004 Data at Rest Encryption
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/005-virtual-machine-monitor.adoc b/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
index 8a66c08..1ead8e1 100644
--- a/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
+++ b/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
@@ -1,6 +1,4 @@
 = 005 Virtual Machine Monitor
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/006-drivers-on-host.adoc b/Documentation/doc/decisions/006-drivers-on-host.adoc
index b92d863..ce7a072 100644
--- a/Documentation/doc/decisions/006-drivers-on-host.adoc
+++ b/Documentation/doc/decisions/006-drivers-on-host.adoc
@@ -1,6 +1,4 @@
 = 006 Drivers on Host
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/007-usb-virtual-machines.adoc b/Documentation/doc/decisions/007-usb-virtual-machines.adoc
index d832691..f494537 100644
--- a/Documentation/doc/decisions/007-usb-virtual-machines.adoc
+++ b/Documentation/doc/decisions/007-usb-virtual-machines.adoc
@@ -1,6 +1,4 @@
 = 007 USB Virtual Machine
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
index c1e5b87..4dec40e 100644
--- a/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
+++ b/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
@@ -1,6 +1,4 @@
 = 008 Inter-VM Communication Mechanisms
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/index.adoc b/Documentation/doc/decisions/index.adoc
index a022239..8a5d237 100644
--- a/Documentation/doc/decisions/index.adoc
+++ b/Documentation/doc/decisions/index.adoc
@@ -1,6 +1,4 @@
 = Architecture Decision Records
-:page-has_children: true
-:page-parent: About Spectrum
 
 // 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/development/build-configuration.adoc b/Documentation/doc/development/build-configuration.adoc
index 49651d0..af7b9fa 100644
--- a/Documentation/doc/development/build-configuration.adoc
+++ b/Documentation/doc/development/build-configuration.adoc
@@ -1,5 +1,4 @@
 = Configuring the Build
-:page-parent: Development
 :page-nav_order: 1
 :example-caption: Test
 
diff --git a/Documentation/doc/development/built-in-vms.adoc b/Documentation/doc/development/built-in-vms.adoc
index d044e75..fdb5f15 100644
--- a/Documentation/doc/development/built-in-vms.adoc
+++ b/Documentation/doc/development/built-in-vms.adoc
@@ -1,5 +1,4 @@
 = Developing Built-in Application VMs
-:page-parent: Development
 :page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2023-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/checks.adoc b/Documentation/doc/development/checks.adoc
index 905d5b8..64463cc 100644
--- a/Documentation/doc/development/checks.adoc
+++ b/Documentation/doc/development/checks.adoc
@@ -1,5 +1,4 @@
 = Checks
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/debugging.adoc b/Documentation/doc/development/debugging.adoc
index f1bbf01..39fd989 100644
--- a/Documentation/doc/development/debugging.adoc
+++ b/Documentation/doc/development/debugging.adoc
@@ -1,5 +1,4 @@
 = Debugging
-:page-parent: Development
 :page-nav_order: 4
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/index.adoc b/Documentation/doc/development/index.adoc
index 4e50425..f5ddfe9 100644
--- a/Documentation/doc/development/index.adoc
+++ b/Documentation/doc/development/index.adoc
@@ -1,7 +1,6 @@
 = Development
 :description: Development progress, general development practices
 :page-nav_order: 4
-:page-has_children: true
 
 // 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/development/persistent-storage.adoc b/Documentation/doc/development/persistent-storage.adoc
index c4bcc16..e3db767 100644
--- a/Documentation/doc/development/persistent-storage.adoc
+++ b/Documentation/doc/development/persistent-storage.adoc
@@ -1,5 +1,4 @@
 = Persistent storage
-:page-parent: Development
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/release.adoc b/Documentation/doc/development/release.adoc
index 4ecbf03..2ab9d88 100644
--- a/Documentation/doc/development/release.adoc
+++ b/Documentation/doc/development/release.adoc
@@ -1,5 +1,4 @@
 = Release Builds
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/updates.adoc b/Documentation/doc/development/updates.adoc
index 8746f97..1ec08c2 100644
--- a/Documentation/doc/development/updates.adoc
+++ b/Documentation/doc/development/updates.adoc
@@ -1,5 +1,4 @@
 = Updating the OS
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2025 Demi Marie Obenour <demiobenour@gmail.com>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/uuid-reference.adoc b/Documentation/doc/development/uuid-reference.adoc
index 16279c8..21c8935 100644
--- a/Documentation/doc/development/uuid-reference.adoc
+++ b/Documentation/doc/development/uuid-reference.adoc
@@ -1,5 +1,4 @@
 = UUID Reference
-:page-parent: Development
 :page-nav_order: 6
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/index.adoc b/Documentation/doc/index.adoc
index 3bf3934..a24d85f 100644
--- a/Documentation/doc/index.adoc
+++ b/Documentation/doc/index.adoc
@@ -1,5 +1,4 @@
 = Spectrum Documentation
-:page-nav_exclude: true
 :page-liquid:
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/binary-cache.adoc b/Documentation/doc/installation/binary-cache.adoc
index 4feaad4..105e09d 100644
--- a/Documentation/doc/installation/binary-cache.adoc
+++ b/Documentation/doc/installation/binary-cache.adoc
@@ -1,5 +1,4 @@
 = Setting Up Binary Cache
-:page-parent: Build and Run
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022-2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/getting-spectrum.adoc b/Documentation/doc/installation/getting-spectrum.adoc
index 22c1fe3..478b1fc 100644
--- a/Documentation/doc/installation/getting-spectrum.adoc
+++ b/Documentation/doc/installation/getting-spectrum.adoc
@@ -1,5 +1,4 @@
 = Getting Spectrum
-:page-parent: Build and Run
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022-2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/index.adoc b/Documentation/doc/installation/index.adoc
index d1df2ed..79e68d9 100644
--- a/Documentation/doc/installation/index.adoc
+++ b/Documentation/doc/installation/index.adoc
@@ -1,7 +1,6 @@
 = Build and Run
 :description: How to download and install Spectrum OS.
 :page-nav_order: 2
-:page-has_children: true
 :page-has_toc: false
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/creating-custom-vms.adoc b/Documentation/doc/using-spectrum/creating-custom-vms.adoc
index 68213c8..5b74084 100644
--- a/Documentation/doc/using-spectrum/creating-custom-vms.adoc
+++ b/Documentation/doc/using-spectrum/creating-custom-vms.adoc
@@ -1,5 +1,4 @@
 = Creating Custom VMs
-:page-parent: Using Spectrum
 
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/index.adoc b/Documentation/doc/using-spectrum/index.adoc
index 25347a4..2464ad4 100644
--- a/Documentation/doc/using-spectrum/index.adoc
+++ b/Documentation/doc/using-spectrum/index.adoc
@@ -1,7 +1,6 @@
 = Using Spectrum
 :description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth).
 :page-nav_order: 3
-:page-has_children: true
 :page-has_toc: false
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/running-vms.adoc b/Documentation/doc/using-spectrum/running-vms.adoc
index 2b47fc0..d8a7732 100644
--- a/Documentation/doc/using-spectrum/running-vms.adoc
+++ b/Documentation/doc/using-spectrum/running-vms.adoc
@@ -1,5 +1,4 @@
 = Running VMs
-:page-parent: Using Spectrum
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/using-spectrum/vm-file-access.adoc b/Documentation/doc/using-spectrum/vm-file-access.adoc
index 6189233..d4276d4 100644
--- a/Documentation/doc/using-spectrum/vm-file-access.adoc
+++ b/Documentation/doc/using-spectrum/vm-file-access.adoc
@@ -1,5 +1,4 @@
 = VM File Access
-:page-parent: Using Spectrum
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/gemset.nix b/Documentation/gemset.nix
index 7b85a7f..b31a35e 100644
--- a/Documentation/gemset.nix
+++ b/Documentation/gemset.nix
@@ -165,17 +165,6 @@
     };
     version = "3.0.1";
   };
-  jekyll-include-cache = {
-    dependencies = ["jekyll"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "01d2l6qrmjc42664ns83cv36jbvalcxqbkmj5i22fakka7jvkm67";
-      type = "gem";
-    };
-    version = "0.2.1";
-  };
   jekyll-sass-converter = {
     dependencies = ["sass-embedded"];
     groups = ["default"];
@@ -187,17 +176,6 @@
     };
     version = "3.1.0";
   };
-  jekyll-seo-tag = {
-    dependencies = ["jekyll"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "0638mqhqynghnlnaz0xi1kvnv53wkggaq94flfzlxwandn8x2biz";
-      type = "gem";
-    };
-    version = "2.8.0";
-  };
   jekyll-watch = {
     dependencies = ["listen"];
     groups = ["default"];
@@ -219,17 +197,6 @@
     };
     version = "2.13.0";
   };
-  just-the-docs = {
-    dependencies = ["jekyll" "jekyll-include-cache" "jekyll-seo-tag" "rake"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "0y2mvzg2vxb4lk1rfay8d405qij4ifa65ypz09qj0945wf6qgsmw";
-      type = "gem";
-    };
-    version = "0.10.1";
-  };
   kramdown = {
     dependencies = ["rexml"];
     groups = ["default"];
-- 
2.51.2


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH 3/3] Documentation: uniform navigation across all pages
  2026-06-08 16:49 [PATCH 0/3] Documentation: render all pages in one style Valentin Gagarin
  2026-06-08 16:49 ` [PATCH 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
  2026-06-08 16:49 ` [PATCH 2/3] Documentation: drop Just the Docs Valentin Gagarin
@ 2026-06-08 16:49 ` Valentin Gagarin
  2026-06-08 16:49 ` [PATCH 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
                   ` (4 subsequent siblings)
  7 siblings, 0 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-08 16:49 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

- Render breadcrumb navigation for all pages
- Use common page layout for hard-coded HTML pages
- Sort hard-coded HTML into sitemap
- Show link to source in the footer

Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
---
 Documentation/_includes/breadcrumb.html       | 23 +++++++++++
 Documentation/_includes/footer_custom.html    | 10 ++---
 Documentation/_includes/sitemap.html          |  2 +-
 Documentation/_layouts/page.html              | 13 +++----
 Documentation/bibliography.html               | 38 +++---------------
 Documentation/contributing.html               | 38 +++---------------
 Documentation/design.html                     | 38 +++---------------
 Documentation/doc/index.adoc                  |  3 +-
 Documentation/impressum.html                  | 35 +++--------------
 Documentation/index.html                      | 33 +++-------------
 Documentation/logo/index.html                 | 38 +++---------------
 Documentation/motivation.html                 | 38 +++---------------
 .../software/cloud-hypervisor/index.html      | 39 ++-----------------
 Documentation/software/index.html             | 38 +++---------------
 14 files changed, 80 insertions(+), 306 deletions(-)
 create mode 100644 Documentation/_includes/breadcrumb.html

diff --git a/Documentation/_includes/breadcrumb.html b/Documentation/_includes/breadcrumb.html
new file mode 100644
index 0000000..f759807
--- /dev/null
+++ b/Documentation/_includes/breadcrumb.html
@@ -0,0 +1,23 @@
+{% comment %}
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
+{% endcomment %}
+{%- unless page.url == '/' -%}
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Spectrum</a></li>
+    {%- assign parts = page.url | split: '/' -%}
+    {%- assign acc = '' -%}
+    {%- for part in parts offset: 1 -%}
+      {%- assign acc = acc | append: '/' | append: part -%}
+      {%- assign parent_url = acc | append: '/' -%}
+      {%- if parent_url == page.url -%}{%- continue -%}{%- endif -%}
+      {%- assign parent = site.pages | where: 'url', parent_url | first -%}
+      {%- if parent %}
+    <li><a href="{{ parent.url }}">{{ parent.title }}</a></li>
+      {%- endif -%}
+    {%- endfor %}
+    <li aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+{%- endunless -%}
diff --git a/Documentation/_includes/footer_custom.html b/Documentation/_includes/footer_custom.html
index 2477920..c7ba518 100644
--- a/Documentation/_includes/footer_custom.html
+++ b/Documentation/_includes/footer_custom.html
@@ -2,9 +2,6 @@
 SPDX-FileCopyrightText: 2020 Alyssa Ross <hi@alyssa.is>
 SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later
 {% endcomment %}
-<p>
-<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
-
 <p>
 <small>Permission is granted to copy, distribute and/or modify this
 document under either the terms of the
@@ -15,6 +12,7 @@ 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>
+<p><small>
+<a href="/sitemap.html">Sitemap</a>
+<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
+<a href="/impressum.html" lang="de">Impressum</a>
diff --git a/Documentation/_includes/sitemap.html b/Documentation/_includes/sitemap.html
index cd493f8..e1a573c 100644
--- a/Documentation/_includes/sitemap.html
+++ b/Documentation/_includes/sitemap.html
@@ -33,7 +33,7 @@ which we assume if it is constructed by a directory and contains an index file.
     {%- 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 -%}
+    {%- if p.name == "index.adoc" or p.name == "index.html" -%}{%- 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 -%}
diff --git a/Documentation/_layouts/page.html b/Documentation/_layouts/page.html
index 230b601..f2cf0f6 100644
--- a/Documentation/_layouts/page.html
+++ b/Documentation/_layouts/page.html
@@ -3,7 +3,7 @@ SPDX-License-Identifier: GPL-3.0-or-later
 SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 {% endcomment %}
 <!doctype html>
-<html lang="en">
+<html lang="{{ page.lang | default: "en" }}">
 
 <head>
 
@@ -17,13 +17,10 @@ SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 
 <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>
+{% include breadcrumb.html %}
+
+{% assign ext = page.path | split: "." | last %}
+{% if ext == "html" and page.no_heading != true %}<h1>{{ page.title }}</h1>{% endif %}
 
 {{ content }}
 
diff --git a/Documentation/bibliography.html b/Documentation/bibliography.html
index f9a8efd..175115a 100644
--- a/Documentation/bibliography.html
+++ b/Documentation/bibliography.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Bibliography
+nav_order: 200
+---
 <!-- SPDX-FileCopyrightText: 2019-2023 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum Bibliography</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Bibliography</h1>
 
 <p>If you'd like to find out when new links are posted, subscribe to
 the <a href="https://spectrum-os.org/git/www/atom/bibliography.html">cgit
@@ -137,16 +122,3 @@ atom feed for this page</a>.
   <li><cite><a href="https://github.com/cloud-hypervisor/cloud-hypervisor">cloud-hypervisor</a></cite>
 
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/contributing.html b/Documentation/contributing.html
index ea85499..8f9948b 100644
--- a/Documentation/contributing.html
+++ b/Documentation/contributing.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Contributing to Spectrum
+nav_order: 3
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Contributing to Spectrum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Contributing to Spectrum</h1>
 
 <p>
 Thank you so much for your interest in contributing to Spectrum.
@@ -104,16 +89,3 @@ on <a href="/doc/contributing/communication.html#spectrum-discuss">spectrum-disc
 or in real time
 on <a href="/doc/contributing/communication.html#chat">Matrix or
 IRC</a>.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/design.html b/Documentation/design.html
index 51e0b77..0aa8762 100644
--- a/Documentation/design.html
+++ b/Documentation/design.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Design
+nav_order: 2
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum Design</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Spectrum Design</h1>
 
 <p>
 Spectrum will, for now, be a Linux-based system, with packages from
@@ -96,16 +81,3 @@ diverse range of hardware, to verify that the images correspond to the
 source code, and are free of tampering.  Work
 like <a href="https://nix-community.github.io/trustix/">Trustix</a>
 will be important to reaching this goal.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/doc/index.adoc b/Documentation/doc/index.adoc
index a24d85f..81b2a18 100644
--- a/Documentation/doc/index.adoc
+++ b/Documentation/doc/index.adoc
@@ -1,5 +1,6 @@
-= Spectrum Documentation
+= Documentation
 :page-liquid:
+:page-nav_order: 100
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/impressum.html b/Documentation/impressum.html
index b4806fe..416ce67 100644
--- a/Documentation/impressum.html
+++ b/Documentation/impressum.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Impressum
+lang: de
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="de">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Impressum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Impressum</h1>
 
 <address>
   <p>
@@ -32,13 +17,3 @@
   <p>
   hi@alyssa.is
 </address>
-
-<p lang="en">
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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>
diff --git a/Documentation/index.html b/Documentation/index.html
index 51685dd..6d6faf7 100644
--- a/Documentation/index.html
+++ b/Documentation/index.html
@@ -1,20 +1,12 @@
-<!doctype html>
+---
+layout: page
+title: Spectrum, a step towards usable secure computing
+no_heading: true
+nav_order: 0
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum, a step towards usable secure computing</title>
-
-<body>
 
 <a href="logo" style="float: left; margin: 0 1em 0.5em 0">
   <img class="logo" src="logo/logo_html.svg" width="70" height="70" alt="Spectrum logo">
@@ -95,16 +87,3 @@ initiative by the Digital Single Market of the European Commission.
     <li><a href="https://cryptpad.fr/kanban/#/2/kanban/view/yLtGXWLV6U7X5+Z1ay+oXKZMrSacqQe+51nXZYRh3ck/">Upstream bug/patch tracking</a>
   </ul>
 </nav>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/logo/index.html b/Documentation/logo/index.html
index 2354062..fbab443 100644
--- a/Documentation/logo/index.html
+++ b/Documentation/logo/index.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Logo
+nav_order: 1002
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo_html.svg">
-<link rel="stylesheet" href="../style.css">
-
-<title>Spectrum logo</title>
-
-<body>
-
-<nav>
-  <a href="..">Spectrum</a>
-</nav>
-
-<h1>Logo</h1>
 
 <p>
 <img class="logo" src="logo_html.svg" width="200" height="200" alt="" style="margin: 0 auto">
@@ -48,16 +33,3 @@ Mesh Gradients</a>.
   <li><a href="logo_mesh.svg" download>logo_mesh.svg</a> (for Inkscape)
 
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/motivation.html b/Documentation/motivation.html
index 4cbe5b0..e144251 100644
--- a/Documentation/motivation.html
+++ b/Documentation/motivation.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Motivation for Spectrum
+nav_order: 1
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Motivation for Spectrum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Motivation for Spectrum</h1>
 
 <p>
 Existing attempts to improve on the security of Unix-like operating
@@ -122,16 +107,3 @@ major security issue.
 
 <p>
 The last release of SubgraphOS was an alpha in 2017.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/software/cloud-hypervisor/index.html b/Documentation/software/cloud-hypervisor/index.html
index 1845068..9b4315c 100644
--- a/Documentation/software/cloud-hypervisor/index.html
+++ b/Documentation/software/cloud-hypervisor/index.html
@@ -1,26 +1,10 @@
-<!doctype html>
+---
+layout: page
+title: Cloud Hypervisor with virtio-gpu support
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="../../logo/logo_html.svg">
-<link rel="stylesheet" href="../../style.css">
-
-<title>Cloud Hypervisor with virtio-gpu support</title>
-
-<body>
-
-<nav>
-  <a href="../..">Spectrum</a>
-</nav>
-
-<h1>Cloud Hypervisor with virtio-gpu support</h1>
 
 <p>
 This is a patchset for <a href="https://cloudhypervisor.org/">Cloud
@@ -162,18 +146,3 @@ the <a href="mailto:discuss@spectrum-os.org">discuss@spectrum-os.org</a>
 list</a>, or ask in the
 Spectrum <a href="/doc/contributing/communication.html#chat">Matrix
 chat</a>.
-
-<hr>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../../impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/software/index.html b/Documentation/software/index.html
index 2a8a852..0265ca1 100644
--- a/Documentation/software/index.html
+++ b/Documentation/software/index.html
@@ -1,41 +1,13 @@
-<!doctype html>
+---
+layout: page
+title: Spectrum software
+nav_order: 10
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="../logo/logo_html.svg">
-<link rel="stylesheet" href="../style.css">
-
-<title>Spectrum software</title>
-
-<body>
-
-<nav>
-  <a href="..">Spectrum</a>
-</nav>
-
-<h1>Spectrum software</h1>
 
 <ul>
   <li><a href="cloud-hypervisor">Cloud Hypervisor with virtio-gpu
   support</a>
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../impressum.html" lang="de"><small>Impressum</small></a>
-- 
2.51.2


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-08 16:49 [PATCH 0/3] Documentation: render all pages in one style Valentin Gagarin
                   ` (2 preceding siblings ...)
  2026-06-08 16:49 ` [PATCH 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
@ 2026-06-08 16:49 ` Valentin Gagarin
  2026-06-09 11:45   ` Alyssa Ross
  2026-06-08 16:49 ` [PATCH 2/3] Documentation: drop Just the Docs Valentin Gagarin
                   ` (3 subsequent siblings)
  7 siblings, 1 reply; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-08 16:49 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

- 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..7f51a0a 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


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH 2/3] Documentation: drop Just the Docs
  2026-06-08 16:49 [PATCH 0/3] Documentation: render all pages in one style Valentin Gagarin
                   ` (3 preceding siblings ...)
  2026-06-08 16:49 ` [PATCH 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
@ 2026-06-08 16:49 ` Valentin Gagarin
  2026-06-09 11:43   ` Alyssa Ross
  2026-06-08 16:49 ` [PATCH 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
                   ` (2 subsequent siblings)
  7 siblings, 1 reply; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-08 16:49 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
---
 Documentation/Gemfile                         |  1 -
 Documentation/Gemfile.lock                    | 12 +-----
 Documentation/_config.yml                     |  7 ---
 Documentation/_includes/title.html            | 13 ------
 Documentation/_plugins/site_title_link.rb     | 10 -----
 Documentation/_sass/custom/custom.scss        | 43 -------------------
 Documentation/doc/about/architecture.adoc     |  1 -
 Documentation/doc/about/index.adoc            |  1 -
 Documentation/doc/about/requirements.adoc     |  1 -
 Documentation/doc/contributing/b4.adoc        |  2 -
 .../contributing/building-documentation.adoc  |  1 -
 .../doc/contributing/communication.adoc       |  1 -
 .../doc/contributing/first-patch.adoc         |  2 -
 Documentation/doc/contributing/index.adoc     |  1 -
 Documentation/doc/contributing/replying.adoc  |  2 -
 .../doc/contributing/reviewing-patches.adoc   |  2 -
 .../doc/contributing/testing-patches.adoc     |  2 -
 .../contributing/working-with-patches.adoc    |  2 -
 .../contributing/writing_documentation.adoc   |  3 +-
 .../decisions/001-host-update-mechanism.adoc  |  2 -
 .../doc/decisions/002-install-options.adoc    |  2 -
 .../doc/decisions/003-partitioning.adoc       |  2 -
 .../004-data-at-rest-encryption.adoc          |  2 -
 .../005-virtual-machine-monitor.adoc          |  2 -
 .../doc/decisions/006-drivers-on-host.adoc    |  2 -
 .../decisions/007-usb-virtual-machines.adoc   |  2 -
 ...008-inter-vm-communication-mechanisms.adoc |  2 -
 Documentation/doc/decisions/index.adoc        |  2 -
 .../doc/development/build-configuration.adoc  |  1 -
 .../doc/development/built-in-vms.adoc         |  1 -
 Documentation/doc/development/checks.adoc     |  1 -
 Documentation/doc/development/debugging.adoc  |  1 -
 Documentation/doc/development/index.adoc      |  1 -
 .../doc/development/persistent-storage.adoc   |  1 -
 Documentation/doc/development/release.adoc    |  1 -
 Documentation/doc/development/updates.adoc    |  1 -
 .../doc/development/uuid-reference.adoc       |  1 -
 Documentation/doc/index.adoc                  |  1 -
 .../doc/installation/binary-cache.adoc        |  1 -
 .../doc/installation/getting-spectrum.adoc    |  1 -
 Documentation/doc/installation/index.adoc     |  1 -
 .../using-spectrum/creating-custom-vms.adoc   |  1 -
 Documentation/doc/using-spectrum/index.adoc   |  1 -
 .../doc/using-spectrum/running-vms.adoc       |  1 -
 .../doc/using-spectrum/vm-file-access.adoc    |  1 -
 Documentation/gemset.nix                      | 33 --------------
 46 files changed, 2 insertions(+), 173 deletions(-)
 delete mode 100644 Documentation/_includes/title.html
 delete mode 100644 Documentation/_plugins/site_title_link.rb
 delete mode 100644 Documentation/_sass/custom/custom.scss

diff --git a/Documentation/Gemfile b/Documentation/Gemfile
index 3c3f59d..a6396da 100644
--- a/Documentation/Gemfile
+++ b/Documentation/Gemfile
@@ -6,4 +6,3 @@ source "https://rubygems.org"
 
 gem "jekyll"
 gem "jekyll-asciidoc"
-gem "just-the-docs", "~> 0.10.0"
diff --git a/Documentation/Gemfile.lock b/Documentation/Gemfile.lock
index e7b515e..992e6da 100644
--- a/Documentation/Gemfile.lock
+++ b/Documentation/Gemfile.lock
@@ -43,20 +43,11 @@ GEM
     jekyll-asciidoc (3.0.1)
       asciidoctor (>= 1.5.0, < 3.0.0)
       jekyll (>= 3.0.0)
-    jekyll-include-cache (0.2.1)
-      jekyll (>= 3.7, < 5.0)
     jekyll-sass-converter (3.1.0)
       sass-embedded (~> 1.75)
-    jekyll-seo-tag (2.8.0)
-      jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     json (2.13.0)
-    just-the-docs (0.10.1)
-      jekyll (>= 3.8.5)
-      jekyll-include-cache
-      jekyll-seo-tag (>= 2.0)
-      rake (>= 12.3.1)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
@@ -90,7 +81,6 @@ PLATFORMS
 DEPENDENCIES
   jekyll
   jekyll-asciidoc
-  just-the-docs (~> 0.10.0)
 
 BUNDLED WITH
-   2.6.9
+   2.7.2
diff --git a/Documentation/_config.yml b/Documentation/_config.yml
index b11c399..cc3e8ea 100644
--- a/Documentation/_config.yml
+++ b/Documentation/_config.yml
@@ -2,13 +2,6 @@
 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 ---
 title: Spectrum documentation
-logo: /logo/logo_html.svg
-theme: just-the-docs
-aux_links:
-  Home:
-    - /
-  Git:
-    - "https://spectrum-os.org/git/"
 plugins:
   - jekyll-asciidoc
 exclude:
diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html
deleted file mode 100644
index 90ef71b..0000000
--- a/Documentation/_includes/title.html
+++ /dev/null
@@ -1,13 +0,0 @@
-{% comment %}
-SPDX-License-Identifier: MIT
-SPDX-FileCopyrightText: 2016 Patrick Marsceill
-SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-Override of: https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_includes/title.html
-{% endcomment %}
-{% if site.logo %}
-  <div class="site-logo" role="img" aria-label="{{ site.title }}"></div>
-{% endif %}
-{% if site.title %}
-  {{ site.title }}
-{% endif %}
diff --git a/Documentation/_plugins/site_title_link.rb b/Documentation/_plugins/site_title_link.rb
deleted file mode 100644
index 4095701..0000000
--- a/Documentation/_plugins/site_title_link.rb
+++ /dev/null
@@ -1,10 +0,0 @@
-# SPDX-License-Identifier: EUPL-1.2+
-# SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-# Just the Docs hardcodes the site header link to `/`.
-# https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_includes/components/sidebar.html#L14
-# Make it point to the docs root, not the top-level site.
-Jekyll::Hooks.register [:pages, :documents], :post_render do |item|
-  item.output.sub!('<a href="/" class="site-title',
-                   '<a href="/doc/" class="site-title')
-end
diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss
deleted file mode 100644
index 48b1d41..0000000
--- a/Documentation/_sass/custom/custom.scss
+++ /dev/null
@@ -1,43 +0,0 @@
-// SPDX-License-Identifier: MIT
-// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
-// SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-.main-content {
-	// Just the Docs puts titles next to definitions, rather than on
-	// the line before.  This makes the definitions too horizontally
-	// compressed.
-	dl {
-		display: block;
-	}
-	dt {
-		text-align: left;
-		font-weight: bold;
-
-		&::after {
-			content: none;
-		}
-	}
-	dd {
-		margin-left: 2ch;
-	}
-}
-
-// Make the logo and title fit the site header.
-.site-header {
-  .site-logo {
-    width: 3rem;
-  }
-
-  // Just the Docs displays a sidebar at the "medium size" `md` breakpoint and above.
-  // Use the upstream `mq` media query mixin to target that breakpoint.
-  // https://just-the-docs.com/docs/utilities/responsive-modifiers/
-  // https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_sass/support/mixins/_layout.scss#L3-L8
-  @include mq(md) {
-    .site-logo {
-      width: 5.5rem;
-    }
-    .site-title {
-      font-size: 1.25rem !important;
-    }
-  }
-}
diff --git a/Documentation/doc/about/architecture.adoc b/Documentation/doc/about/architecture.adoc
index 2b86616..bbc927d 100644
--- a/Documentation/doc/about/architecture.adoc
+++ b/Documentation/doc/about/architecture.adoc
@@ -1,5 +1,4 @@
 = Architecture
-:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/about/index.adoc b/Documentation/doc/about/index.adoc
index 6961b6a..65f7f7c 100644
--- a/Documentation/doc/about/index.adoc
+++ b/Documentation/doc/about/index.adoc
@@ -1,7 +1,6 @@
 = About Spectrum
 :description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum.
 :page-nav_order: 1
-:page-has_children: true
 
 // 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/about/requirements.adoc b/Documentation/doc/about/requirements.adoc
index 40f802f..6c32c31 100644
--- a/Documentation/doc/about/requirements.adoc
+++ b/Documentation/doc/about/requirements.adoc
@@ -1,5 +1,4 @@
 = Hardware and firmware requirements
-:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/contributing/b4.adoc b/Documentation/doc/contributing/b4.adoc
index 81f2519..3734c3a 100644
--- a/Documentation/doc/contributing/b4.adoc
+++ b/Documentation/doc/contributing/b4.adoc
@@ -1,6 +1,4 @@
 = Installing and Configuring b4
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/building-documentation.adoc b/Documentation/doc/contributing/building-documentation.adoc
index 919a021..b691d4d 100644
--- a/Documentation/doc/contributing/building-documentation.adoc
+++ b/Documentation/doc/contributing/building-documentation.adoc
@@ -1,5 +1,4 @@
 = Building Documentation
-:page-parent: Contributing
 :page-nav_order: 4
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/contributing/communication.adoc b/Documentation/doc/contributing/communication.adoc
index 874ad4e..5099c9c 100644
--- a/Documentation/doc/contributing/communication.adoc
+++ b/Documentation/doc/contributing/communication.adoc
@@ -1,7 +1,6 @@
 = Communication in Spectrum
 :description: Channels, announcements and so on.
 :page-nav_order: 1
-:page-parent: Contributing
 
 // SPDX-FileCopyrightText: 2019-2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2023 Unikie
diff --git a/Documentation/doc/contributing/first-patch.adoc b/Documentation/doc/contributing/first-patch.adoc
index 38326c0..2625888 100644
--- a/Documentation/doc/contributing/first-patch.adoc
+++ b/Documentation/doc/contributing/first-patch.adoc
@@ -1,6 +1,4 @@
 = Sending Your Patch
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/contributing/index.adoc b/Documentation/doc/contributing/index.adoc
index 5ae6811..2607b35 100644
--- a/Documentation/doc/contributing/index.adoc
+++ b/Documentation/doc/contributing/index.adoc
@@ -1,7 +1,6 @@
 = Contributing
 :description: How to contribute changes to the Spectrum source repository.
 :page-nav_order: 5
-:page-has_children: true
 
 // SPDX-FileCopyrightText: 2023 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/contributing/replying.adoc b/Documentation/doc/contributing/replying.adoc
index c478afb..c6ec4b8 100644
--- a/Documentation/doc/contributing/replying.adoc
+++ b/Documentation/doc/contributing/replying.adoc
@@ -1,6 +1,4 @@
 = Replying to Messages in the Mailing List Archives
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/reviewing-patches.adoc b/Documentation/doc/contributing/reviewing-patches.adoc
index 0e73b0e..224e314 100644
--- a/Documentation/doc/contributing/reviewing-patches.adoc
+++ b/Documentation/doc/contributing/reviewing-patches.adoc
@@ -1,6 +1,4 @@
 = Reviewing Patches
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/testing-patches.adoc b/Documentation/doc/contributing/testing-patches.adoc
index d98b738..031855d 100644
--- a/Documentation/doc/contributing/testing-patches.adoc
+++ b/Documentation/doc/contributing/testing-patches.adoc
@@ -1,6 +1,4 @@
 = Testing Patches
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/working-with-patches.adoc b/Documentation/doc/contributing/working-with-patches.adoc
index 8e22343..6e1e83e 100644
--- a/Documentation/doc/contributing/working-with-patches.adoc
+++ b/Documentation/doc/contributing/working-with-patches.adoc
@@ -1,7 +1,5 @@
 = Working with Patches
-:page-parent: Contributing
 :page-nav_order: 2
-:page-has_children: true
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-FileCopyrightText: 2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/writing_documentation.adoc b/Documentation/doc/contributing/writing_documentation.adoc
index cb09241..33e4480 100644
--- a/Documentation/doc/contributing/writing_documentation.adoc
+++ b/Documentation/doc/contributing/writing_documentation.adoc
@@ -1,7 +1,6 @@
 = Documentation Style Guide
 :description: Channels, announcements and so on.
 :page-nav_order: 3
-:page-parent: Contributing
 
 // SPDX-FileCopyrightText: 2023 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -12,7 +11,7 @@ Please follow these guidelines and conventions
 when editing the documentation.
 
 We use https://nixos.org/manual/nix/stable/introduction.html[Nix] and
-https://github.com/just-the-docs/just-the-docs[Just the Docs] for
+https://jekyllrb.com/[Jekyll] for
 building the documentation. Sources are written in AsciiDoc If you are
 new with it, see
 https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation].
diff --git a/Documentation/doc/decisions/001-host-update-mechanism.adoc b/Documentation/doc/decisions/001-host-update-mechanism.adoc
index 39f9f28..d0ab341 100644
--- a/Documentation/doc/decisions/001-host-update-mechanism.adoc
+++ b/Documentation/doc/decisions/001-host-update-mechanism.adoc
@@ -1,6 +1,4 @@
 = 001 Host Update Mechanism
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/002-install-options.adoc b/Documentation/doc/decisions/002-install-options.adoc
index 4a745eb..f56a626 100644
--- a/Documentation/doc/decisions/002-install-options.adoc
+++ b/Documentation/doc/decisions/002-install-options.adoc
@@ -1,6 +1,4 @@
 = 002 Install Options
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/003-partitioning.adoc b/Documentation/doc/decisions/003-partitioning.adoc
index 8e538c3..39f0ee2 100644
--- a/Documentation/doc/decisions/003-partitioning.adoc
+++ b/Documentation/doc/decisions/003-partitioning.adoc
@@ -1,6 +1,4 @@
 = 003 Partitioning
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/004-data-at-rest-encryption.adoc b/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
index 5b0f518..8f4d430 100644
--- a/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
+++ b/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
@@ -1,6 +1,4 @@
 = 004 Data at Rest Encryption
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/005-virtual-machine-monitor.adoc b/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
index 8a66c08..1ead8e1 100644
--- a/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
+++ b/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
@@ -1,6 +1,4 @@
 = 005 Virtual Machine Monitor
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/006-drivers-on-host.adoc b/Documentation/doc/decisions/006-drivers-on-host.adoc
index b92d863..ce7a072 100644
--- a/Documentation/doc/decisions/006-drivers-on-host.adoc
+++ b/Documentation/doc/decisions/006-drivers-on-host.adoc
@@ -1,6 +1,4 @@
 = 006 Drivers on Host
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/007-usb-virtual-machines.adoc b/Documentation/doc/decisions/007-usb-virtual-machines.adoc
index d832691..f494537 100644
--- a/Documentation/doc/decisions/007-usb-virtual-machines.adoc
+++ b/Documentation/doc/decisions/007-usb-virtual-machines.adoc
@@ -1,6 +1,4 @@
 = 007 USB Virtual Machine
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
index c1e5b87..4dec40e 100644
--- a/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
+++ b/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
@@ -1,6 +1,4 @@
 = 008 Inter-VM Communication Mechanisms
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/index.adoc b/Documentation/doc/decisions/index.adoc
index a022239..8a5d237 100644
--- a/Documentation/doc/decisions/index.adoc
+++ b/Documentation/doc/decisions/index.adoc
@@ -1,6 +1,4 @@
 = Architecture Decision Records
-:page-has_children: true
-:page-parent: About Spectrum
 
 // 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/development/build-configuration.adoc b/Documentation/doc/development/build-configuration.adoc
index 49651d0..af7b9fa 100644
--- a/Documentation/doc/development/build-configuration.adoc
+++ b/Documentation/doc/development/build-configuration.adoc
@@ -1,5 +1,4 @@
 = Configuring the Build
-:page-parent: Development
 :page-nav_order: 1
 :example-caption: Test
 
diff --git a/Documentation/doc/development/built-in-vms.adoc b/Documentation/doc/development/built-in-vms.adoc
index d044e75..fdb5f15 100644
--- a/Documentation/doc/development/built-in-vms.adoc
+++ b/Documentation/doc/development/built-in-vms.adoc
@@ -1,5 +1,4 @@
 = Developing Built-in Application VMs
-:page-parent: Development
 :page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2023-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/checks.adoc b/Documentation/doc/development/checks.adoc
index 905d5b8..64463cc 100644
--- a/Documentation/doc/development/checks.adoc
+++ b/Documentation/doc/development/checks.adoc
@@ -1,5 +1,4 @@
 = Checks
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/debugging.adoc b/Documentation/doc/development/debugging.adoc
index f1bbf01..39fd989 100644
--- a/Documentation/doc/development/debugging.adoc
+++ b/Documentation/doc/development/debugging.adoc
@@ -1,5 +1,4 @@
 = Debugging
-:page-parent: Development
 :page-nav_order: 4
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/index.adoc b/Documentation/doc/development/index.adoc
index 4e50425..f5ddfe9 100644
--- a/Documentation/doc/development/index.adoc
+++ b/Documentation/doc/development/index.adoc
@@ -1,7 +1,6 @@
 = Development
 :description: Development progress, general development practices
 :page-nav_order: 4
-:page-has_children: true
 
 // 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/development/persistent-storage.adoc b/Documentation/doc/development/persistent-storage.adoc
index c4bcc16..e3db767 100644
--- a/Documentation/doc/development/persistent-storage.adoc
+++ b/Documentation/doc/development/persistent-storage.adoc
@@ -1,5 +1,4 @@
 = Persistent storage
-:page-parent: Development
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/release.adoc b/Documentation/doc/development/release.adoc
index 4ecbf03..2ab9d88 100644
--- a/Documentation/doc/development/release.adoc
+++ b/Documentation/doc/development/release.adoc
@@ -1,5 +1,4 @@
 = Release Builds
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/updates.adoc b/Documentation/doc/development/updates.adoc
index 8746f97..1ec08c2 100644
--- a/Documentation/doc/development/updates.adoc
+++ b/Documentation/doc/development/updates.adoc
@@ -1,5 +1,4 @@
 = Updating the OS
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2025 Demi Marie Obenour <demiobenour@gmail.com>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/uuid-reference.adoc b/Documentation/doc/development/uuid-reference.adoc
index 16279c8..21c8935 100644
--- a/Documentation/doc/development/uuid-reference.adoc
+++ b/Documentation/doc/development/uuid-reference.adoc
@@ -1,5 +1,4 @@
 = UUID Reference
-:page-parent: Development
 :page-nav_order: 6
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/index.adoc b/Documentation/doc/index.adoc
index 3bf3934..a24d85f 100644
--- a/Documentation/doc/index.adoc
+++ b/Documentation/doc/index.adoc
@@ -1,5 +1,4 @@
 = Spectrum Documentation
-:page-nav_exclude: true
 :page-liquid:
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/binary-cache.adoc b/Documentation/doc/installation/binary-cache.adoc
index 4feaad4..105e09d 100644
--- a/Documentation/doc/installation/binary-cache.adoc
+++ b/Documentation/doc/installation/binary-cache.adoc
@@ -1,5 +1,4 @@
 = Setting Up Binary Cache
-:page-parent: Build and Run
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022-2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/getting-spectrum.adoc b/Documentation/doc/installation/getting-spectrum.adoc
index 22c1fe3..478b1fc 100644
--- a/Documentation/doc/installation/getting-spectrum.adoc
+++ b/Documentation/doc/installation/getting-spectrum.adoc
@@ -1,5 +1,4 @@
 = Getting Spectrum
-:page-parent: Build and Run
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022-2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/index.adoc b/Documentation/doc/installation/index.adoc
index d1df2ed..79e68d9 100644
--- a/Documentation/doc/installation/index.adoc
+++ b/Documentation/doc/installation/index.adoc
@@ -1,7 +1,6 @@
 = Build and Run
 :description: How to download and install Spectrum OS.
 :page-nav_order: 2
-:page-has_children: true
 :page-has_toc: false
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/creating-custom-vms.adoc b/Documentation/doc/using-spectrum/creating-custom-vms.adoc
index 68213c8..5b74084 100644
--- a/Documentation/doc/using-spectrum/creating-custom-vms.adoc
+++ b/Documentation/doc/using-spectrum/creating-custom-vms.adoc
@@ -1,5 +1,4 @@
 = Creating Custom VMs
-:page-parent: Using Spectrum
 
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/index.adoc b/Documentation/doc/using-spectrum/index.adoc
index 25347a4..2464ad4 100644
--- a/Documentation/doc/using-spectrum/index.adoc
+++ b/Documentation/doc/using-spectrum/index.adoc
@@ -1,7 +1,6 @@
 = Using Spectrum
 :description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth).
 :page-nav_order: 3
-:page-has_children: true
 :page-has_toc: false
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/running-vms.adoc b/Documentation/doc/using-spectrum/running-vms.adoc
index 2b47fc0..d8a7732 100644
--- a/Documentation/doc/using-spectrum/running-vms.adoc
+++ b/Documentation/doc/using-spectrum/running-vms.adoc
@@ -1,5 +1,4 @@
 = Running VMs
-:page-parent: Using Spectrum
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/using-spectrum/vm-file-access.adoc b/Documentation/doc/using-spectrum/vm-file-access.adoc
index 6189233..d4276d4 100644
--- a/Documentation/doc/using-spectrum/vm-file-access.adoc
+++ b/Documentation/doc/using-spectrum/vm-file-access.adoc
@@ -1,5 +1,4 @@
 = VM File Access
-:page-parent: Using Spectrum
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/gemset.nix b/Documentation/gemset.nix
index 7b85a7f..b31a35e 100644
--- a/Documentation/gemset.nix
+++ b/Documentation/gemset.nix
@@ -165,17 +165,6 @@
     };
     version = "3.0.1";
   };
-  jekyll-include-cache = {
-    dependencies = ["jekyll"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "01d2l6qrmjc42664ns83cv36jbvalcxqbkmj5i22fakka7jvkm67";
-      type = "gem";
-    };
-    version = "0.2.1";
-  };
   jekyll-sass-converter = {
     dependencies = ["sass-embedded"];
     groups = ["default"];
@@ -187,17 +176,6 @@
     };
     version = "3.1.0";
   };
-  jekyll-seo-tag = {
-    dependencies = ["jekyll"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "0638mqhqynghnlnaz0xi1kvnv53wkggaq94flfzlxwandn8x2biz";
-      type = "gem";
-    };
-    version = "2.8.0";
-  };
   jekyll-watch = {
     dependencies = ["listen"];
     groups = ["default"];
@@ -219,17 +197,6 @@
     };
     version = "2.13.0";
   };
-  just-the-docs = {
-    dependencies = ["jekyll" "jekyll-include-cache" "jekyll-seo-tag" "rake"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "0y2mvzg2vxb4lk1rfay8d405qij4ifa65ypz09qj0945wf6qgsmw";
-      type = "gem";
-    };
-    version = "0.10.1";
-  };
   kramdown = {
     dependencies = ["rexml"];
     groups = ["default"];
-- 
2.51.2


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH 3/3] Documentation: uniform navigation across all pages
  2026-06-08 16:49 [PATCH 0/3] Documentation: render all pages in one style Valentin Gagarin
                   ` (4 preceding siblings ...)
  2026-06-08 16:49 ` [PATCH 2/3] Documentation: drop Just the Docs Valentin Gagarin
@ 2026-06-08 16:49 ` Valentin Gagarin
  2026-06-09 11:54   ` Alyssa Ross
  2026-06-11  6:37 ` [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
  2026-06-16  9:35 ` [PATCH v3 0/3] Documentation: render all pages in one style Valentin Gagarin
  7 siblings, 1 reply; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-08 16:49 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

- Render breadcrumb navigation for all pages
- Use common page layout for hard-coded HTML pages
- Sort hard-coded HTML into sitemap
- Show link to source in the footer

Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
---
 Documentation/_includes/breadcrumb.html       | 23 +++++++++++
 Documentation/_includes/footer_custom.html    | 10 ++---
 Documentation/_includes/sitemap.html          |  2 +-
 Documentation/_layouts/page.html              | 13 +++----
 Documentation/bibliography.html               | 38 +++---------------
 Documentation/contributing.html               | 38 +++---------------
 Documentation/design.html                     | 38 +++---------------
 Documentation/doc/index.adoc                  |  3 +-
 Documentation/impressum.html                  | 35 +++--------------
 Documentation/index.html                      | 33 +++-------------
 Documentation/logo/index.html                 | 38 +++---------------
 Documentation/motivation.html                 | 38 +++---------------
 .../software/cloud-hypervisor/index.html      | 39 ++-----------------
 Documentation/software/index.html             | 38 +++---------------
 14 files changed, 80 insertions(+), 306 deletions(-)
 create mode 100644 Documentation/_includes/breadcrumb.html

diff --git a/Documentation/_includes/breadcrumb.html b/Documentation/_includes/breadcrumb.html
new file mode 100644
index 0000000..f759807
--- /dev/null
+++ b/Documentation/_includes/breadcrumb.html
@@ -0,0 +1,23 @@
+{% comment %}
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
+{% endcomment %}
+{%- unless page.url == '/' -%}
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Spectrum</a></li>
+    {%- assign parts = page.url | split: '/' -%}
+    {%- assign acc = '' -%}
+    {%- for part in parts offset: 1 -%}
+      {%- assign acc = acc | append: '/' | append: part -%}
+      {%- assign parent_url = acc | append: '/' -%}
+      {%- if parent_url == page.url -%}{%- continue -%}{%- endif -%}
+      {%- assign parent = site.pages | where: 'url', parent_url | first -%}
+      {%- if parent %}
+    <li><a href="{{ parent.url }}">{{ parent.title }}</a></li>
+      {%- endif -%}
+    {%- endfor %}
+    <li aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+{%- endunless -%}
diff --git a/Documentation/_includes/footer_custom.html b/Documentation/_includes/footer_custom.html
index 2477920..c7ba518 100644
--- a/Documentation/_includes/footer_custom.html
+++ b/Documentation/_includes/footer_custom.html
@@ -2,9 +2,6 @@
 SPDX-FileCopyrightText: 2020 Alyssa Ross <hi@alyssa.is>
 SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later
 {% endcomment %}
-<p>
-<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
-
 <p>
 <small>Permission is granted to copy, distribute and/or modify this
 document under either the terms of the
@@ -15,6 +12,7 @@ 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>
+<p><small>
+<a href="/sitemap.html">Sitemap</a>
+<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
+<a href="/impressum.html" lang="de">Impressum</a>
diff --git a/Documentation/_includes/sitemap.html b/Documentation/_includes/sitemap.html
index cd493f8..e1a573c 100644
--- a/Documentation/_includes/sitemap.html
+++ b/Documentation/_includes/sitemap.html
@@ -33,7 +33,7 @@ which we assume if it is constructed by a directory and contains an index file.
     {%- 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 -%}
+    {%- if p.name == "index.adoc" or p.name == "index.html" -%}{%- 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 -%}
diff --git a/Documentation/_layouts/page.html b/Documentation/_layouts/page.html
index 230b601..f2cf0f6 100644
--- a/Documentation/_layouts/page.html
+++ b/Documentation/_layouts/page.html
@@ -3,7 +3,7 @@ SPDX-License-Identifier: GPL-3.0-or-later
 SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 {% endcomment %}
 <!doctype html>
-<html lang="en">
+<html lang="{{ page.lang | default: "en" }}">
 
 <head>
 
@@ -17,13 +17,10 @@ SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 
 <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>
+{% include breadcrumb.html %}
+
+{% assign ext = page.path | split: "." | last %}
+{% if ext == "html" and page.no_heading != true %}<h1>{{ page.title }}</h1>{% endif %}
 
 {{ content }}
 
diff --git a/Documentation/bibliography.html b/Documentation/bibliography.html
index f9a8efd..175115a 100644
--- a/Documentation/bibliography.html
+++ b/Documentation/bibliography.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Bibliography
+nav_order: 200
+---
 <!-- SPDX-FileCopyrightText: 2019-2023 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum Bibliography</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Bibliography</h1>
 
 <p>If you'd like to find out when new links are posted, subscribe to
 the <a href="https://spectrum-os.org/git/www/atom/bibliography.html">cgit
@@ -137,16 +122,3 @@ atom feed for this page</a>.
   <li><cite><a href="https://github.com/cloud-hypervisor/cloud-hypervisor">cloud-hypervisor</a></cite>
 
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/contributing.html b/Documentation/contributing.html
index ea85499..8f9948b 100644
--- a/Documentation/contributing.html
+++ b/Documentation/contributing.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Contributing to Spectrum
+nav_order: 3
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Contributing to Spectrum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Contributing to Spectrum</h1>
 
 <p>
 Thank you so much for your interest in contributing to Spectrum.
@@ -104,16 +89,3 @@ on <a href="/doc/contributing/communication.html#spectrum-discuss">spectrum-disc
 or in real time
 on <a href="/doc/contributing/communication.html#chat">Matrix or
 IRC</a>.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/design.html b/Documentation/design.html
index 51e0b77..0aa8762 100644
--- a/Documentation/design.html
+++ b/Documentation/design.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Design
+nav_order: 2
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum Design</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Spectrum Design</h1>
 
 <p>
 Spectrum will, for now, be a Linux-based system, with packages from
@@ -96,16 +81,3 @@ diverse range of hardware, to verify that the images correspond to the
 source code, and are free of tampering.  Work
 like <a href="https://nix-community.github.io/trustix/">Trustix</a>
 will be important to reaching this goal.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/doc/index.adoc b/Documentation/doc/index.adoc
index a24d85f..81b2a18 100644
--- a/Documentation/doc/index.adoc
+++ b/Documentation/doc/index.adoc
@@ -1,5 +1,6 @@
-= Spectrum Documentation
+= Documentation
 :page-liquid:
+:page-nav_order: 100
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/impressum.html b/Documentation/impressum.html
index b4806fe..416ce67 100644
--- a/Documentation/impressum.html
+++ b/Documentation/impressum.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Impressum
+lang: de
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="de">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Impressum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Impressum</h1>
 
 <address>
   <p>
@@ -32,13 +17,3 @@
   <p>
   hi@alyssa.is
 </address>
-
-<p lang="en">
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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>
diff --git a/Documentation/index.html b/Documentation/index.html
index 51685dd..6d6faf7 100644
--- a/Documentation/index.html
+++ b/Documentation/index.html
@@ -1,20 +1,12 @@
-<!doctype html>
+---
+layout: page
+title: Spectrum, a step towards usable secure computing
+no_heading: true
+nav_order: 0
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum, a step towards usable secure computing</title>
-
-<body>
 
 <a href="logo" style="float: left; margin: 0 1em 0.5em 0">
   <img class="logo" src="logo/logo_html.svg" width="70" height="70" alt="Spectrum logo">
@@ -95,16 +87,3 @@ initiative by the Digital Single Market of the European Commission.
     <li><a href="https://cryptpad.fr/kanban/#/2/kanban/view/yLtGXWLV6U7X5+Z1ay+oXKZMrSacqQe+51nXZYRh3ck/">Upstream bug/patch tracking</a>
   </ul>
 </nav>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/logo/index.html b/Documentation/logo/index.html
index 2354062..fbab443 100644
--- a/Documentation/logo/index.html
+++ b/Documentation/logo/index.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Logo
+nav_order: 1002
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo_html.svg">
-<link rel="stylesheet" href="../style.css">
-
-<title>Spectrum logo</title>
-
-<body>
-
-<nav>
-  <a href="..">Spectrum</a>
-</nav>
-
-<h1>Logo</h1>
 
 <p>
 <img class="logo" src="logo_html.svg" width="200" height="200" alt="" style="margin: 0 auto">
@@ -48,16 +33,3 @@ Mesh Gradients</a>.
   <li><a href="logo_mesh.svg" download>logo_mesh.svg</a> (for Inkscape)
 
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/motivation.html b/Documentation/motivation.html
index 4cbe5b0..e144251 100644
--- a/Documentation/motivation.html
+++ b/Documentation/motivation.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Motivation for Spectrum
+nav_order: 1
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Motivation for Spectrum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Motivation for Spectrum</h1>
 
 <p>
 Existing attempts to improve on the security of Unix-like operating
@@ -122,16 +107,3 @@ major security issue.
 
 <p>
 The last release of SubgraphOS was an alpha in 2017.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/software/cloud-hypervisor/index.html b/Documentation/software/cloud-hypervisor/index.html
index 1845068..9b4315c 100644
--- a/Documentation/software/cloud-hypervisor/index.html
+++ b/Documentation/software/cloud-hypervisor/index.html
@@ -1,26 +1,10 @@
-<!doctype html>
+---
+layout: page
+title: Cloud Hypervisor with virtio-gpu support
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="../../logo/logo_html.svg">
-<link rel="stylesheet" href="../../style.css">
-
-<title>Cloud Hypervisor with virtio-gpu support</title>
-
-<body>
-
-<nav>
-  <a href="../..">Spectrum</a>
-</nav>
-
-<h1>Cloud Hypervisor with virtio-gpu support</h1>
 
 <p>
 This is a patchset for <a href="https://cloudhypervisor.org/">Cloud
@@ -162,18 +146,3 @@ the <a href="mailto:discuss@spectrum-os.org">discuss@spectrum-os.org</a>
 list</a>, or ask in the
 Spectrum <a href="/doc/contributing/communication.html#chat">Matrix
 chat</a>.
-
-<hr>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../../impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/software/index.html b/Documentation/software/index.html
index 2a8a852..0265ca1 100644
--- a/Documentation/software/index.html
+++ b/Documentation/software/index.html
@@ -1,41 +1,13 @@
-<!doctype html>
+---
+layout: page
+title: Spectrum software
+nav_order: 10
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="../logo/logo_html.svg">
-<link rel="stylesheet" href="../style.css">
-
-<title>Spectrum software</title>
-
-<body>
-
-<nav>
-  <a href="..">Spectrum</a>
-</nav>
-
-<h1>Spectrum software</h1>
 
 <ul>
   <li><a href="cloud-hypervisor">Cloud Hypervisor with virtio-gpu
   support</a>
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../impressum.html" lang="de"><small>Impressum</small></a>
-- 
2.51.2


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* Re: [PATCH 2/3] Documentation: drop Just the Docs
  2026-06-08 16:49 ` [PATCH 2/3] Documentation: drop Just the Docs Valentin Gagarin
@ 2026-06-09 11:43   ` Alyssa Ross
  0 siblings, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-09 11:43 UTC (permalink / raw)
  To: Valentin Gagarin; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 634 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

> diff --git a/Documentation/doc/contributing/b4.adoc b/Documentation/doc/contributing/b4.adoc
> index 81f2519..3734c3a 100644
> --- a/Documentation/doc/contributing/b4.adoc
> +++ b/Documentation/doc/contributing/b4.adoc
> @@ -1,6 +1,4 @@
>  = Installing and Configuring b4
> -:page-parent: Working with Patches
> -:page-grand_parent: Contributing
>  :page-nav_order: 1
>  
>  // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>

Love that we get to drop all this silly metadata.

Reviewed-by: Alyssa Ross <hi@alyssa.is>
Tested-by: Alyssa Ross <hi@alyssa.is>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-08 16:49 ` [PATCH 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
@ 2026-06-09 11:45   ` Alyssa Ross
  2026-06-10 12:12     ` Valentin Gagarin
  0 siblings, 1 reply; 28+ messages in thread
From: Alyssa Ross @ 2026-06-09 11:45 UTC (permalink / raw)
  To: Valentin Gagarin; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 5927 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

> 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 %}

Is this right?  I see we have pages with descriptions, but when I look
at the sitemap I don't see any descriptions rendered.

> +      {%- 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>

This probably ought to be ommitted if the current page is /doc.
Otherwise I see "Spectrum / Documentation / Spectrum Documentation".

(Not a huge deal though — I see that it's fixed in patch #3.)

> diff --git a/Documentation/style.css b/Documentation/style.css
> index f4d4c4e..7f51a0a 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;

Something's off with your indentation here.

> +}
> +
> +.admonitionblock td {
> +	padding: 1rem;
> +  vertical-align: top;

And here.

> +}
> +
> +.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}

For consistency this should be:                                               ; }

New styles are looking lovely. :)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH 3/3] Documentation: uniform navigation across all pages
  2026-06-08 16:49 ` [PATCH 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
@ 2026-06-09 11:54   ` Alyssa Ross
  0 siblings, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-09 11:54 UTC (permalink / raw)
  To: Valentin Gagarin; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 3125 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

> - Render breadcrumb navigation for all pages
> - Use common page layout for hard-coded HTML pages
> - Sort hard-coded HTML into sitemap
> - Show link to source in the footer
>
> Signed-off-by: Valentin Gagarin <valentin@gagarin.work>

> diff --git a/Documentation/_includes/footer_custom.html b/Documentation/_includes/footer_custom.html
> index 2477920..c7ba518 100644
> --- a/Documentation/_includes/footer_custom.html
> +++ b/Documentation/_includes/footer_custom.html
> @@ -2,9 +2,6 @@
>  SPDX-FileCopyrightText: 2020 Alyssa Ross <hi@alyssa.is>
>  SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later
>  {% endcomment %}
> -<p>
> -<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
> -
>  <p>
>  <small>Permission is granted to copy, distribute and/or modify this
>  document under either the terms of the
> @@ -15,6 +12,7 @@ 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>
> +<p><small>
> +<a href="/sitemap.html">Sitemap</a>
> +<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
> +<a href="/impressum.html" lang="de">Impressum</a>

These links are getting a bit dense.  Maybe they could have some
separation between them?

> diff --git a/Documentation/_layouts/page.html b/Documentation/_layouts/page.html
> index 230b601..f2cf0f6 100644
> --- a/Documentation/_layouts/page.html
> +++ b/Documentation/_layouts/page.html
> @@ -3,7 +3,7 @@ SPDX-License-Identifier: GPL-3.0-or-later
>  SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
>  {% endcomment %}
>  <!doctype html>
> -<html lang="en">
> +<html lang="{{ page.lang | default: "en" }}">
>  
>  <head>
>  
> @@ -17,13 +17,10 @@ SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
>  
>  <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>
> +{% include breadcrumb.html %}
> +
> +{% assign ext = page.path | split: "." | last %}
> +{% if ext == "html" and page.no_heading != true %}<h1>{{ page.title }}</h1>{% endif %}

What's the extension check for?  Wouldn't checking no_heading be enough?

> diff --git a/Documentation/index.html b/Documentation/index.html
> index 51685dd..6d6faf7 100644
> --- a/Documentation/index.html
> +++ b/Documentation/index.html
> @@ -1,20 +1,12 @@
> -<!doctype html>
> +---
> +layout: page
> +title: Spectrum, a step towards usable secure computing
> +no_heading: true
> +nav_order: 0

Doesn't this page get excluded from the sitemap?  Why does it need to
have nav_order set?

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-09 11:45   ` Alyssa Ross
@ 2026-06-10 12:12     ` Valentin Gagarin
  2026-06-10 12:23       ` Alyssa Ross
  0 siblings, 1 reply; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-10 12:12 UTC (permalink / raw)
  To: Alyssa Ross; +Cc: devel

>> +<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>
> 
> This probably ought to be ommitted if the current page is /doc.
> Otherwise I see "Spectrum / Documentation / Spectrum Documentation".
> 
> (Not a huge deal though — I see that it's fixed in patch #3.)

This is a means to keep each change limited in scope.  The first patch 
effectively only adds a sitemap for the `doc` subdirectory.  You can of 
course squash everything, then it won't matter, but it then will be one 
huge diff.

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-10 12:12     ` Valentin Gagarin
@ 2026-06-10 12:23       ` Alyssa Ross
  0 siblings, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-10 12:23 UTC (permalink / raw)
  To: Valentin Gagarin; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 1082 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

>>> +<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>
>> 
>> This probably ought to be ommitted if the current page is /doc.
>> Otherwise I see "Spectrum / Documentation / Spectrum Documentation".
>> 
>> (Not a huge deal though — I see that it's fixed in patch #3.)
>
> This is a means to keep each change limited in scope.  The first patch 
> effectively only adds a sitemap for the `doc` subdirectory.  You can of 
> course squash everything, then it won't matter, but it then will be one 
> huge diff.

I just meant that it could have been avoided with something like the
following in this commit (untested), and then implemented properly in
the later patch, to avoid an intermediate state where it does the wrong
thing.

{- unless page.url == "/doc" -}
<li aria-current="page">{{ page.title }}</li>
{- endunless -}

As I said though, it's not a big deal.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

^ permalink raw reply	[flat|nested] 28+ messages in thread

* [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-08 16:49 [PATCH 0/3] Documentation: render all pages in one style Valentin Gagarin
                   ` (5 preceding siblings ...)
  2026-06-08 16:49 ` [PATCH 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
@ 2026-06-11  6:37 ` Valentin Gagarin
  2026-06-11  6:37   ` [PATCH v2 2/3] Documentation: drop Just the Docs Valentin Gagarin
                     ` (2 more replies)
  2026-06-16  9:35 ` [PATCH v3 0/3] Documentation: render all pages in one style Valentin Gagarin
  7 siblings, 3 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-11  6:37 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

- 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


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH v2 2/3] Documentation: drop Just the Docs
  2026-06-11  6:37 ` [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
@ 2026-06-11  6:37   ` Valentin Gagarin
  2026-06-11  6:37   ` [PATCH v2 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
  2026-06-12  8:27   ` [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website Alyssa Ross
  2 siblings, 0 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-11  6:37 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
---
 Documentation/Gemfile                         |  1 -
 Documentation/Gemfile.lock                    | 12 +-----
 Documentation/_config.yml                     |  7 ---
 Documentation/_includes/sitemap.html          |  2 +-
 Documentation/_includes/title.html            | 13 ------
 Documentation/_plugins/site_title_link.rb     | 10 -----
 Documentation/_sass/custom/custom.scss        | 43 -------------------
 Documentation/doc/about/architecture.adoc     |  1 -
 Documentation/doc/about/index.adoc            |  2 -
 Documentation/doc/about/requirements.adoc     |  1 -
 Documentation/doc/contributing/b4.adoc        |  2 -
 .../contributing/building-documentation.adoc  |  1 -
 .../doc/contributing/communication.adoc       |  2 -
 .../doc/contributing/first-patch.adoc         |  2 -
 Documentation/doc/contributing/index.adoc     |  2 -
 Documentation/doc/contributing/replying.adoc  |  2 -
 .../doc/contributing/reviewing-patches.adoc   |  2 -
 .../doc/contributing/testing-patches.adoc     |  2 -
 .../contributing/working-with-patches.adoc    |  2 -
 .../contributing/writing_documentation.adoc   |  5 +--
 .../decisions/001-host-update-mechanism.adoc  |  2 -
 .../doc/decisions/002-install-options.adoc    |  2 -
 .../doc/decisions/003-partitioning.adoc       |  2 -
 .../004-data-at-rest-encryption.adoc          |  2 -
 .../005-virtual-machine-monitor.adoc          |  2 -
 .../doc/decisions/006-drivers-on-host.adoc    |  2 -
 .../decisions/007-usb-virtual-machines.adoc   |  2 -
 ...008-inter-vm-communication-mechanisms.adoc |  2 -
 Documentation/doc/decisions/index.adoc        |  2 -
 .../doc/development/build-configuration.adoc  |  1 -
 .../doc/development/built-in-vms.adoc         |  1 -
 Documentation/doc/development/checks.adoc     |  1 -
 Documentation/doc/development/debugging.adoc  |  1 -
 Documentation/doc/development/index.adoc      |  2 -
 .../doc/development/persistent-storage.adoc   |  1 -
 Documentation/doc/development/release.adoc    |  1 -
 Documentation/doc/development/updates.adoc    |  1 -
 .../doc/development/uuid-reference.adoc       |  1 -
 Documentation/doc/index.adoc                  |  1 -
 .../doc/installation/binary-cache.adoc        |  1 -
 .../doc/installation/getting-spectrum.adoc    |  1 -
 Documentation/doc/installation/index.adoc     |  2 -
 .../using-spectrum/creating-custom-vms.adoc   |  1 -
 Documentation/doc/using-spectrum/index.adoc   |  2 -
 .../doc/using-spectrum/running-vms.adoc       |  1 -
 .../doc/using-spectrum/vm-file-access.adoc    |  1 -
 Documentation/gemset.nix                      | 33 --------------
 47 files changed, 3 insertions(+), 182 deletions(-)
 delete mode 100644 Documentation/_includes/title.html
 delete mode 100644 Documentation/_plugins/site_title_link.rb
 delete mode 100644 Documentation/_sass/custom/custom.scss

diff --git a/Documentation/Gemfile b/Documentation/Gemfile
index 3c3f59d..a6396da 100644
--- a/Documentation/Gemfile
+++ b/Documentation/Gemfile
@@ -6,4 +6,3 @@ source "https://rubygems.org"
 
 gem "jekyll"
 gem "jekyll-asciidoc"
-gem "just-the-docs", "~> 0.10.0"
diff --git a/Documentation/Gemfile.lock b/Documentation/Gemfile.lock
index e7b515e..992e6da 100644
--- a/Documentation/Gemfile.lock
+++ b/Documentation/Gemfile.lock
@@ -43,20 +43,11 @@ GEM
     jekyll-asciidoc (3.0.1)
       asciidoctor (>= 1.5.0, < 3.0.0)
       jekyll (>= 3.0.0)
-    jekyll-include-cache (0.2.1)
-      jekyll (>= 3.7, < 5.0)
     jekyll-sass-converter (3.1.0)
       sass-embedded (~> 1.75)
-    jekyll-seo-tag (2.8.0)
-      jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     json (2.13.0)
-    just-the-docs (0.10.1)
-      jekyll (>= 3.8.5)
-      jekyll-include-cache
-      jekyll-seo-tag (>= 2.0)
-      rake (>= 12.3.1)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
@@ -90,7 +81,6 @@ PLATFORMS
 DEPENDENCIES
   jekyll
   jekyll-asciidoc
-  just-the-docs (~> 0.10.0)
 
 BUNDLED WITH
-   2.6.9
+   2.7.2
diff --git a/Documentation/_config.yml b/Documentation/_config.yml
index b11c399..cc3e8ea 100644
--- a/Documentation/_config.yml
+++ b/Documentation/_config.yml
@@ -2,13 +2,6 @@
 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 ---
 title: Spectrum documentation
-logo: /logo/logo_html.svg
-theme: just-the-docs
-aux_links:
-  Home:
-    - /
-  Git:
-    - "https://spectrum-os.org/git/"
 plugins:
   - jekyll-asciidoc
 exclude:
diff --git a/Documentation/_includes/sitemap.html b/Documentation/_includes/sitemap.html
index cd493f8..0850a48 100644
--- a/Documentation/_includes/sitemap.html
+++ b/Documentation/_includes/sitemap.html
@@ -40,7 +40,7 @@ which we assume if it is constructed by a directory and contains an index file.
     {%- 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 %}
+      <a href="{{ p.url | relative_url }}">{{ p.title }}</a>
       {%- if is_section -%}
         {%- include sitemap.html prefix=p.url -%}
       {%- endif -%}
diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html
deleted file mode 100644
index 90ef71b..0000000
--- a/Documentation/_includes/title.html
+++ /dev/null
@@ -1,13 +0,0 @@
-{% comment %}
-SPDX-License-Identifier: MIT
-SPDX-FileCopyrightText: 2016 Patrick Marsceill
-SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-Override of: https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_includes/title.html
-{% endcomment %}
-{% if site.logo %}
-  <div class="site-logo" role="img" aria-label="{{ site.title }}"></div>
-{% endif %}
-{% if site.title %}
-  {{ site.title }}
-{% endif %}
diff --git a/Documentation/_plugins/site_title_link.rb b/Documentation/_plugins/site_title_link.rb
deleted file mode 100644
index 4095701..0000000
--- a/Documentation/_plugins/site_title_link.rb
+++ /dev/null
@@ -1,10 +0,0 @@
-# SPDX-License-Identifier: EUPL-1.2+
-# SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-# Just the Docs hardcodes the site header link to `/`.
-# https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_includes/components/sidebar.html#L14
-# Make it point to the docs root, not the top-level site.
-Jekyll::Hooks.register [:pages, :documents], :post_render do |item|
-  item.output.sub!('<a href="/" class="site-title',
-                   '<a href="/doc/" class="site-title')
-end
diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss
deleted file mode 100644
index 48b1d41..0000000
--- a/Documentation/_sass/custom/custom.scss
+++ /dev/null
@@ -1,43 +0,0 @@
-// SPDX-License-Identifier: MIT
-// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
-// SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-.main-content {
-	// Just the Docs puts titles next to definitions, rather than on
-	// the line before.  This makes the definitions too horizontally
-	// compressed.
-	dl {
-		display: block;
-	}
-	dt {
-		text-align: left;
-		font-weight: bold;
-
-		&::after {
-			content: none;
-		}
-	}
-	dd {
-		margin-left: 2ch;
-	}
-}
-
-// Make the logo and title fit the site header.
-.site-header {
-  .site-logo {
-    width: 3rem;
-  }
-
-  // Just the Docs displays a sidebar at the "medium size" `md` breakpoint and above.
-  // Use the upstream `mq` media query mixin to target that breakpoint.
-  // https://just-the-docs.com/docs/utilities/responsive-modifiers/
-  // https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_sass/support/mixins/_layout.scss#L3-L8
-  @include mq(md) {
-    .site-logo {
-      width: 5.5rem;
-    }
-    .site-title {
-      font-size: 1.25rem !important;
-    }
-  }
-}
diff --git a/Documentation/doc/about/architecture.adoc b/Documentation/doc/about/architecture.adoc
index 2b86616..bbc927d 100644
--- a/Documentation/doc/about/architecture.adoc
+++ b/Documentation/doc/about/architecture.adoc
@@ -1,5 +1,4 @@
 = Architecture
-:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/about/index.adoc b/Documentation/doc/about/index.adoc
index 6961b6a..019737f 100644
--- a/Documentation/doc/about/index.adoc
+++ b/Documentation/doc/about/index.adoc
@@ -1,7 +1,5 @@
 = About Spectrum
-:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum.
 :page-nav_order: 1
-:page-has_children: true
 
 // 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/about/requirements.adoc b/Documentation/doc/about/requirements.adoc
index 40f802f..6c32c31 100644
--- a/Documentation/doc/about/requirements.adoc
+++ b/Documentation/doc/about/requirements.adoc
@@ -1,5 +1,4 @@
 = Hardware and firmware requirements
-:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/contributing/b4.adoc b/Documentation/doc/contributing/b4.adoc
index 81f2519..3734c3a 100644
--- a/Documentation/doc/contributing/b4.adoc
+++ b/Documentation/doc/contributing/b4.adoc
@@ -1,6 +1,4 @@
 = Installing and Configuring b4
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/building-documentation.adoc b/Documentation/doc/contributing/building-documentation.adoc
index 919a021..b691d4d 100644
--- a/Documentation/doc/contributing/building-documentation.adoc
+++ b/Documentation/doc/contributing/building-documentation.adoc
@@ -1,5 +1,4 @@
 = Building Documentation
-:page-parent: Contributing
 :page-nav_order: 4
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/contributing/communication.adoc b/Documentation/doc/contributing/communication.adoc
index 874ad4e..987014e 100644
--- a/Documentation/doc/contributing/communication.adoc
+++ b/Documentation/doc/contributing/communication.adoc
@@ -1,7 +1,5 @@
 = Communication in Spectrum
-:description: Channels, announcements and so on.
 :page-nav_order: 1
-:page-parent: Contributing
 
 // SPDX-FileCopyrightText: 2019-2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2023 Unikie
diff --git a/Documentation/doc/contributing/first-patch.adoc b/Documentation/doc/contributing/first-patch.adoc
index 38326c0..2625888 100644
--- a/Documentation/doc/contributing/first-patch.adoc
+++ b/Documentation/doc/contributing/first-patch.adoc
@@ -1,6 +1,4 @@
 = Sending Your Patch
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/contributing/index.adoc b/Documentation/doc/contributing/index.adoc
index 5ae6811..04ff34a 100644
--- a/Documentation/doc/contributing/index.adoc
+++ b/Documentation/doc/contributing/index.adoc
@@ -1,7 +1,5 @@
 = Contributing
-:description: How to contribute changes to the Spectrum source repository.
 :page-nav_order: 5
-:page-has_children: true
 
 // SPDX-FileCopyrightText: 2023 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/contributing/replying.adoc b/Documentation/doc/contributing/replying.adoc
index c478afb..c6ec4b8 100644
--- a/Documentation/doc/contributing/replying.adoc
+++ b/Documentation/doc/contributing/replying.adoc
@@ -1,6 +1,4 @@
 = Replying to Messages in the Mailing List Archives
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/reviewing-patches.adoc b/Documentation/doc/contributing/reviewing-patches.adoc
index 0e73b0e..224e314 100644
--- a/Documentation/doc/contributing/reviewing-patches.adoc
+++ b/Documentation/doc/contributing/reviewing-patches.adoc
@@ -1,6 +1,4 @@
 = Reviewing Patches
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/testing-patches.adoc b/Documentation/doc/contributing/testing-patches.adoc
index d98b738..031855d 100644
--- a/Documentation/doc/contributing/testing-patches.adoc
+++ b/Documentation/doc/contributing/testing-patches.adoc
@@ -1,6 +1,4 @@
 = Testing Patches
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/working-with-patches.adoc b/Documentation/doc/contributing/working-with-patches.adoc
index 8e22343..6e1e83e 100644
--- a/Documentation/doc/contributing/working-with-patches.adoc
+++ b/Documentation/doc/contributing/working-with-patches.adoc
@@ -1,7 +1,5 @@
 = Working with Patches
-:page-parent: Contributing
 :page-nav_order: 2
-:page-has_children: true
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-FileCopyrightText: 2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/writing_documentation.adoc b/Documentation/doc/contributing/writing_documentation.adoc
index cb09241..d61f0bd 100644
--- a/Documentation/doc/contributing/writing_documentation.adoc
+++ b/Documentation/doc/contributing/writing_documentation.adoc
@@ -1,7 +1,5 @@
 = Documentation Style Guide
-:description: Channels, announcements and so on.
 :page-nav_order: 3
-:page-parent: Contributing
 
 // SPDX-FileCopyrightText: 2023 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -12,7 +10,7 @@ Please follow these guidelines and conventions
 when editing the documentation.
 
 We use https://nixos.org/manual/nix/stable/introduction.html[Nix] and
-https://github.com/just-the-docs/just-the-docs[Just the Docs] for
+https://jekyllrb.com/[Jekyll] for
 building the documentation. Sources are written in AsciiDoc If you are
 new with it, see
 https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation].
@@ -42,7 +40,6 @@ to suit your changing needs.
 include your name and a revision line following the author line. Example:
 
     = Document Title
-    :description: Some words about the content.
     Author Name <author@example.org>
     v1.0, 2012-02-10
     //empty line that ends the document header
diff --git a/Documentation/doc/decisions/001-host-update-mechanism.adoc b/Documentation/doc/decisions/001-host-update-mechanism.adoc
index 39f9f28..d0ab341 100644
--- a/Documentation/doc/decisions/001-host-update-mechanism.adoc
+++ b/Documentation/doc/decisions/001-host-update-mechanism.adoc
@@ -1,6 +1,4 @@
 = 001 Host Update Mechanism
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/002-install-options.adoc b/Documentation/doc/decisions/002-install-options.adoc
index 4a745eb..f56a626 100644
--- a/Documentation/doc/decisions/002-install-options.adoc
+++ b/Documentation/doc/decisions/002-install-options.adoc
@@ -1,6 +1,4 @@
 = 002 Install Options
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/003-partitioning.adoc b/Documentation/doc/decisions/003-partitioning.adoc
index 8e538c3..39f0ee2 100644
--- a/Documentation/doc/decisions/003-partitioning.adoc
+++ b/Documentation/doc/decisions/003-partitioning.adoc
@@ -1,6 +1,4 @@
 = 003 Partitioning
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/004-data-at-rest-encryption.adoc b/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
index 5b0f518..8f4d430 100644
--- a/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
+++ b/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
@@ -1,6 +1,4 @@
 = 004 Data at Rest Encryption
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/005-virtual-machine-monitor.adoc b/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
index 8a66c08..1ead8e1 100644
--- a/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
+++ b/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
@@ -1,6 +1,4 @@
 = 005 Virtual Machine Monitor
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/006-drivers-on-host.adoc b/Documentation/doc/decisions/006-drivers-on-host.adoc
index b92d863..ce7a072 100644
--- a/Documentation/doc/decisions/006-drivers-on-host.adoc
+++ b/Documentation/doc/decisions/006-drivers-on-host.adoc
@@ -1,6 +1,4 @@
 = 006 Drivers on Host
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/007-usb-virtual-machines.adoc b/Documentation/doc/decisions/007-usb-virtual-machines.adoc
index d832691..f494537 100644
--- a/Documentation/doc/decisions/007-usb-virtual-machines.adoc
+++ b/Documentation/doc/decisions/007-usb-virtual-machines.adoc
@@ -1,6 +1,4 @@
 = 007 USB Virtual Machine
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
index c1e5b87..4dec40e 100644
--- a/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
+++ b/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
@@ -1,6 +1,4 @@
 = 008 Inter-VM Communication Mechanisms
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/index.adoc b/Documentation/doc/decisions/index.adoc
index a022239..8a5d237 100644
--- a/Documentation/doc/decisions/index.adoc
+++ b/Documentation/doc/decisions/index.adoc
@@ -1,6 +1,4 @@
 = Architecture Decision Records
-:page-has_children: true
-:page-parent: About Spectrum
 
 // 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/development/build-configuration.adoc b/Documentation/doc/development/build-configuration.adoc
index 49651d0..af7b9fa 100644
--- a/Documentation/doc/development/build-configuration.adoc
+++ b/Documentation/doc/development/build-configuration.adoc
@@ -1,5 +1,4 @@
 = Configuring the Build
-:page-parent: Development
 :page-nav_order: 1
 :example-caption: Test
 
diff --git a/Documentation/doc/development/built-in-vms.adoc b/Documentation/doc/development/built-in-vms.adoc
index d044e75..fdb5f15 100644
--- a/Documentation/doc/development/built-in-vms.adoc
+++ b/Documentation/doc/development/built-in-vms.adoc
@@ -1,5 +1,4 @@
 = Developing Built-in Application VMs
-:page-parent: Development
 :page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2023-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/checks.adoc b/Documentation/doc/development/checks.adoc
index 905d5b8..64463cc 100644
--- a/Documentation/doc/development/checks.adoc
+++ b/Documentation/doc/development/checks.adoc
@@ -1,5 +1,4 @@
 = Checks
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/debugging.adoc b/Documentation/doc/development/debugging.adoc
index f1bbf01..39fd989 100644
--- a/Documentation/doc/development/debugging.adoc
+++ b/Documentation/doc/development/debugging.adoc
@@ -1,5 +1,4 @@
 = Debugging
-:page-parent: Development
 :page-nav_order: 4
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/index.adoc b/Documentation/doc/development/index.adoc
index 4e50425..a52c593 100644
--- a/Documentation/doc/development/index.adoc
+++ b/Documentation/doc/development/index.adoc
@@ -1,7 +1,5 @@
 = Development
-:description: Development progress, general development practices
 :page-nav_order: 4
-:page-has_children: true
 
 // 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/development/persistent-storage.adoc b/Documentation/doc/development/persistent-storage.adoc
index c4bcc16..e3db767 100644
--- a/Documentation/doc/development/persistent-storage.adoc
+++ b/Documentation/doc/development/persistent-storage.adoc
@@ -1,5 +1,4 @@
 = Persistent storage
-:page-parent: Development
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/release.adoc b/Documentation/doc/development/release.adoc
index 4ecbf03..2ab9d88 100644
--- a/Documentation/doc/development/release.adoc
+++ b/Documentation/doc/development/release.adoc
@@ -1,5 +1,4 @@
 = Release Builds
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/updates.adoc b/Documentation/doc/development/updates.adoc
index 8746f97..1ec08c2 100644
--- a/Documentation/doc/development/updates.adoc
+++ b/Documentation/doc/development/updates.adoc
@@ -1,5 +1,4 @@
 = Updating the OS
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2025 Demi Marie Obenour <demiobenour@gmail.com>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/uuid-reference.adoc b/Documentation/doc/development/uuid-reference.adoc
index 16279c8..21c8935 100644
--- a/Documentation/doc/development/uuid-reference.adoc
+++ b/Documentation/doc/development/uuid-reference.adoc
@@ -1,5 +1,4 @@
 = UUID Reference
-:page-parent: Development
 :page-nav_order: 6
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/index.adoc b/Documentation/doc/index.adoc
index 3bf3934..a24d85f 100644
--- a/Documentation/doc/index.adoc
+++ b/Documentation/doc/index.adoc
@@ -1,5 +1,4 @@
 = Spectrum Documentation
-:page-nav_exclude: true
 :page-liquid:
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/binary-cache.adoc b/Documentation/doc/installation/binary-cache.adoc
index 4feaad4..105e09d 100644
--- a/Documentation/doc/installation/binary-cache.adoc
+++ b/Documentation/doc/installation/binary-cache.adoc
@@ -1,5 +1,4 @@
 = Setting Up Binary Cache
-:page-parent: Build and Run
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022-2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/getting-spectrum.adoc b/Documentation/doc/installation/getting-spectrum.adoc
index 22c1fe3..478b1fc 100644
--- a/Documentation/doc/installation/getting-spectrum.adoc
+++ b/Documentation/doc/installation/getting-spectrum.adoc
@@ -1,5 +1,4 @@
 = Getting Spectrum
-:page-parent: Build and Run
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022-2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/index.adoc b/Documentation/doc/installation/index.adoc
index d1df2ed..225abc6 100644
--- a/Documentation/doc/installation/index.adoc
+++ b/Documentation/doc/installation/index.adoc
@@ -1,7 +1,5 @@
 = Build and Run
-:description: How to download and install Spectrum OS.
 :page-nav_order: 2
-:page-has_children: true
 :page-has_toc: false
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/creating-custom-vms.adoc b/Documentation/doc/using-spectrum/creating-custom-vms.adoc
index 68213c8..5b74084 100644
--- a/Documentation/doc/using-spectrum/creating-custom-vms.adoc
+++ b/Documentation/doc/using-spectrum/creating-custom-vms.adoc
@@ -1,5 +1,4 @@
 = Creating Custom VMs
-:page-parent: Using Spectrum
 
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/index.adoc b/Documentation/doc/using-spectrum/index.adoc
index 25347a4..9571b50 100644
--- a/Documentation/doc/using-spectrum/index.adoc
+++ b/Documentation/doc/using-spectrum/index.adoc
@@ -1,7 +1,5 @@
 = Using Spectrum
-:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth).
 :page-nav_order: 3
-:page-has_children: true
 :page-has_toc: false
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/running-vms.adoc b/Documentation/doc/using-spectrum/running-vms.adoc
index 2b47fc0..d8a7732 100644
--- a/Documentation/doc/using-spectrum/running-vms.adoc
+++ b/Documentation/doc/using-spectrum/running-vms.adoc
@@ -1,5 +1,4 @@
 = Running VMs
-:page-parent: Using Spectrum
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/using-spectrum/vm-file-access.adoc b/Documentation/doc/using-spectrum/vm-file-access.adoc
index 6189233..d4276d4 100644
--- a/Documentation/doc/using-spectrum/vm-file-access.adoc
+++ b/Documentation/doc/using-spectrum/vm-file-access.adoc
@@ -1,5 +1,4 @@
 = VM File Access
-:page-parent: Using Spectrum
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/gemset.nix b/Documentation/gemset.nix
index 7b85a7f..b31a35e 100644
--- a/Documentation/gemset.nix
+++ b/Documentation/gemset.nix
@@ -165,17 +165,6 @@
     };
     version = "3.0.1";
   };
-  jekyll-include-cache = {
-    dependencies = ["jekyll"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "01d2l6qrmjc42664ns83cv36jbvalcxqbkmj5i22fakka7jvkm67";
-      type = "gem";
-    };
-    version = "0.2.1";
-  };
   jekyll-sass-converter = {
     dependencies = ["sass-embedded"];
     groups = ["default"];
@@ -187,17 +176,6 @@
     };
     version = "3.1.0";
   };
-  jekyll-seo-tag = {
-    dependencies = ["jekyll"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "0638mqhqynghnlnaz0xi1kvnv53wkggaq94flfzlxwandn8x2biz";
-      type = "gem";
-    };
-    version = "2.8.0";
-  };
   jekyll-watch = {
     dependencies = ["listen"];
     groups = ["default"];
@@ -219,17 +197,6 @@
     };
     version = "2.13.0";
   };
-  just-the-docs = {
-    dependencies = ["jekyll" "jekyll-include-cache" "jekyll-seo-tag" "rake"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "0y2mvzg2vxb4lk1rfay8d405qij4ifa65ypz09qj0945wf6qgsmw";
-      type = "gem";
-    };
-    version = "0.10.1";
-  };
   kramdown = {
     dependencies = ["rexml"];
     groups = ["default"];
-- 
2.51.2


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH v2 3/3] Documentation: uniform navigation across all pages
  2026-06-11  6:37 ` [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
  2026-06-11  6:37   ` [PATCH v2 2/3] Documentation: drop Just the Docs Valentin Gagarin
@ 2026-06-11  6:37   ` Valentin Gagarin
  2026-06-12  8:44     ` Alyssa Ross
  2026-06-12  8:27   ` [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website Alyssa Ross
  2 siblings, 1 reply; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-11  6:37 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

- Render breadcrumb navigation for all pages
- Use common page layout for hard-coded HTML pages
- Sort hard-coded HTML into sitemap
- Show link to source in the footer

Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
---
 Documentation/_includes/breadcrumb.html       | 23 +++++++++++
 Documentation/_includes/footer_custom.html    | 12 +++---
 Documentation/_includes/sitemap.html          |  7 +++-
 Documentation/_layouts/page.html              | 13 +++----
 Documentation/bibliography.html               | 38 +++---------------
 Documentation/contributing.html               | 38 +++---------------
 Documentation/design.html                     | 38 +++---------------
 Documentation/doc/index.adoc                  |  3 +-
 Documentation/impressum.html                  | 35 +++--------------
 Documentation/index.html                      | 33 +++-------------
 Documentation/logo/index.html                 | 38 +++---------------
 Documentation/motivation.html                 | 38 +++---------------
 .../software/cloud-hypervisor/index.html      | 39 ++-----------------
 Documentation/software/index.html             | 38 +++---------------
 14 files changed, 87 insertions(+), 306 deletions(-)
 create mode 100644 Documentation/_includes/breadcrumb.html

diff --git a/Documentation/_includes/breadcrumb.html b/Documentation/_includes/breadcrumb.html
new file mode 100644
index 0000000..f759807
--- /dev/null
+++ b/Documentation/_includes/breadcrumb.html
@@ -0,0 +1,23 @@
+{% comment %}
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
+{% endcomment %}
+{%- unless page.url == '/' -%}
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Spectrum</a></li>
+    {%- assign parts = page.url | split: '/' -%}
+    {%- assign acc = '' -%}
+    {%- for part in parts offset: 1 -%}
+      {%- assign acc = acc | append: '/' | append: part -%}
+      {%- assign parent_url = acc | append: '/' -%}
+      {%- if parent_url == page.url -%}{%- continue -%}{%- endif -%}
+      {%- assign parent = site.pages | where: 'url', parent_url | first -%}
+      {%- if parent %}
+    <li><a href="{{ parent.url }}">{{ parent.title }}</a></li>
+      {%- endif -%}
+    {%- endfor %}
+    <li aria-current="page">{{ page.title }}</li>
+  </ol>
+</nav>
+{%- endunless -%}
diff --git a/Documentation/_includes/footer_custom.html b/Documentation/_includes/footer_custom.html
index 2477920..db29f82 100644
--- a/Documentation/_includes/footer_custom.html
+++ b/Documentation/_includes/footer_custom.html
@@ -2,9 +2,6 @@
 SPDX-FileCopyrightText: 2020 Alyssa Ross <hi@alyssa.is>
 SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later
 {% endcomment %}
-<p>
-<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
-
 <p>
 <small>Permission is granted to copy, distribute and/or modify this
 document under either the terms of the
@@ -15,6 +12,9 @@ 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>
+<p><small>
+<a href="/sitemap.html">Sitemap</a>
+·
+<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
+·
+<a href="/impressum.html" lang="de">Impressum</a>
diff --git a/Documentation/_includes/sitemap.html b/Documentation/_includes/sitemap.html
index 0850a48..51c5bb0 100644
--- a/Documentation/_includes/sitemap.html
+++ b/Documentation/_includes/sitemap.html
@@ -18,6 +18,10 @@ which we assume if it is constructed by a directory and contains an index file.
   {%- assign candidates = site.html_pages
         | where_exp: "p", "p.url contains prefix"
         | where_exp: "p", "p.url != prefix" -%}
+  {%- if prefix == default_root -%}
+    {%- assign list_with_root_page = site.html_pages | where: "url", prefix -%}
+    {%- assign candidates = list_with_root_page | concat: candidates -%}
+  {%- endif -%}
   {%- comment %}
   Ordered pages first, ascending.  The rest after, in URL order, so output is deterministic.
   {%- endcomment %}
@@ -33,9 +37,10 @@ which we assume if it is constructed by a directory and contains an index file.
     {%- 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 -%}
+    {%- if p.name == "index.adoc" or p.name == "index.html" -%}{%- assign is_index = true -%}{%- endif -%}
     {%- assign is_page = false -%}
     {%- if is_index == false and slashes == 0 -%}{%- assign is_page = true -%}{%- endif -%}
+    {%- if is_index and suffix == "" -%}{%- 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 %}
diff --git a/Documentation/_layouts/page.html b/Documentation/_layouts/page.html
index 230b601..f2cf0f6 100644
--- a/Documentation/_layouts/page.html
+++ b/Documentation/_layouts/page.html
@@ -3,7 +3,7 @@ SPDX-License-Identifier: GPL-3.0-or-later
 SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 {% endcomment %}
 <!doctype html>
-<html lang="en">
+<html lang="{{ page.lang | default: "en" }}">
 
 <head>
 
@@ -17,13 +17,10 @@ SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 
 <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>
+{% include breadcrumb.html %}
+
+{% assign ext = page.path | split: "." | last %}
+{% if ext == "html" and page.no_heading != true %}<h1>{{ page.title }}</h1>{% endif %}
 
 {{ content }}
 
diff --git a/Documentation/bibliography.html b/Documentation/bibliography.html
index f9a8efd..175115a 100644
--- a/Documentation/bibliography.html
+++ b/Documentation/bibliography.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Bibliography
+nav_order: 200
+---
 <!-- SPDX-FileCopyrightText: 2019-2023 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum Bibliography</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Bibliography</h1>
 
 <p>If you'd like to find out when new links are posted, subscribe to
 the <a href="https://spectrum-os.org/git/www/atom/bibliography.html">cgit
@@ -137,16 +122,3 @@ atom feed for this page</a>.
   <li><cite><a href="https://github.com/cloud-hypervisor/cloud-hypervisor">cloud-hypervisor</a></cite>
 
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/contributing.html b/Documentation/contributing.html
index e1835df..6e5fc00 100644
--- a/Documentation/contributing.html
+++ b/Documentation/contributing.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Contributing to Spectrum
+nav_order: 10
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Contributing to Spectrum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Contributing to Spectrum</h1>
 
 <p>
 Thank you so much for your interest in contributing to Spectrum.
@@ -104,16 +89,3 @@ on <a href="/doc/contributing/communication.html#spectrum-discuss">spectrum-disc
 or in real time
 on <a href="/doc/contributing/communication.html#chat">Matrix or
 IRC</a>.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/design.html b/Documentation/design.html
index 51e0b77..0aa8762 100644
--- a/Documentation/design.html
+++ b/Documentation/design.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Design
+nav_order: 2
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum Design</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Spectrum Design</h1>
 
 <p>
 Spectrum will, for now, be a Linux-based system, with packages from
@@ -96,16 +81,3 @@ diverse range of hardware, to verify that the images correspond to the
 source code, and are free of tampering.  Work
 like <a href="https://nix-community.github.io/trustix/">Trustix</a>
 will be important to reaching this goal.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/doc/index.adoc b/Documentation/doc/index.adoc
index a24d85f..81b2a18 100644
--- a/Documentation/doc/index.adoc
+++ b/Documentation/doc/index.adoc
@@ -1,5 +1,6 @@
-= Spectrum Documentation
+= Documentation
 :page-liquid:
+:page-nav_order: 100
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/impressum.html b/Documentation/impressum.html
index b4806fe..416ce67 100644
--- a/Documentation/impressum.html
+++ b/Documentation/impressum.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Impressum
+lang: de
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="de">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Impressum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Impressum</h1>
 
 <address>
   <p>
@@ -32,13 +17,3 @@
   <p>
   hi@alyssa.is
 </address>
-
-<p lang="en">
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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>
diff --git a/Documentation/index.html b/Documentation/index.html
index 51685dd..6d6faf7 100644
--- a/Documentation/index.html
+++ b/Documentation/index.html
@@ -1,20 +1,12 @@
-<!doctype html>
+---
+layout: page
+title: Spectrum, a step towards usable secure computing
+no_heading: true
+nav_order: 0
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum, a step towards usable secure computing</title>
-
-<body>
 
 <a href="logo" style="float: left; margin: 0 1em 0.5em 0">
   <img class="logo" src="logo/logo_html.svg" width="70" height="70" alt="Spectrum logo">
@@ -95,16 +87,3 @@ initiative by the Digital Single Market of the European Commission.
     <li><a href="https://cryptpad.fr/kanban/#/2/kanban/view/yLtGXWLV6U7X5+Z1ay+oXKZMrSacqQe+51nXZYRh3ck/">Upstream bug/patch tracking</a>
   </ul>
 </nav>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/logo/index.html b/Documentation/logo/index.html
index 2354062..fbab443 100644
--- a/Documentation/logo/index.html
+++ b/Documentation/logo/index.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Logo
+nav_order: 1002
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo_html.svg">
-<link rel="stylesheet" href="../style.css">
-
-<title>Spectrum logo</title>
-
-<body>
-
-<nav>
-  <a href="..">Spectrum</a>
-</nav>
-
-<h1>Logo</h1>
 
 <p>
 <img class="logo" src="logo_html.svg" width="200" height="200" alt="" style="margin: 0 auto">
@@ -48,16 +33,3 @@ Mesh Gradients</a>.
   <li><a href="logo_mesh.svg" download>logo_mesh.svg</a> (for Inkscape)
 
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/motivation.html b/Documentation/motivation.html
index 4cbe5b0..e144251 100644
--- a/Documentation/motivation.html
+++ b/Documentation/motivation.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Motivation for Spectrum
+nav_order: 1
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Motivation for Spectrum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Motivation for Spectrum</h1>
 
 <p>
 Existing attempts to improve on the security of Unix-like operating
@@ -122,16 +107,3 @@ major security issue.
 
 <p>
 The last release of SubgraphOS was an alpha in 2017.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/software/cloud-hypervisor/index.html b/Documentation/software/cloud-hypervisor/index.html
index 1845068..9b4315c 100644
--- a/Documentation/software/cloud-hypervisor/index.html
+++ b/Documentation/software/cloud-hypervisor/index.html
@@ -1,26 +1,10 @@
-<!doctype html>
+---
+layout: page
+title: Cloud Hypervisor with virtio-gpu support
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="../../logo/logo_html.svg">
-<link rel="stylesheet" href="../../style.css">
-
-<title>Cloud Hypervisor with virtio-gpu support</title>
-
-<body>
-
-<nav>
-  <a href="../..">Spectrum</a>
-</nav>
-
-<h1>Cloud Hypervisor with virtio-gpu support</h1>
 
 <p>
 This is a patchset for <a href="https://cloudhypervisor.org/">Cloud
@@ -162,18 +146,3 @@ the <a href="mailto:discuss@spectrum-os.org">discuss@spectrum-os.org</a>
 list</a>, or ask in the
 Spectrum <a href="/doc/contributing/communication.html#chat">Matrix
 chat</a>.
-
-<hr>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../../impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/software/index.html b/Documentation/software/index.html
index 2a8a852..8b95c2d 100644
--- a/Documentation/software/index.html
+++ b/Documentation/software/index.html
@@ -1,41 +1,13 @@
-<!doctype html>
+---
+layout: page
+title: Spectrum software
+nav_order: 3
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="../logo/logo_html.svg">
-<link rel="stylesheet" href="../style.css">
-
-<title>Spectrum software</title>
-
-<body>
-
-<nav>
-  <a href="..">Spectrum</a>
-</nav>
-
-<h1>Spectrum software</h1>
 
 <ul>
   <li><a href="cloud-hypervisor">Cloud Hypervisor with virtio-gpu
   support</a>
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../impressum.html" lang="de"><small>Impressum</small></a>
-- 
2.51.2


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* Re: [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-11  6:37 ` [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
  2026-06-11  6:37   ` [PATCH v2 2/3] Documentation: drop Just the Docs Valentin Gagarin
  2026-06-11  6:37   ` [PATCH v2 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
@ 2026-06-12  8:27   ` Alyssa Ross
  2 siblings, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-12  8:27 UTC (permalink / raw)
  To: Valentin Gagarin; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 3118 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

> 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" -%}

I overlooked this last time — what if "prefix" is e.g. a suffix of
"p.url"?  Would the false positive be a problem?

> +  {%- 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 %}

Thank you for fighting this uninspiring language on our behalf. :)

> +    {%- 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 %}

Description rendering here still doesn't work, but I see the next patch
removes the description part here.  That should be part of this patch
instead so we don't add functionality and then immediately remove it.  I
can make that shift when applying if there are no other changes needed
(which depends on the answer to my question above).

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH v2 3/3] Documentation: uniform navigation across all pages
  2026-06-11  6:37   ` [PATCH v2 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
@ 2026-06-12  8:44     ` Alyssa Ross
  0 siblings, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-12  8:44 UTC (permalink / raw)
  To: Valentin Gagarin; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 2966 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

> diff --git a/Documentation/_includes/footer_custom.html b/Documentation/_includes/footer_custom.html
> index 2477920..db29f82 100644
> --- a/Documentation/_includes/footer_custom.html
> +++ b/Documentation/_includes/footer_custom.html
> @@ -2,9 +2,6 @@
>  SPDX-FileCopyrightText: 2020 Alyssa Ross <hi@alyssa.is>
>  SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later
>  {% endcomment %}
> -<p>
> -<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
> -
>  <p>
>  <small>Permission is granted to copy, distribute and/or modify this
>  document under either the terms of the
> @@ -15,6 +12,9 @@ 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>
> +<p><small>
> +<a href="/sitemap.html">Sitemap</a>
> +·
> +<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
> +·
> +<a href="/impressum.html" lang="de">Impressum</a>

Needs a </small> here — it's not optional like </p> is per the spec.
I can fix when applying if no other changes are needed.

https://html.spec.whatwg.org/multipage/syntax.html#optional-tags

(When I was writing the website content originally I liked that omitting
the </p> tags helped keep the source clean, but it's an obscure HTML
feature other contributors are unlikely to be familiar with, so I
wouldn't object to changing to avoiding tag omissions even where
permitted by spec.)

> diff --git a/Documentation/_layouts/page.html b/Documentation/_layouts/page.html
> index 230b601..f2cf0f6 100644
> --- a/Documentation/_layouts/page.html
> +++ b/Documentation/_layouts/page.html
> @@ -3,7 +3,7 @@ SPDX-License-Identifier: GPL-3.0-or-later
>  SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
>  {% endcomment %}
>  <!doctype html>
> -<html lang="en">
> +<html lang="{{ page.lang | default: "en" }}">
>  
>  <head>
>  
> @@ -17,13 +17,10 @@ SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
>  
>  <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>
> +{% include breadcrumb.html %}
> +
> +{% assign ext = page.path | split: "." | last %}
> +{% if ext == "html" and page.no_heading != true %}<h1>{{ page.title }}</h1>{% endif %}

Ah, I've figured out the answer to my own question from last time.
AsciiDoctor renders page titles as h1, so without the extension check it
would be duplicated here.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

^ permalink raw reply	[flat|nested] 28+ messages in thread

* [PATCH v3 0/3] Documentation: render all pages in one style
  2026-06-08 16:49 [PATCH 0/3] Documentation: render all pages in one style Valentin Gagarin
                   ` (6 preceding siblings ...)
  2026-06-11  6:37 ` [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
@ 2026-06-16  9:35 ` Valentin Gagarin
  2026-06-16  9:35   ` [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
                     ` (3 more replies)
  7 siblings, 4 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-16  9:35 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

After some out-of-band discussion I decided to make the navigation
structure more literal.  That has the advantage of being slightly less
source code and slightly smaller output, but more importantly it seems
to degrade more gracefully and less noisily for limited clients, such as
screen readers and text browsers.

Since the overall change is really large and the changes may be hard to
spot, here's the diff against v2.

diff --git a/Documentation/_includes/breadcrumb.html b/Documentation/_includes/breadcrumb.html
index f759807..3b93128 100644
--- a/Documentation/_includes/breadcrumb.html
+++ b/Documentation/_includes/breadcrumb.html
@@ -4,20 +4,18 @@ SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 {% endcomment %}
 {%- unless page.url == '/' -%}
 <nav aria-label="Breadcrumb">
-  <ol>
-    <li><a href="/">Spectrum</a></li>
-    {%- assign parts = page.url | split: '/' -%}
-    {%- assign acc = '' -%}
-    {%- for part in parts offset: 1 -%}
-      {%- assign acc = acc | append: '/' | append: part -%}
-      {%- assign parent_url = acc | append: '/' -%}
-      {%- if parent_url == page.url -%}{%- continue -%}{%- endif -%}
-      {%- assign parent = site.pages | where: 'url', parent_url | first -%}
-      {%- if parent %}
-    <li><a href="{{ parent.url }}">{{ parent.title }}</a></li>
-      {%- endif -%}
-    {%- endfor %}
-    <li aria-current="page">{{ page.title }}</li>
-  </ol>
+  <a href="/">Spectrum</a>
+  {%- assign parts = page.url | split: '/' -%}
+  {%- assign acc = '' -%}
+  {%- for part in parts offset: 1 -%}
+    {%- assign acc = acc | append: '/' | append: part -%}
+    {%- assign parent_url = acc | append: '/' -%}
+    {%- if parent_url == page.url -%}{%- continue -%}{%- endif -%}
+    {%- assign parent = site.pages | where: 'url', parent_url | first -%}
+    {%- if parent %}
+    / <a href="{{ parent.url }}">{{ parent.title }}</a>
+    {%- endif -%}
+  {%- endfor %}
+  / <span aria-current="page">{{ page.title }}</span>
 </nav>
 {%- endunless -%}
diff --git a/Documentation/_includes/footer_custom.html b/Documentation/_includes/footer.html
similarity index 82%
rename from Documentation/_includes/footer_custom.html
rename to Documentation/_includes/footer.html
index db29f82..d0e2c0b 100644
--- a/Documentation/_includes/footer_custom.html
+++ b/Documentation/_includes/footer.html
@@ -3,18 +3,19 @@ SPDX-FileCopyrightText: 2020 Alyssa Ross <hi@alyssa.is>
 SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later
 {% endcomment %}
 <p>
-<small>Permission is granted to copy, distribute and/or modify this
+Permission is granted to copy, distribute and/or modify this
 document under either the terms of the
 <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
 Commons Attribution-ShareAlike 4.0 International License</a>, or the
 <a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
 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>
+Front-Cover Texts, and no Back-Cover Texts.
 
-<p><small>
+<nav aria-label="Footer">
 <a href="/sitemap.html">Sitemap</a>
-·
+&middot;
 <a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
-·
+&middot;
 <a href="/impressum.html" lang="de">Impressum</a>
+</nav>
diff --git a/Documentation/_includes/sitemap.html b/Documentation/_includes/sitemap.html
index 51c5bb0..26e96ec 100644
--- a/Documentation/_includes/sitemap.html
+++ b/Documentation/_includes/sitemap.html
@@ -33,7 +33,9 @@ which we assume if it is constructed by a directory and contains an index file.
     `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 url_start = p.url | slice: 0, prefix.size -%}
+    {%- if url_start == prefix -%}
+    {%- assign suffix = p.url | slice: prefix.size, p.url.size -%}
     {%- assign without_slashes = suffix | replace: "/", "" -%}
     {%- assign slashes = suffix.size | minus: without_slashes.size -%}
     {%- assign is_index = false -%}
@@ -51,6 +53,7 @@ which we assume if it is constructed by a directory and contains an index file.
       {%- endif -%}
     </li>
     {%- endif -%}
+    {%- endif -%}
   {%- endfor -%}
 {%- endcapture -%}
 {%- assign trimmed = inner | strip -%}
diff --git a/Documentation/_layouts/page.html b/Documentation/_layouts/page.html
index f2cf0f6..4eba50d 100644
--- a/Documentation/_layouts/page.html
+++ b/Documentation/_layouts/page.html
@@ -24,5 +24,5 @@ SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 
 {{ content }}
 
-{% include footer_custom.html %}
+{% include footer.html %}
 </html>
diff --git a/Documentation/contributing.html b/Documentation/contributing.html
index 6e5fc00..9bb21d8 100644
--- a/Documentation/contributing.html
+++ b/Documentation/contributing.html
@@ -22,8 +22,8 @@ If you're interested in contributing code to Spectrum, you
 can <a href="https://spectrum-os.org/git/">find</a> the source
 repositories online.
 
-If you've made changes you'd like to be included
-in the official Spectrum distribution, please send patches to the
+If you've made changes you'd like to be included in the official
+Spectrum distribution, please send patches to the
 spectrum-devel <a href="https://lists.spectrum-os.org/mailman3/lists/devel.spectrum-os.org/">
 mailing list</a>
 (<a href="mailto:devel@spectrum-os.org">devel@spectrum-os.org</a>).
diff --git a/Documentation/style.css b/Documentation/style.css
index 44060b3..ae617c5 100644
--- a/Documentation/style.css
+++ b/Documentation/style.css
@@ -26,16 +26,8 @@ var {
     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;
+footer {
+	font-size: small;
 }
 
 :root {

-- 
2.54.0


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-16  9:35 ` [PATCH v3 0/3] Documentation: render all pages in one style Valentin Gagarin
@ 2026-06-16  9:35   ` Valentin Gagarin
  2026-06-16 11:49     ` Alyssa Ross
  2026-06-17 10:48     ` Alyssa Ross
  2026-06-16  9:35   ` [PATCH v3 2/3] Documentation: drop Just the Docs Valentin Gagarin
                     ` (2 subsequent siblings)
  3 siblings, 2 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-16  9:35 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

- 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    |  5 ++
 Documentation/_includes/sitemap.html          | 58 +++++++++++++++++++
 Documentation/_layouts/page.html              | 31 ++++++++++
 ...architecture-decision-record-template.adoc |  2 +-
 Documentation/doc/index.adoc                  |  7 +++
 Documentation/sitemap.adoc                    |  8 +++
 Documentation/style.css                       | 46 +++++++++++++++
 7 files changed, 156 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..ab55e04 100644
--- a/Documentation/_includes/footer_custom.html
+++ b/Documentation/_includes/footer_custom.html
@@ -14,3 +14,8 @@ 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>
+&middot;
+<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..723bdb3
--- /dev/null
+++ b/Documentation/_includes/sitemap.html
@@ -0,0 +1,58 @@
+{% 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 url_start = p.url | slice: 0, prefix.size -%}
+    {%- if url_start == prefix -%}
+    {%- assign suffix = p.url | slice: prefix.size, p.url.size -%}
+    {%- 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 is_section -%}
+        {%- include sitemap.html prefix=p.url -%}
+      {%- endif -%}
+    </li>
+    {%- endif -%}
+    {%- 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..cb1bb7b
--- /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">
+  <a href="/">Spectrum</a>
+  /
+  <a href="/doc/">Documentation</a>
+  /
+  <span aria-current="page">{{ page.title }}</span>
+</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..f8cb9da 100644
--- a/Documentation/style.css
+++ b/Documentation/style.css
@@ -25,3 +25,49 @@ var {
 :target {
     background: yellow;
 }
+
+: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.54.0


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH v3 2/3] Documentation: drop Just the Docs
  2026-06-16  9:35 ` [PATCH v3 0/3] Documentation: render all pages in one style Valentin Gagarin
  2026-06-16  9:35   ` [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
@ 2026-06-16  9:35   ` Valentin Gagarin
  2026-06-17 10:48     ` Alyssa Ross
  2026-06-16  9:35   ` [PATCH v3 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
  2026-06-16 12:01   ` [PATCH v3 0/3] Documentation: render all pages in one style Alyssa Ross
  3 siblings, 1 reply; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-16  9:35 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
---
 Documentation/Gemfile                         |  1 -
 Documentation/Gemfile.lock                    | 12 +-----
 Documentation/_config.yml                     |  7 ---
 Documentation/_includes/title.html            | 13 ------
 Documentation/_plugins/site_title_link.rb     | 10 -----
 Documentation/_sass/custom/custom.scss        | 43 -------------------
 Documentation/doc/about/architecture.adoc     |  1 -
 Documentation/doc/about/index.adoc            |  2 -
 Documentation/doc/about/requirements.adoc     |  1 -
 Documentation/doc/contributing/b4.adoc        |  2 -
 .../contributing/building-documentation.adoc  |  1 -
 .../doc/contributing/communication.adoc       |  2 -
 .../doc/contributing/first-patch.adoc         |  2 -
 Documentation/doc/contributing/index.adoc     |  2 -
 Documentation/doc/contributing/replying.adoc  |  2 -
 .../doc/contributing/reviewing-patches.adoc   |  2 -
 .../doc/contributing/testing-patches.adoc     |  2 -
 .../contributing/working-with-patches.adoc    |  2 -
 .../contributing/writing_documentation.adoc   |  5 +--
 .../decisions/001-host-update-mechanism.adoc  |  2 -
 .../doc/decisions/002-install-options.adoc    |  2 -
 .../doc/decisions/003-partitioning.adoc       |  2 -
 .../004-data-at-rest-encryption.adoc          |  2 -
 .../005-virtual-machine-monitor.adoc          |  2 -
 .../doc/decisions/006-drivers-on-host.adoc    |  2 -
 .../decisions/007-usb-virtual-machines.adoc   |  2 -
 ...008-inter-vm-communication-mechanisms.adoc |  2 -
 Documentation/doc/decisions/index.adoc        |  2 -
 .../doc/development/build-configuration.adoc  |  1 -
 .../doc/development/built-in-vms.adoc         |  1 -
 Documentation/doc/development/checks.adoc     |  1 -
 Documentation/doc/development/debugging.adoc  |  1 -
 Documentation/doc/development/index.adoc      |  2 -
 .../doc/development/persistent-storage.adoc   |  1 -
 Documentation/doc/development/release.adoc    |  1 -
 Documentation/doc/development/updates.adoc    |  1 -
 .../doc/development/uuid-reference.adoc       |  1 -
 Documentation/doc/index.adoc                  |  1 -
 .../doc/installation/binary-cache.adoc        |  1 -
 .../doc/installation/getting-spectrum.adoc    |  1 -
 Documentation/doc/installation/index.adoc     |  2 -
 .../using-spectrum/creating-custom-vms.adoc   |  1 -
 Documentation/doc/using-spectrum/index.adoc   |  2 -
 .../doc/using-spectrum/running-vms.adoc       |  1 -
 .../doc/using-spectrum/vm-file-access.adoc    |  1 -
 Documentation/gemset.nix                      | 33 --------------
 46 files changed, 2 insertions(+), 181 deletions(-)
 delete mode 100644 Documentation/_includes/title.html
 delete mode 100644 Documentation/_plugins/site_title_link.rb
 delete mode 100644 Documentation/_sass/custom/custom.scss

diff --git a/Documentation/Gemfile b/Documentation/Gemfile
index 3c3f59d..a6396da 100644
--- a/Documentation/Gemfile
+++ b/Documentation/Gemfile
@@ -6,4 +6,3 @@ source "https://rubygems.org"
 
 gem "jekyll"
 gem "jekyll-asciidoc"
-gem "just-the-docs", "~> 0.10.0"
diff --git a/Documentation/Gemfile.lock b/Documentation/Gemfile.lock
index e7b515e..992e6da 100644
--- a/Documentation/Gemfile.lock
+++ b/Documentation/Gemfile.lock
@@ -43,20 +43,11 @@ GEM
     jekyll-asciidoc (3.0.1)
       asciidoctor (>= 1.5.0, < 3.0.0)
       jekyll (>= 3.0.0)
-    jekyll-include-cache (0.2.1)
-      jekyll (>= 3.7, < 5.0)
     jekyll-sass-converter (3.1.0)
       sass-embedded (~> 1.75)
-    jekyll-seo-tag (2.8.0)
-      jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     json (2.13.0)
-    just-the-docs (0.10.1)
-      jekyll (>= 3.8.5)
-      jekyll-include-cache
-      jekyll-seo-tag (>= 2.0)
-      rake (>= 12.3.1)
     kramdown (2.5.1)
       rexml (>= 3.3.9)
     kramdown-parser-gfm (1.1.0)
@@ -90,7 +81,6 @@ PLATFORMS
 DEPENDENCIES
   jekyll
   jekyll-asciidoc
-  just-the-docs (~> 0.10.0)
 
 BUNDLED WITH
-   2.6.9
+   2.7.2
diff --git a/Documentation/_config.yml b/Documentation/_config.yml
index b11c399..cc3e8ea 100644
--- a/Documentation/_config.yml
+++ b/Documentation/_config.yml
@@ -2,13 +2,6 @@
 # SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 ---
 title: Spectrum documentation
-logo: /logo/logo_html.svg
-theme: just-the-docs
-aux_links:
-  Home:
-    - /
-  Git:
-    - "https://spectrum-os.org/git/"
 plugins:
   - jekyll-asciidoc
 exclude:
diff --git a/Documentation/_includes/title.html b/Documentation/_includes/title.html
deleted file mode 100644
index 90ef71b..0000000
--- a/Documentation/_includes/title.html
+++ /dev/null
@@ -1,13 +0,0 @@
-{% comment %}
-SPDX-License-Identifier: MIT
-SPDX-FileCopyrightText: 2016 Patrick Marsceill
-SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-Override of: https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_includes/title.html
-{% endcomment %}
-{% if site.logo %}
-  <div class="site-logo" role="img" aria-label="{{ site.title }}"></div>
-{% endif %}
-{% if site.title %}
-  {{ site.title }}
-{% endif %}
diff --git a/Documentation/_plugins/site_title_link.rb b/Documentation/_plugins/site_title_link.rb
deleted file mode 100644
index 4095701..0000000
--- a/Documentation/_plugins/site_title_link.rb
+++ /dev/null
@@ -1,10 +0,0 @@
-# SPDX-License-Identifier: EUPL-1.2+
-# SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-# Just the Docs hardcodes the site header link to `/`.
-# https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_includes/components/sidebar.html#L14
-# Make it point to the docs root, not the top-level site.
-Jekyll::Hooks.register [:pages, :documents], :post_render do |item|
-  item.output.sub!('<a href="/" class="site-title',
-                   '<a href="/doc/" class="site-title')
-end
diff --git a/Documentation/_sass/custom/custom.scss b/Documentation/_sass/custom/custom.scss
deleted file mode 100644
index 48b1d41..0000000
--- a/Documentation/_sass/custom/custom.scss
+++ /dev/null
@@ -1,43 +0,0 @@
-// SPDX-License-Identifier: MIT
-// SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
-// SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
-
-.main-content {
-	// Just the Docs puts titles next to definitions, rather than on
-	// the line before.  This makes the definitions too horizontally
-	// compressed.
-	dl {
-		display: block;
-	}
-	dt {
-		text-align: left;
-		font-weight: bold;
-
-		&::after {
-			content: none;
-		}
-	}
-	dd {
-		margin-left: 2ch;
-	}
-}
-
-// Make the logo and title fit the site header.
-.site-header {
-  .site-logo {
-    width: 3rem;
-  }
-
-  // Just the Docs displays a sidebar at the "medium size" `md` breakpoint and above.
-  // Use the upstream `mq` media query mixin to target that breakpoint.
-  // https://just-the-docs.com/docs/utilities/responsive-modifiers/
-  // https://github.com/just-the-docs/just-the-docs/blob/v0.10.1/_sass/support/mixins/_layout.scss#L3-L8
-  @include mq(md) {
-    .site-logo {
-      width: 5.5rem;
-    }
-    .site-title {
-      font-size: 1.25rem !important;
-    }
-  }
-}
diff --git a/Documentation/doc/about/architecture.adoc b/Documentation/doc/about/architecture.adoc
index 2b86616..bbc927d 100644
--- a/Documentation/doc/about/architecture.adoc
+++ b/Documentation/doc/about/architecture.adoc
@@ -1,5 +1,4 @@
 = Architecture
-:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/about/index.adoc b/Documentation/doc/about/index.adoc
index 6961b6a..019737f 100644
--- a/Documentation/doc/about/index.adoc
+++ b/Documentation/doc/about/index.adoc
@@ -1,7 +1,5 @@
 = About Spectrum
-:description: Some words about Spectrum as the operating system, not a project. Highlights the differences between common Linux distributions and Spectrum.
 :page-nav_order: 1
-:page-has_children: true
 
 // 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/about/requirements.adoc b/Documentation/doc/about/requirements.adoc
index 40f802f..6c32c31 100644
--- a/Documentation/doc/about/requirements.adoc
+++ b/Documentation/doc/about/requirements.adoc
@@ -1,5 +1,4 @@
 = Hardware and firmware requirements
-:page-parent: About Spectrum
 
 // SPDX-FileCopyrightText: 2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/contributing/b4.adoc b/Documentation/doc/contributing/b4.adoc
index 81f2519..3734c3a 100644
--- a/Documentation/doc/contributing/b4.adoc
+++ b/Documentation/doc/contributing/b4.adoc
@@ -1,6 +1,4 @@
 = Installing and Configuring b4
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/building-documentation.adoc b/Documentation/doc/contributing/building-documentation.adoc
index 919a021..b691d4d 100644
--- a/Documentation/doc/contributing/building-documentation.adoc
+++ b/Documentation/doc/contributing/building-documentation.adoc
@@ -1,5 +1,4 @@
 = Building Documentation
-:page-parent: Contributing
 :page-nav_order: 4
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/contributing/communication.adoc b/Documentation/doc/contributing/communication.adoc
index 874ad4e..987014e 100644
--- a/Documentation/doc/contributing/communication.adoc
+++ b/Documentation/doc/contributing/communication.adoc
@@ -1,7 +1,5 @@
 = Communication in Spectrum
-:description: Channels, announcements and so on.
 :page-nav_order: 1
-:page-parent: Contributing
 
 // SPDX-FileCopyrightText: 2019-2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2023 Unikie
diff --git a/Documentation/doc/contributing/first-patch.adoc b/Documentation/doc/contributing/first-patch.adoc
index 38326c0..2625888 100644
--- a/Documentation/doc/contributing/first-patch.adoc
+++ b/Documentation/doc/contributing/first-patch.adoc
@@ -1,6 +1,4 @@
 = Sending Your Patch
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/contributing/index.adoc b/Documentation/doc/contributing/index.adoc
index 5ae6811..04ff34a 100644
--- a/Documentation/doc/contributing/index.adoc
+++ b/Documentation/doc/contributing/index.adoc
@@ -1,7 +1,5 @@
 = Contributing
-:description: How to contribute changes to the Spectrum source repository.
 :page-nav_order: 5
-:page-has_children: true
 
 // SPDX-FileCopyrightText: 2023 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/contributing/replying.adoc b/Documentation/doc/contributing/replying.adoc
index c478afb..c6ec4b8 100644
--- a/Documentation/doc/contributing/replying.adoc
+++ b/Documentation/doc/contributing/replying.adoc
@@ -1,6 +1,4 @@
 = Replying to Messages in the Mailing List Archives
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/reviewing-patches.adoc b/Documentation/doc/contributing/reviewing-patches.adoc
index 0e73b0e..224e314 100644
--- a/Documentation/doc/contributing/reviewing-patches.adoc
+++ b/Documentation/doc/contributing/reviewing-patches.adoc
@@ -1,6 +1,4 @@
 = Reviewing Patches
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/testing-patches.adoc b/Documentation/doc/contributing/testing-patches.adoc
index d98b738..031855d 100644
--- a/Documentation/doc/contributing/testing-patches.adoc
+++ b/Documentation/doc/contributing/testing-patches.adoc
@@ -1,6 +1,4 @@
 = Testing Patches
-:page-parent: Working with Patches
-:page-grand_parent: Contributing
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/working-with-patches.adoc b/Documentation/doc/contributing/working-with-patches.adoc
index 8e22343..6e1e83e 100644
--- a/Documentation/doc/contributing/working-with-patches.adoc
+++ b/Documentation/doc/contributing/working-with-patches.adoc
@@ -1,7 +1,5 @@
 = Working with Patches
-:page-parent: Contributing
 :page-nav_order: 2
-:page-has_children: true
 
 // SPDX-FileCopyrightText: 2022 Unikie
 // SPDX-FileCopyrightText: 2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/contributing/writing_documentation.adoc b/Documentation/doc/contributing/writing_documentation.adoc
index cb09241..d61f0bd 100644
--- a/Documentation/doc/contributing/writing_documentation.adoc
+++ b/Documentation/doc/contributing/writing_documentation.adoc
@@ -1,7 +1,5 @@
 = Documentation Style Guide
-:description: Channels, announcements and so on.
 :page-nav_order: 3
-:page-parent: Contributing
 
 // SPDX-FileCopyrightText: 2023 Unikie
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
@@ -12,7 +10,7 @@ Please follow these guidelines and conventions
 when editing the documentation.
 
 We use https://nixos.org/manual/nix/stable/introduction.html[Nix] and
-https://github.com/just-the-docs/just-the-docs[Just the Docs] for
+https://jekyllrb.com/[Jekyll] for
 building the documentation. Sources are written in AsciiDoc If you are
 new with it, see
 https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation].
@@ -42,7 +40,6 @@ to suit your changing needs.
 include your name and a revision line following the author line. Example:
 
     = Document Title
-    :description: Some words about the content.
     Author Name <author@example.org>
     v1.0, 2012-02-10
     //empty line that ends the document header
diff --git a/Documentation/doc/decisions/001-host-update-mechanism.adoc b/Documentation/doc/decisions/001-host-update-mechanism.adoc
index 39f9f28..d0ab341 100644
--- a/Documentation/doc/decisions/001-host-update-mechanism.adoc
+++ b/Documentation/doc/decisions/001-host-update-mechanism.adoc
@@ -1,6 +1,4 @@
 = 001 Host Update Mechanism
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/002-install-options.adoc b/Documentation/doc/decisions/002-install-options.adoc
index 4a745eb..f56a626 100644
--- a/Documentation/doc/decisions/002-install-options.adoc
+++ b/Documentation/doc/decisions/002-install-options.adoc
@@ -1,6 +1,4 @@
 = 002 Install Options
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/003-partitioning.adoc b/Documentation/doc/decisions/003-partitioning.adoc
index 8e538c3..39f0ee2 100644
--- a/Documentation/doc/decisions/003-partitioning.adoc
+++ b/Documentation/doc/decisions/003-partitioning.adoc
@@ -1,6 +1,4 @@
 = 003 Partitioning
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/004-data-at-rest-encryption.adoc b/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
index 5b0f518..8f4d430 100644
--- a/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
+++ b/Documentation/doc/decisions/004-data-at-rest-encryption.adoc
@@ -1,6 +1,4 @@
 = 004 Data at Rest Encryption
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/005-virtual-machine-monitor.adoc b/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
index 8a66c08..1ead8e1 100644
--- a/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
+++ b/Documentation/doc/decisions/005-virtual-machine-monitor.adoc
@@ -1,6 +1,4 @@
 = 005 Virtual Machine Monitor
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/006-drivers-on-host.adoc b/Documentation/doc/decisions/006-drivers-on-host.adoc
index b92d863..ce7a072 100644
--- a/Documentation/doc/decisions/006-drivers-on-host.adoc
+++ b/Documentation/doc/decisions/006-drivers-on-host.adoc
@@ -1,6 +1,4 @@
 = 006 Drivers on Host
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/007-usb-virtual-machines.adoc b/Documentation/doc/decisions/007-usb-virtual-machines.adoc
index d832691..f494537 100644
--- a/Documentation/doc/decisions/007-usb-virtual-machines.adoc
+++ b/Documentation/doc/decisions/007-usb-virtual-machines.adoc
@@ -1,6 +1,4 @@
 = 007 USB Virtual Machine
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/008-inter-vm-communication-mechanisms.adoc b/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
index c1e5b87..4dec40e 100644
--- a/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
+++ b/Documentation/doc/decisions/008-inter-vm-communication-mechanisms.adoc
@@ -1,6 +1,4 @@
 = 008 Inter-VM Communication Mechanisms
-:page-parent: Architecture Decision Records
-:page-grand_parent: About Spectrum
 
 // 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/decisions/index.adoc b/Documentation/doc/decisions/index.adoc
index a022239..8a5d237 100644
--- a/Documentation/doc/decisions/index.adoc
+++ b/Documentation/doc/decisions/index.adoc
@@ -1,6 +1,4 @@
 = Architecture Decision Records
-:page-has_children: true
-:page-parent: About Spectrum
 
 // 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/development/build-configuration.adoc b/Documentation/doc/development/build-configuration.adoc
index 49651d0..af7b9fa 100644
--- a/Documentation/doc/development/build-configuration.adoc
+++ b/Documentation/doc/development/build-configuration.adoc
@@ -1,5 +1,4 @@
 = Configuring the Build
-:page-parent: Development
 :page-nav_order: 1
 :example-caption: Test
 
diff --git a/Documentation/doc/development/built-in-vms.adoc b/Documentation/doc/development/built-in-vms.adoc
index d044e75..fdb5f15 100644
--- a/Documentation/doc/development/built-in-vms.adoc
+++ b/Documentation/doc/development/built-in-vms.adoc
@@ -1,5 +1,4 @@
 = Developing Built-in Application VMs
-:page-parent: Development
 :page-nav_order: 3
 
 // SPDX-FileCopyrightText: 2023-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/checks.adoc b/Documentation/doc/development/checks.adoc
index 905d5b8..64463cc 100644
--- a/Documentation/doc/development/checks.adoc
+++ b/Documentation/doc/development/checks.adoc
@@ -1,5 +1,4 @@
 = Checks
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/debugging.adoc b/Documentation/doc/development/debugging.adoc
index f1bbf01..39fd989 100644
--- a/Documentation/doc/development/debugging.adoc
+++ b/Documentation/doc/development/debugging.adoc
@@ -1,5 +1,4 @@
 = Debugging
-:page-parent: Development
 :page-nav_order: 4
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/index.adoc b/Documentation/doc/development/index.adoc
index 4e50425..a52c593 100644
--- a/Documentation/doc/development/index.adoc
+++ b/Documentation/doc/development/index.adoc
@@ -1,7 +1,5 @@
 = Development
-:description: Development progress, general development practices
 :page-nav_order: 4
-:page-has_children: true
 
 // 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/development/persistent-storage.adoc b/Documentation/doc/development/persistent-storage.adoc
index c4bcc16..e3db767 100644
--- a/Documentation/doc/development/persistent-storage.adoc
+++ b/Documentation/doc/development/persistent-storage.adoc
@@ -1,5 +1,4 @@
 = Persistent storage
-:page-parent: Development
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/development/release.adoc b/Documentation/doc/development/release.adoc
index 4ecbf03..2ab9d88 100644
--- a/Documentation/doc/development/release.adoc
+++ b/Documentation/doc/development/release.adoc
@@ -1,5 +1,4 @@
 = Release Builds
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2023 Alyssa Ross <hi@alyssa.is>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/updates.adoc b/Documentation/doc/development/updates.adoc
index 8746f97..1ec08c2 100644
--- a/Documentation/doc/development/updates.adoc
+++ b/Documentation/doc/development/updates.adoc
@@ -1,5 +1,4 @@
 = Updating the OS
-:page-parent: Development
 
 // SPDX-FileCopyrightText: 2025 Demi Marie Obenour <demiobenour@gmail.com>
 // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
diff --git a/Documentation/doc/development/uuid-reference.adoc b/Documentation/doc/development/uuid-reference.adoc
index 16279c8..21c8935 100644
--- a/Documentation/doc/development/uuid-reference.adoc
+++ b/Documentation/doc/development/uuid-reference.adoc
@@ -1,5 +1,4 @@
 = UUID Reference
-:page-parent: Development
 :page-nav_order: 6
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/index.adoc b/Documentation/doc/index.adoc
index 3bf3934..a24d85f 100644
--- a/Documentation/doc/index.adoc
+++ b/Documentation/doc/index.adoc
@@ -1,5 +1,4 @@
 = Spectrum Documentation
-:page-nav_exclude: true
 :page-liquid:
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/binary-cache.adoc b/Documentation/doc/installation/binary-cache.adoc
index 4feaad4..105e09d 100644
--- a/Documentation/doc/installation/binary-cache.adoc
+++ b/Documentation/doc/installation/binary-cache.adoc
@@ -1,5 +1,4 @@
 = Setting Up Binary Cache
-:page-parent: Build and Run
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022-2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/getting-spectrum.adoc b/Documentation/doc/installation/getting-spectrum.adoc
index 22c1fe3..478b1fc 100644
--- a/Documentation/doc/installation/getting-spectrum.adoc
+++ b/Documentation/doc/installation/getting-spectrum.adoc
@@ -1,5 +1,4 @@
 = Getting Spectrum
-:page-parent: Build and Run
 :page-nav_order: 2
 
 // SPDX-FileCopyrightText: 2022-2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/installation/index.adoc b/Documentation/doc/installation/index.adoc
index d1df2ed..225abc6 100644
--- a/Documentation/doc/installation/index.adoc
+++ b/Documentation/doc/installation/index.adoc
@@ -1,7 +1,5 @@
 = Build and Run
-:description: How to download and install Spectrum OS.
 :page-nav_order: 2
-:page-has_children: true
 :page-has_toc: false
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/creating-custom-vms.adoc b/Documentation/doc/using-spectrum/creating-custom-vms.adoc
index 68213c8..5b74084 100644
--- a/Documentation/doc/using-spectrum/creating-custom-vms.adoc
+++ b/Documentation/doc/using-spectrum/creating-custom-vms.adoc
@@ -1,5 +1,4 @@
 = Creating Custom VMs
-:page-parent: Using Spectrum
 
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/index.adoc b/Documentation/doc/using-spectrum/index.adoc
index 25347a4..9571b50 100644
--- a/Documentation/doc/using-spectrum/index.adoc
+++ b/Documentation/doc/using-spectrum/index.adoc
@@ -1,7 +1,5 @@
 = Using Spectrum
-:description: Exploring Spectrum OS. Using (=How-To-Guides), Configuring (adding smth).
 :page-nav_order: 3
-:page-has_children: true
 :page-has_toc: false
 
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/doc/using-spectrum/running-vms.adoc b/Documentation/doc/using-spectrum/running-vms.adoc
index 2b47fc0..d8a7732 100644
--- a/Documentation/doc/using-spectrum/running-vms.adoc
+++ b/Documentation/doc/using-spectrum/running-vms.adoc
@@ -1,5 +1,4 @@
 = Running VMs
-:page-parent: Using Spectrum
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2022, 2024 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/doc/using-spectrum/vm-file-access.adoc b/Documentation/doc/using-spectrum/vm-file-access.adoc
index 6189233..d4276d4 100644
--- a/Documentation/doc/using-spectrum/vm-file-access.adoc
+++ b/Documentation/doc/using-spectrum/vm-file-access.adoc
@@ -1,5 +1,4 @@
 = VM File Access
-:page-parent: Using Spectrum
 :page-nav_order: 1
 
 // SPDX-FileCopyrightText: 2024-2025 Alyssa Ross <hi@alyssa.is>
diff --git a/Documentation/gemset.nix b/Documentation/gemset.nix
index 7b85a7f..b31a35e 100644
--- a/Documentation/gemset.nix
+++ b/Documentation/gemset.nix
@@ -165,17 +165,6 @@
     };
     version = "3.0.1";
   };
-  jekyll-include-cache = {
-    dependencies = ["jekyll"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "01d2l6qrmjc42664ns83cv36jbvalcxqbkmj5i22fakka7jvkm67";
-      type = "gem";
-    };
-    version = "0.2.1";
-  };
   jekyll-sass-converter = {
     dependencies = ["sass-embedded"];
     groups = ["default"];
@@ -187,17 +176,6 @@
     };
     version = "3.1.0";
   };
-  jekyll-seo-tag = {
-    dependencies = ["jekyll"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "0638mqhqynghnlnaz0xi1kvnv53wkggaq94flfzlxwandn8x2biz";
-      type = "gem";
-    };
-    version = "2.8.0";
-  };
   jekyll-watch = {
     dependencies = ["listen"];
     groups = ["default"];
@@ -219,17 +197,6 @@
     };
     version = "2.13.0";
   };
-  just-the-docs = {
-    dependencies = ["jekyll" "jekyll-include-cache" "jekyll-seo-tag" "rake"];
-    groups = ["default"];
-    platforms = [];
-    source = {
-      remotes = ["https://rubygems.org"];
-      sha256 = "0y2mvzg2vxb4lk1rfay8d405qij4ifa65ypz09qj0945wf6qgsmw";
-      type = "gem";
-    };
-    version = "0.10.1";
-  };
   kramdown = {
     dependencies = ["rexml"];
     groups = ["default"];
-- 
2.54.0


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* [PATCH v3 3/3] Documentation: uniform navigation across all pages
  2026-06-16  9:35 ` [PATCH v3 0/3] Documentation: render all pages in one style Valentin Gagarin
  2026-06-16  9:35   ` [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
  2026-06-16  9:35   ` [PATCH v3 2/3] Documentation: drop Just the Docs Valentin Gagarin
@ 2026-06-16  9:35   ` Valentin Gagarin
  2026-06-16 12:01     ` Alyssa Ross
  2026-06-17 10:48     ` Alyssa Ross
  2026-06-16 12:01   ` [PATCH v3 0/3] Documentation: render all pages in one style Alyssa Ross
  3 siblings, 2 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-16  9:35 UTC (permalink / raw)
  To: devel; +Cc: Valentin Gagarin

- Render breadcrumb navigation for all pages
- Use common page layout for hard-coded HTML pages
- Sort hard-coded HTML into sitemap
- Show link to source in the footer

Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
---
 Documentation/_includes/breadcrumb.html       | 21 ++++++++++
 .../{footer_custom.html => footer.html}       | 16 ++++----
 Documentation/_includes/sitemap.html          |  7 +++-
 Documentation/_layouts/page.html              | 15 +++----
 Documentation/bibliography.html               | 38 +++---------------
 Documentation/contributing.html               | 38 +++---------------
 Documentation/design.html                     | 38 +++---------------
 Documentation/doc/index.adoc                  |  3 +-
 Documentation/impressum.html                  | 35 +++--------------
 Documentation/index.html                      | 33 +++-------------
 Documentation/logo/index.html                 | 38 +++---------------
 Documentation/motivation.html                 | 38 +++---------------
 .../software/cloud-hypervisor/index.html      | 39 ++-----------------
 Documentation/software/index.html             | 38 +++---------------
 Documentation/style.css                       |  4 ++
 15 files changed, 92 insertions(+), 309 deletions(-)
 create mode 100644 Documentation/_includes/breadcrumb.html
 rename Documentation/_includes/{footer_custom.html => footer.html} (72%)

diff --git a/Documentation/_includes/breadcrumb.html b/Documentation/_includes/breadcrumb.html
new file mode 100644
index 0000000..3b93128
--- /dev/null
+++ b/Documentation/_includes/breadcrumb.html
@@ -0,0 +1,21 @@
+{% comment %}
+SPDX-License-Identifier: GPL-3.0-or-later
+SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
+{% endcomment %}
+{%- unless page.url == '/' -%}
+<nav aria-label="Breadcrumb">
+  <a href="/">Spectrum</a>
+  {%- assign parts = page.url | split: '/' -%}
+  {%- assign acc = '' -%}
+  {%- for part in parts offset: 1 -%}
+    {%- assign acc = acc | append: '/' | append: part -%}
+    {%- assign parent_url = acc | append: '/' -%}
+    {%- if parent_url == page.url -%}{%- continue -%}{%- endif -%}
+    {%- assign parent = site.pages | where: 'url', parent_url | first -%}
+    {%- if parent %}
+    / <a href="{{ parent.url }}">{{ parent.title }}</a>
+    {%- endif -%}
+  {%- endfor %}
+  / <span aria-current="page">{{ page.title }}</span>
+</nav>
+{%- endunless -%}
diff --git a/Documentation/_includes/footer_custom.html b/Documentation/_includes/footer.html
similarity index 72%
rename from Documentation/_includes/footer_custom.html
rename to Documentation/_includes/footer.html
index ab55e04..d0e2c0b 100644
--- a/Documentation/_includes/footer_custom.html
+++ b/Documentation/_includes/footer.html
@@ -3,19 +3,19 @@ SPDX-FileCopyrightText: 2020 Alyssa Ross <hi@alyssa.is>
 SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later
 {% endcomment %}
 <p>
-<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
+Permission is granted to copy, distribute and/or modify this
 document under either the terms of the
 <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
 Commons Attribution-ShareAlike 4.0 International License</a>, or the
 <a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
 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>
+Front-Cover Texts, and no Back-Cover Texts.
 
-<p>
-<a href="/sitemap.html"><small>Sitemap</small></a>
+<nav aria-label="Footer">
+<a href="/sitemap.html">Sitemap</a>
+&middot;
+<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
 &middot;
-<a href="/impressum.html" lang="de"><small>Impressum</small></a>
+<a href="/impressum.html" lang="de">Impressum</a>
+</nav>
diff --git a/Documentation/_includes/sitemap.html b/Documentation/_includes/sitemap.html
index 723bdb3..26e96ec 100644
--- a/Documentation/_includes/sitemap.html
+++ b/Documentation/_includes/sitemap.html
@@ -18,6 +18,10 @@ which we assume if it is constructed by a directory and contains an index file.
   {%- assign candidates = site.html_pages
         | where_exp: "p", "p.url contains prefix"
         | where_exp: "p", "p.url != prefix" -%}
+  {%- if prefix == default_root -%}
+    {%- assign list_with_root_page = site.html_pages | where: "url", prefix -%}
+    {%- assign candidates = list_with_root_page | concat: candidates -%}
+  {%- endif -%}
   {%- comment %}
   Ordered pages first, ascending.  The rest after, in URL order, so output is deterministic.
   {%- endcomment %}
@@ -35,9 +39,10 @@ which we assume if it is constructed by a directory and contains an index file.
     {%- 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 -%}
+    {%- if p.name == "index.adoc" or p.name == "index.html" -%}{%- assign is_index = true -%}{%- endif -%}
     {%- assign is_page = false -%}
     {%- if is_index == false and slashes == 0 -%}{%- assign is_page = true -%}{%- endif -%}
+    {%- if is_index and suffix == "" -%}{%- 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 %}
diff --git a/Documentation/_layouts/page.html b/Documentation/_layouts/page.html
index cb1bb7b..4eba50d 100644
--- a/Documentation/_layouts/page.html
+++ b/Documentation/_layouts/page.html
@@ -3,7 +3,7 @@ SPDX-License-Identifier: GPL-3.0-or-later
 SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 {% endcomment %}
 <!doctype html>
-<html lang="en">
+<html lang="{{ page.lang | default: "en" }}">
 
 <head>
 
@@ -17,15 +17,12 @@ SPDX-FileCopyrightText: 2026 Valentin Gagarin <valentin@gagarin.work>
 
 <body>
 
-<nav aria-label="Breadcrumb">
-  <a href="/">Spectrum</a>
-  /
-  <a href="/doc/">Documentation</a>
-  /
-  <span aria-current="page">{{ page.title }}</span>
-</nav>
+{% include breadcrumb.html %}
+
+{% assign ext = page.path | split: "." | last %}
+{% if ext == "html" and page.no_heading != true %}<h1>{{ page.title }}</h1>{% endif %}
 
 {{ content }}
 
-{% include footer_custom.html %}
+{% include footer.html %}
 </html>
diff --git a/Documentation/bibliography.html b/Documentation/bibliography.html
index f9a8efd..175115a 100644
--- a/Documentation/bibliography.html
+++ b/Documentation/bibliography.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Bibliography
+nav_order: 200
+---
 <!-- SPDX-FileCopyrightText: 2019-2023 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum Bibliography</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Bibliography</h1>
 
 <p>If you'd like to find out when new links are posted, subscribe to
 the <a href="https://spectrum-os.org/git/www/atom/bibliography.html">cgit
@@ -137,16 +122,3 @@ atom feed for this page</a>.
   <li><cite><a href="https://github.com/cloud-hypervisor/cloud-hypervisor">cloud-hypervisor</a></cite>
 
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/contributing.html b/Documentation/contributing.html
index ea85499..9bb21d8 100644
--- a/Documentation/contributing.html
+++ b/Documentation/contributing.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Contributing to Spectrum
+nav_order: 10
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Contributing to Spectrum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Contributing to Spectrum</h1>
 
 <p>
 Thank you so much for your interest in contributing to Spectrum.
@@ -104,16 +89,3 @@ on <a href="/doc/contributing/communication.html#spectrum-discuss">spectrum-disc
 or in real time
 on <a href="/doc/contributing/communication.html#chat">Matrix or
 IRC</a>.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/design.html b/Documentation/design.html
index 51e0b77..0aa8762 100644
--- a/Documentation/design.html
+++ b/Documentation/design.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Design
+nav_order: 2
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum Design</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Spectrum Design</h1>
 
 <p>
 Spectrum will, for now, be a Linux-based system, with packages from
@@ -96,16 +81,3 @@ diverse range of hardware, to verify that the images correspond to the
 source code, and are free of tampering.  Work
 like <a href="https://nix-community.github.io/trustix/">Trustix</a>
 will be important to reaching this goal.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/doc/index.adoc b/Documentation/doc/index.adoc
index a24d85f..81b2a18 100644
--- a/Documentation/doc/index.adoc
+++ b/Documentation/doc/index.adoc
@@ -1,5 +1,6 @@
-= Spectrum Documentation
+= Documentation
 :page-liquid:
+:page-nav_order: 100
 
 // SPDX-FileCopyrightText: 2022 Alyssa Ross <hi@alyssa.is>
 // SPDX-FileCopyrightText: 2022 Unikie
diff --git a/Documentation/impressum.html b/Documentation/impressum.html
index b4806fe..416ce67 100644
--- a/Documentation/impressum.html
+++ b/Documentation/impressum.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Impressum
+lang: de
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="de">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Impressum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Impressum</h1>
 
 <address>
   <p>
@@ -32,13 +17,3 @@
   <p>
   hi@alyssa.is
 </address>
-
-<p lang="en">
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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>
diff --git a/Documentation/index.html b/Documentation/index.html
index 51685dd..6d6faf7 100644
--- a/Documentation/index.html
+++ b/Documentation/index.html
@@ -1,20 +1,12 @@
-<!doctype html>
+---
+layout: page
+title: Spectrum, a step towards usable secure computing
+no_heading: true
+nav_order: 0
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Spectrum, a step towards usable secure computing</title>
-
-<body>
 
 <a href="logo" style="float: left; margin: 0 1em 0.5em 0">
   <img class="logo" src="logo/logo_html.svg" width="70" height="70" alt="Spectrum logo">
@@ -95,16 +87,3 @@ initiative by the Digital Single Market of the European Commission.
     <li><a href="https://cryptpad.fr/kanban/#/2/kanban/view/yLtGXWLV6U7X5+Z1ay+oXKZMrSacqQe+51nXZYRh3ck/">Upstream bug/patch tracking</a>
   </ul>
 </nav>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/logo/index.html b/Documentation/logo/index.html
index 2354062..fbab443 100644
--- a/Documentation/logo/index.html
+++ b/Documentation/logo/index.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Logo
+nav_order: 1002
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo_html.svg">
-<link rel="stylesheet" href="../style.css">
-
-<title>Spectrum logo</title>
-
-<body>
-
-<nav>
-  <a href="..">Spectrum</a>
-</nav>
-
-<h1>Logo</h1>
 
 <p>
 <img class="logo" src="logo_html.svg" width="200" height="200" alt="" style="margin: 0 auto">
@@ -48,16 +33,3 @@ Mesh Gradients</a>.
   <li><a href="logo_mesh.svg" download>logo_mesh.svg</a> (for Inkscape)
 
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/motivation.html b/Documentation/motivation.html
index 4cbe5b0..e144251 100644
--- a/Documentation/motivation.html
+++ b/Documentation/motivation.html
@@ -1,26 +1,11 @@
-<!doctype html>
+---
+layout: page
+title: Motivation for Spectrum
+nav_order: 1
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="logo/logo_html.svg">
-<link rel="stylesheet" href="style.css">
-
-<title>Motivation for Spectrum</title>
-
-<body>
-
-<nav>
-  <a href=".">Spectrum</a>
-</nav>
-
-<h1>Motivation for Spectrum</h1>
 
 <p>
 Existing attempts to improve on the security of Unix-like operating
@@ -122,16 +107,3 @@ major security issue.
 
 <p>
 The last release of SubgraphOS was an alpha in 2017.
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/software/cloud-hypervisor/index.html b/Documentation/software/cloud-hypervisor/index.html
index 1845068..9b4315c 100644
--- a/Documentation/software/cloud-hypervisor/index.html
+++ b/Documentation/software/cloud-hypervisor/index.html
@@ -1,26 +1,10 @@
-<!doctype html>
+---
+layout: page
+title: Cloud Hypervisor with virtio-gpu support
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="../../logo/logo_html.svg">
-<link rel="stylesheet" href="../../style.css">
-
-<title>Cloud Hypervisor with virtio-gpu support</title>
-
-<body>
-
-<nav>
-  <a href="../..">Spectrum</a>
-</nav>
-
-<h1>Cloud Hypervisor with virtio-gpu support</h1>
 
 <p>
 This is a patchset for <a href="https://cloudhypervisor.org/">Cloud
@@ -162,18 +146,3 @@ the <a href="mailto:discuss@spectrum-os.org">discuss@spectrum-os.org</a>
 list</a>, or ask in the
 Spectrum <a href="/doc/contributing/communication.html#chat">Matrix
 chat</a>.
-
-<hr>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../../impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/software/index.html b/Documentation/software/index.html
index 2a8a852..8b95c2d 100644
--- a/Documentation/software/index.html
+++ b/Documentation/software/index.html
@@ -1,41 +1,13 @@
-<!doctype html>
+---
+layout: page
+title: Spectrum software
+nav_order: 3
+---
 <!-- SPDX-FileCopyrightText: 2019-2020, 2022, 2024 Alyssa Ross <hi@alyssa.is> -->
 <!-- SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later -->
 <!-- SPDX-License-Identifier: GPL-3.0-or-later -->
-<html lang="en">
-
-<head>
-
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-
-<link rel="icon" href="../logo/logo_html.svg">
-<link rel="stylesheet" href="../style.css">
-
-<title>Spectrum software</title>
-
-<body>
-
-<nav>
-  <a href="..">Spectrum</a>
-</nav>
-
-<h1>Spectrum software</h1>
 
 <ul>
   <li><a href="cloud-hypervisor">Cloud Hypervisor with virtio-gpu
   support</a>
 </ul>
-
-<p>
-<small>Permission is granted to copy, distribute and/or modify this
-document under either the terms of the
-<a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
-Commons Attribution-ShareAlike 4.0 International License</a>, or the
-<a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
-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="../impressum.html" lang="de"><small>Impressum</small></a>
diff --git a/Documentation/style.css b/Documentation/style.css
index f8cb9da..ae617c5 100644
--- a/Documentation/style.css
+++ b/Documentation/style.css
@@ -26,6 +26,10 @@ var {
     background: yellow;
 }
 
+footer {
+	font-size: small;
+}
+
 :root {
 	--bg: Canvas;
 	--code-bg: whitesmoke;
-- 
2.54.0


^ permalink raw reply related	[flat|nested] 28+ messages in thread

* Re: [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-16  9:35   ` [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
@ 2026-06-16 11:49     ` Alyssa Ross
  2026-06-16 12:02       ` Valentin Gagarin
  2026-06-17 10:48     ` Alyssa Ross
  1 sibling, 1 reply; 28+ messages in thread
From: Alyssa Ross @ 2026-06-16 11:49 UTC (permalink / raw)
  To: Valentin Gagarin; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 1992 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

> diff --git a/Documentation/_includes/sitemap.html b/Documentation/_includes/sitemap.html
> new file mode 100644
> index 0000000..723bdb3
> --- /dev/null
> +++ b/Documentation/_includes/sitemap.html
> @@ -0,0 +1,58 @@
> +{% 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 url_start = p.url | slice: 0, prefix.size -%}
> +    {%- if url_start == prefix -%}

Should be indentation inside this.  (Or we could do a continue to avoid
rightward drift.)  Let me know which you prefer.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH v3 3/3] Documentation: uniform navigation across all pages
  2026-06-16  9:35   ` [PATCH v3 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
@ 2026-06-16 12:01     ` Alyssa Ross
  2026-06-17 10:48     ` Alyssa Ross
  1 sibling, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-16 12:01 UTC (permalink / raw)
  To: Valentin Gagarin; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 2508 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

> diff --git a/Documentation/_includes/footer_custom.html b/Documentation/_includes/footer.html
> similarity index 72%
> rename from Documentation/_includes/footer_custom.html
> rename to Documentation/_includes/footer.html
> index ab55e04..d0e2c0b 100644
> --- a/Documentation/_includes/footer_custom.html
> +++ b/Documentation/_includes/footer.html
> @@ -3,19 +3,19 @@ SPDX-FileCopyrightText: 2020 Alyssa Ross <hi@alyssa.is>
>  SPDX-License-Identifier: CC-BY-SA-4.0 OR GFDL-1.3-no-invariants-or-later
>  {% endcomment %}
>  <p>
> -<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
> -
> -<p>
> -<small>Permission is granted to copy, distribute and/or modify this
> +Permission is granted to copy, distribute and/or modify this
>  document under either the terms of the
>  <a href="https://creativecommons.org/licenses/by-sa/4.0/">Creative
>  Commons Attribution-ShareAlike 4.0 International License</a>, or the
>  <a href="https://www.gnu.org/licenses/fdl-1.3.html">GNU Free
>  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>
> +Front-Cover Texts, and no Back-Cover Texts.

Decided to drop the <small> entirely?  I thought it was quite nice to
mark the small print, both semantically and visually.  Legal text is
exactly the sort of thing it's for:

https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/small

> -<p>
> -<a href="/sitemap.html"><small>Sitemap</small></a>
> +<nav aria-label="Footer">
> +<a href="/sitemap.html">Sitemap</a>
> +&middot;
> +<a href="https://spectrum-os.org/git/spectrum/tree/Documentation/{{ page.path }}">Source code for this page</a>
>  &middot;
> -<a href="/impressum.html" lang="de"><small>Impressum</small></a>
> +<a href="/impressum.html" lang="de">Impressum</a>
> +</nav>

I can see dropping the <small>s here making sense though.

> diff --git a/Documentation/style.css b/Documentation/style.css
> index f8cb9da..ae617c5 100644
> --- a/Documentation/style.css
> +++ b/Documentation/style.css
> @@ -26,6 +26,10 @@ var {
>      background: yellow;
>  }
>  
> +footer {
> +	font-size: small;
> +}
> +

This doesn't do anything, because there are no footer elements.
(As above though I think it makes sense to retain the <small> in HTML.)

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH v3 0/3] Documentation: render all pages in one style
  2026-06-16  9:35 ` [PATCH v3 0/3] Documentation: render all pages in one style Valentin Gagarin
                     ` (2 preceding siblings ...)
  2026-06-16  9:35   ` [PATCH v3 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
@ 2026-06-16 12:01   ` Alyssa Ross
  3 siblings, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-16 12:01 UTC (permalink / raw)
  To: Valentin Gagarin; +Cc: devel

[-- Attachment #1: Type: text/plain, Size: 418 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

> After some out-of-band discussion I decided to make the navigation
> structure more literal.  That has the advantage of being slightly less
> source code and slightly smaller output, but more importantly it seems
> to degrade more gracefully and less noisily for limited clients, such as
> screen readers and text browsers.

Thanks!  I think this is an improvement.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-16 11:49     ` Alyssa Ross
@ 2026-06-16 12:02       ` Valentin Gagarin
  0 siblings, 0 replies; 28+ messages in thread
From: Valentin Gagarin @ 2026-06-16 12:02 UTC (permalink / raw)
  To: Alyssa Ross; +Cc: devel

> Should be indentation inside this.
Right, would be great if you can fix that up before merging.  Thank you!

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website
  2026-06-16  9:35   ` [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
  2026-06-16 11:49     ` Alyssa Ross
@ 2026-06-17 10:48     ` Alyssa Ross
  1 sibling, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-17 10:48 UTC (permalink / raw)
  To: Valentin Gagarin, devel; +Cc: Valentin Gagarin

This patch has been committed as 5e7602c1ec087fdbc79dec115dce4c7378a66e45,
which can be viewed online at
https://spectrum-os.org/git/spectrum/commit/?id=5e7602c1ec087fdbc79dec115dce4c7378a66e45.

This is an automated message.  Send comments/questions/requests to:
Alyssa Ross <hi@alyssa.is>

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH v3 2/3] Documentation: drop Just the Docs
  2026-06-16  9:35   ` [PATCH v3 2/3] Documentation: drop Just the Docs Valentin Gagarin
@ 2026-06-17 10:48     ` Alyssa Ross
  0 siblings, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-17 10:48 UTC (permalink / raw)
  To: Valentin Gagarin, devel; +Cc: Valentin Gagarin

This patch has been committed as 6544f1ac00e9fa43e98eac4436a070ba3aa97640,
which can be viewed online at
https://spectrum-os.org/git/spectrum/commit/?id=6544f1ac00e9fa43e98eac4436a070ba3aa97640.

This is an automated message.  Send comments/questions/requests to:
Alyssa Ross <hi@alyssa.is>

^ permalink raw reply	[flat|nested] 28+ messages in thread

* Re: [PATCH v3 3/3] Documentation: uniform navigation across all pages
  2026-06-16  9:35   ` [PATCH v3 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
  2026-06-16 12:01     ` Alyssa Ross
@ 2026-06-17 10:48     ` Alyssa Ross
  1 sibling, 0 replies; 28+ messages in thread
From: Alyssa Ross @ 2026-06-17 10:48 UTC (permalink / raw)
  To: Valentin Gagarin, devel; +Cc: Valentin Gagarin

This patch has been committed as e459fbfd65673150979c96426dd76484bbba6e10,
which can be viewed online at
https://spectrum-os.org/git/spectrum/commit/?id=e459fbfd65673150979c96426dd76484bbba6e10.

This is an automated message.  Send comments/questions/requests to:
Alyssa Ross <hi@alyssa.is>

^ permalink raw reply	[flat|nested] 28+ messages in thread

end of thread, other threads:[~2026-06-17 10:48 UTC | newest]

Thread overview: 28+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-06-08 16:49 [PATCH 0/3] Documentation: render all pages in one style Valentin Gagarin
2026-06-08 16:49 ` [PATCH 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
2026-06-08 16:49 ` [PATCH 2/3] Documentation: drop Just the Docs Valentin Gagarin
2026-06-08 16:49 ` [PATCH 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
2026-06-08 16:49 ` [PATCH 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
2026-06-09 11:45   ` Alyssa Ross
2026-06-10 12:12     ` Valentin Gagarin
2026-06-10 12:23       ` Alyssa Ross
2026-06-08 16:49 ` [PATCH 2/3] Documentation: drop Just the Docs Valentin Gagarin
2026-06-09 11:43   ` Alyssa Ross
2026-06-08 16:49 ` [PATCH 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
2026-06-09 11:54   ` Alyssa Ross
2026-06-11  6:37 ` [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
2026-06-11  6:37   ` [PATCH v2 2/3] Documentation: drop Just the Docs Valentin Gagarin
2026-06-11  6:37   ` [PATCH v2 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
2026-06-12  8:44     ` Alyssa Ross
2026-06-12  8:27   ` [PATCH v2 1/3] Documentation: align Jekyll page style to rest of website Alyssa Ross
2026-06-16  9:35 ` [PATCH v3 0/3] Documentation: render all pages in one style Valentin Gagarin
2026-06-16  9:35   ` [PATCH v3 1/3] Documentation: align Jekyll page style to rest of website Valentin Gagarin
2026-06-16 11:49     ` Alyssa Ross
2026-06-16 12:02       ` Valentin Gagarin
2026-06-17 10:48     ` Alyssa Ross
2026-06-16  9:35   ` [PATCH v3 2/3] Documentation: drop Just the Docs Valentin Gagarin
2026-06-17 10:48     ` Alyssa Ross
2026-06-16  9:35   ` [PATCH v3 3/3] Documentation: uniform navigation across all pages Valentin Gagarin
2026-06-16 12:01     ` Alyssa Ross
2026-06-17 10:48     ` Alyssa Ross
2026-06-16 12:01   ` [PATCH v3 0/3] Documentation: render all pages in one style Alyssa Ross

Code repositories for project(s) associated with this public inbox

	https://spectrum-os.org/git/crosvm
	https://spectrum-os.org/git/doc
	https://spectrum-os.org/git/mktuntap
	https://spectrum-os.org/git/nixpkgs
	https://spectrum-os.org/git/spectrum
	https://spectrum-os.org/git/ucspi-vsock
	https://spectrum-os.org/git/www

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).