From f52b8226beffc7871054b62448139b89893d1d31 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 11:03:42 +0000
Subject: [PATCH 1/7] Hide the drawers until their element is upgraded

A custom element renders its children until it is upgraded, and a side
drawer keeps its closed state in its shadow root. The script that defines
it is an async module, so it runs after the first paint: until then the
search drawer painted over the header and the table of contents drawer
over the article, which read as a collapsed layout for a moment.

Measured while undefined, the search drawer was 500x98 over the header
and the table of contents drawer 500x216 over the article. The nav
drawer was not visible on a wide screen, because it sits in the mobile
nav, which is hidden there.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kkjvqifo7fQ5W6woRWiSW
---
 .changeset/olive-moons-shake.md    | 10 ++++++++++
 packages/markdown/assets/shell.css |  7 +++++++
 website/en/book/changelog.md       |  2 ++
 3 files changed, 19 insertions(+)
 create mode 100644 .changeset/olive-moons-shake.md

diff --git a/.changeset/olive-moons-shake.md b/.changeset/olive-moons-shake.md
new file mode 100644
index 000000000..b12d62fac
--- /dev/null
+++ b/.changeset/olive-moons-shake.md
@@ -0,0 +1,10 @@
+---
+"@hyperbook/markdown": patch
+"hyperbook": patch
+"hyperbook-studio": patch
+---
+
+Fix the drawers flashing over the page while it loads. A custom element renders
+its children until it is upgraded, and a side drawer is only hidden by its
+shadow root, so the search drawer and the table of contents drawer painted over
+the header and the article until `side-drawer.js` had run.
diff --git a/packages/markdown/assets/shell.css b/packages/markdown/assets/shell.css
index 5d39024d9..200dca032 100644
--- a/packages/markdown/assets/shell.css
+++ b/packages/markdown/assets/shell.css
@@ -41,6 +41,13 @@ side-drawer {
   display: none;
 }
 
+/* A custom element renders its children until it is upgraded. The drawers are
+   only hidden by their shadow root, so without this their content paints over
+   the page until side-drawer.js has run. */
+side-drawer:not(:defined) {
+  display: none;
+}
+
 /* Hide mobile nav toggle when JavaScript is disabled */
 .no-js .mobile-nav .toggle {
   display: none;
diff --git a/website/en/book/changelog.md b/website/en/book/changelog.md
index e1dcd2c5e..573abdac4 100644
--- a/website/en/book/changelog.md
+++ b/website/en/book/changelog.md
@@ -62,6 +62,8 @@ If you need a new feature, open an [issue](https://github.com/openpatch/hyperboo
 
 **bookmarks**: A heading that contains a quote or a backslash can be bookmarked again.
 
+**shell**: The search and table of contents drawers no longer flash over the page for a moment while it loads.
+
 :::
 
 ::::

From 3df69aca695d3757d97ed217e0acde86e07593ad Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 11:14:49 +0000
Subject: [PATCH 2/7] Inline the script that loads the theme stylesheets

The light and dark stylesheets sit in a noscript element and are written
into the page by a script. Nothing can paint before they are there, so
loading that script as a file put a round trip in front of every first
paint, and a second one in front of the stylesheets it writes.

The script is 1.5 kB, so it is part of the page now. On the
documentation, over a connection throttled to 1.5 Mbit/s with 100 ms of
latency, the first contentful paint went from a median of 1128 ms to
984 ms over seven runs each.

The behaviour is unchanged: a mode the reader picked before still wins
over the system preference, in both directions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kkjvqifo7fQ5W6woRWiSW
---
 .changeset/gentle-pans-smile.md               |  11 +
 .../darkModeStylesheetsLoader.ts}             |  27 +-
 packages/markdown/src/rehypeHtmlStructure.ts  |  15 +-
 .../tests/__snapshots__/process.test.ts.snap  | 324 +++++++++++++++++-
 website/en/book/changelog.md                  |   2 +
 5 files changed, 349 insertions(+), 30 deletions(-)
 create mode 100644 .changeset/gentle-pans-smile.md
 rename packages/markdown/{assets/dark-mode-toggle-stylesheets-loader.js => src/darkModeStylesheetsLoader.ts} (50%)

diff --git a/.changeset/gentle-pans-smile.md b/.changeset/gentle-pans-smile.md
new file mode 100644
index 000000000..b56f7faad
--- /dev/null
+++ b/.changeset/gentle-pans-smile.md
@@ -0,0 +1,11 @@
+---
+"@hyperbook/markdown": patch
+"hyperbook": patch
+"hyperbook-studio": patch
+---
+
+Inline the script that loads the light and dark stylesheets. It was a file, and
+nothing can paint before the stylesheets it writes are there, so every first
+paint waited for a round trip to fetch 1.5 kB and then another for the
+stylesheets themselves. It is part of the page now, which measured about 140 ms
+off the first contentful paint of the documentation on a throttled connection.
diff --git a/packages/markdown/assets/dark-mode-toggle-stylesheets-loader.js b/packages/markdown/src/darkModeStylesheetsLoader.ts
similarity index 50%
rename from packages/markdown/assets/dark-mode-toggle-stylesheets-loader.js
rename to packages/markdown/src/darkModeStylesheetsLoader.ts
index 9e888b15e..5f08e2224 100644
--- a/packages/markdown/assets/dark-mode-toggle-stylesheets-loader.js
+++ b/packages/markdown/src/darkModeStylesheetsLoader.ts
@@ -1,19 +1,17 @@
 /**
- * Copyright 2024 Google LLC
+ * Writes the light and dark stylesheets into the page, honoring a mode the
+ * reader picked before. The stylesheets sit in a noscript element, so they are
+ * only text until this runs.
  *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
+ * This is inlined into the head instead of being loaded as a file. Nothing can
+ * paint before the stylesheets are there, so an external script would put a
+ * round trip in front of every first paint, and a second one in front of the
+ * stylesheets it writes.
  *
- *     https://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+ * https://www.apache.org/licenses/LICENSE-2.0
  */
-
+export const darkModeStylesheetsLoader = `
 // @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
 (() => {
   const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
@@ -28,8 +26,8 @@
     mode = localStorage.getItem(STORAGE_NAME);
   } catch (e) {}
 
-  const lightCSSMediaRegex = /\(\s*prefers-color-scheme\s*:\s*light\s*\)/gi;
-  const darkCSSMediaRegex = /\(\s*prefers-color-scheme\s*:\s*dark\s*\)/gi;
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
 
   switch (mode) {
     case LIGHT:
@@ -47,3 +45,4 @@
 
   document.write(stylesheets);
 })();
+// @license-end`;
diff --git a/packages/markdown/src/rehypeHtmlStructure.ts b/packages/markdown/src/rehypeHtmlStructure.ts
index 5254a7f9b..bdc7331ed 100644
--- a/packages/markdown/src/rehypeHtmlStructure.ts
+++ b/packages/markdown/src/rehypeHtmlStructure.ts
@@ -4,6 +4,7 @@
 import { HyperbookContext } from "@hyperbook/types";
 import { ElementContent, Root } from "hast";
 import { VFile } from "vfile";
+import { darkModeStylesheetsLoader } from "./darkModeStylesheetsLoader";
 
 function parseFont(font: string): [string, string] {
   const parts = font.split(":");
@@ -379,13 +380,13 @@ window.hyperbook.emoji = { style: "twemoji", base: "${makeUrl(["emoji"], "assets
               {
                 type: "element",
                 tagName: "script",
-                properties: {
-                  src: makeUrl(
-                    ["dark-mode-toggle-stylesheets-loader.js"],
-                    "assets",
-                  ),
-                },
-                children: [],
+                properties: {},
+                children: [
+                  {
+                    type: "raw",
+                    value: darkModeStylesheetsLoader,
+                  },
+                ],
               },
               {
                 type: "element",
diff --git a/packages/markdown/tests/__snapshots__/process.test.ts.snap b/packages/markdown/tests/__snapshots__/process.test.ts.snap
index d811d1025..ebb30b558 100644
--- a/packages/markdown/tests/__snapshots__/process.test.ts.snap
+++ b/packages/markdown/tests/__snapshots__/process.test.ts.snap
@@ -41,7 +41,41 @@ body {
 }
 </style><noscript id="dark-mode-toggle-stylesheets"><link rel="stylesheet" href="assets/light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="assets/dark.css" media="(prefers-color-scheme: dark)"></noscript><script>
 // Remove no-js class as soon as JavaScript is available
-document.documentElement.classList.remove('no-js');</script><script src="assets/dark-mode-toggle-stylesheets-loader.js"></script><script type="module" src="assets/dark-mode-toggle.js"></script><script src="assets/i18n.js" defer></script><script src="assets/dexie.min.js" defer></script><script src="assets/dexie-export-import.js" defer></script><script src="assets/store.js" defer></script><script>
+document.documentElement.classList.remove('no-js');</script><script>
+// @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+(() => {
+  const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
+  const STORAGE_NAME = 'dark-mode-toggle';
+  const LIGHT = 'light';
+  const DARK = 'dark';
+
+  let stylesheets = document.getElementById(ELEMENT_ID).textContent;
+
+  let mode = null;
+  try {
+    mode = localStorage.getItem(STORAGE_NAME);
+  } catch (e) {}
+
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
+
+  switch (mode) {
+    case LIGHT:
+      stylesheets = stylesheets
+        .replace(lightCSSMediaRegex, '$&, all')
+        .replace(darkCSSMediaRegex, '$& and not all');
+      break;
+
+    case DARK:
+      stylesheets = stylesheets
+        .replace(darkCSSMediaRegex, '$&, all')
+        .replace(lightCSSMediaRegex, '$& and not all');
+      break;
+  }
+
+  document.write(stylesheets);
+})();
+// @license-end</script><script type="module" src="assets/dark-mode-toggle.js"></script><script src="assets/i18n.js" defer></script><script src="assets/dexie.min.js" defer></script><script src="assets/dexie-export-import.js" defer></script><script src="assets/store.js" defer></script><script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="assets/prism/prism.js" defer></script><script src="assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="assets/prism/prism.css"><link rel="stylesheet" href="assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="assets/math/katex.min.css"><link rel="stylesheet" href="assets/shell.css"><link rel="stylesheet" href="assets/content.css"><link rel="stylesheet" href="assets/code.css"><script>
 HYPERBOOK_ASSETS = "assets/"
@@ -115,7 +149,41 @@ body {
 }
 </style><noscript id="dark-mode-toggle-stylesheets"><link rel="stylesheet" href="/assets/light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/dark.css" media="(prefers-color-scheme: dark)"></noscript><script>
 // Remove no-js class as soon as JavaScript is available
-document.documentElement.classList.remove('no-js');</script><script src="/assets/dark-mode-toggle-stylesheets-loader.js"></script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
+document.documentElement.classList.remove('no-js');</script><script>
+// @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+(() => {
+  const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
+  const STORAGE_NAME = 'dark-mode-toggle';
+  const LIGHT = 'light';
+  const DARK = 'dark';
+
+  let stylesheets = document.getElementById(ELEMENT_ID).textContent;
+
+  let mode = null;
+  try {
+    mode = localStorage.getItem(STORAGE_NAME);
+  } catch (e) {}
+
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
+
+  switch (mode) {
+    case LIGHT:
+      stylesheets = stylesheets
+        .replace(lightCSSMediaRegex, '$&, all')
+        .replace(darkCSSMediaRegex, '$& and not all');
+      break;
+
+    case DARK:
+      stylesheets = stylesheets
+        .replace(darkCSSMediaRegex, '$&, all')
+        .replace(lightCSSMediaRegex, '$& and not all');
+      break;
+  }
+
+  document.write(stylesheets);
+})();
+// @license-end</script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
@@ -178,7 +246,41 @@ body {
 }
 </style><noscript id="dark-mode-toggle-stylesheets"><link rel="stylesheet" href="/assets/light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/dark.css" media="(prefers-color-scheme: dark)"></noscript><script>
 // Remove no-js class as soon as JavaScript is available
-document.documentElement.classList.remove('no-js');</script><script src="/assets/dark-mode-toggle-stylesheets-loader.js"></script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
+document.documentElement.classList.remove('no-js');</script><script>
+// @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+(() => {
+  const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
+  const STORAGE_NAME = 'dark-mode-toggle';
+  const LIGHT = 'light';
+  const DARK = 'dark';
+
+  let stylesheets = document.getElementById(ELEMENT_ID).textContent;
+
+  let mode = null;
+  try {
+    mode = localStorage.getItem(STORAGE_NAME);
+  } catch (e) {}
+
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
+
+  switch (mode) {
+    case LIGHT:
+      stylesheets = stylesheets
+        .replace(lightCSSMediaRegex, '$&, all')
+        .replace(darkCSSMediaRegex, '$& and not all');
+      break;
+
+    case DARK:
+      stylesheets = stylesheets
+        .replace(darkCSSMediaRegex, '$&, all')
+        .replace(lightCSSMediaRegex, '$& and not all');
+      break;
+  }
+
+  document.write(stylesheets);
+})();
+// @license-end</script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
@@ -241,7 +343,41 @@ body {
 }
 </style><noscript id="dark-mode-toggle-stylesheets"><link rel="stylesheet" href="/assets/light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/dark.css" media="(prefers-color-scheme: dark)"></noscript><script>
 // Remove no-js class as soon as JavaScript is available
-document.documentElement.classList.remove('no-js');</script><script src="/assets/dark-mode-toggle-stylesheets-loader.js"></script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
+document.documentElement.classList.remove('no-js');</script><script>
+// @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+(() => {
+  const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
+  const STORAGE_NAME = 'dark-mode-toggle';
+  const LIGHT = 'light';
+  const DARK = 'dark';
+
+  let stylesheets = document.getElementById(ELEMENT_ID).textContent;
+
+  let mode = null;
+  try {
+    mode = localStorage.getItem(STORAGE_NAME);
+  } catch (e) {}
+
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
+
+  switch (mode) {
+    case LIGHT:
+      stylesheets = stylesheets
+        .replace(lightCSSMediaRegex, '$&, all')
+        .replace(darkCSSMediaRegex, '$& and not all');
+      break;
+
+    case DARK:
+      stylesheets = stylesheets
+        .replace(darkCSSMediaRegex, '$&, all')
+        .replace(lightCSSMediaRegex, '$& and not all');
+      break;
+  }
+
+  document.write(stylesheets);
+})();
+// @license-end</script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
@@ -302,7 +438,41 @@ body {
 }
 </style><noscript id="dark-mode-toggle-stylesheets"><link rel="stylesheet" href="/assets/light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/dark.css" media="(prefers-color-scheme: dark)"></noscript><script>
 // Remove no-js class as soon as JavaScript is available
-document.documentElement.classList.remove('no-js');</script><script src="/assets/dark-mode-toggle-stylesheets-loader.js"></script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
+document.documentElement.classList.remove('no-js');</script><script>
+// @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+(() => {
+  const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
+  const STORAGE_NAME = 'dark-mode-toggle';
+  const LIGHT = 'light';
+  const DARK = 'dark';
+
+  let stylesheets = document.getElementById(ELEMENT_ID).textContent;
+
+  let mode = null;
+  try {
+    mode = localStorage.getItem(STORAGE_NAME);
+  } catch (e) {}
+
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
+
+  switch (mode) {
+    case LIGHT:
+      stylesheets = stylesheets
+        .replace(lightCSSMediaRegex, '$&, all')
+        .replace(darkCSSMediaRegex, '$& and not all');
+      break;
+
+    case DARK:
+      stylesheets = stylesheets
+        .replace(darkCSSMediaRegex, '$&, all')
+        .replace(lightCSSMediaRegex, '$& and not all');
+      break;
+  }
+
+  document.write(stylesheets);
+})();
+// @license-end</script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
@@ -363,7 +533,41 @@ body {
 }
 </style><noscript id="dark-mode-toggle-stylesheets"><link rel="stylesheet" href="/assets/light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/dark.css" media="(prefers-color-scheme: dark)"></noscript><script>
 // Remove no-js class as soon as JavaScript is available
-document.documentElement.classList.remove('no-js');</script><script src="/assets/dark-mode-toggle-stylesheets-loader.js"></script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
+document.documentElement.classList.remove('no-js');</script><script>
+// @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+(() => {
+  const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
+  const STORAGE_NAME = 'dark-mode-toggle';
+  const LIGHT = 'light';
+  const DARK = 'dark';
+
+  let stylesheets = document.getElementById(ELEMENT_ID).textContent;
+
+  let mode = null;
+  try {
+    mode = localStorage.getItem(STORAGE_NAME);
+  } catch (e) {}
+
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
+
+  switch (mode) {
+    case LIGHT:
+      stylesheets = stylesheets
+        .replace(lightCSSMediaRegex, '$&, all')
+        .replace(darkCSSMediaRegex, '$& and not all');
+      break;
+
+    case DARK:
+      stylesheets = stylesheets
+        .replace(darkCSSMediaRegex, '$&, all')
+        .replace(lightCSSMediaRegex, '$& and not all');
+      break;
+  }
+
+  document.write(stylesheets);
+})();
+// @license-end</script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
@@ -426,7 +630,41 @@ body {
 }
 </style><noscript id="dark-mode-toggle-stylesheets"><link rel="stylesheet" href="/assets/light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/dark.css" media="(prefers-color-scheme: dark)"></noscript><script>
 // Remove no-js class as soon as JavaScript is available
-document.documentElement.classList.remove('no-js');</script><script src="/assets/dark-mode-toggle-stylesheets-loader.js"></script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
+document.documentElement.classList.remove('no-js');</script><script>
+// @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+(() => {
+  const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
+  const STORAGE_NAME = 'dark-mode-toggle';
+  const LIGHT = 'light';
+  const DARK = 'dark';
+
+  let stylesheets = document.getElementById(ELEMENT_ID).textContent;
+
+  let mode = null;
+  try {
+    mode = localStorage.getItem(STORAGE_NAME);
+  } catch (e) {}
+
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
+
+  switch (mode) {
+    case LIGHT:
+      stylesheets = stylesheets
+        .replace(lightCSSMediaRegex, '$&, all')
+        .replace(darkCSSMediaRegex, '$& and not all');
+      break;
+
+    case DARK:
+      stylesheets = stylesheets
+        .replace(darkCSSMediaRegex, '$&, all')
+        .replace(lightCSSMediaRegex, '$& and not all');
+      break;
+  }
+
+  document.write(stylesheets);
+})();
+// @license-end</script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
@@ -494,7 +732,41 @@ body {
 }
 </style><noscript id="dark-mode-toggle-stylesheets"><link rel="stylesheet" href="/assets/light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/dark.css" media="(prefers-color-scheme: dark)"></noscript><script>
 // Remove no-js class as soon as JavaScript is available
-document.documentElement.classList.remove('no-js');</script><script src="/assets/dark-mode-toggle-stylesheets-loader.js"></script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
+document.documentElement.classList.remove('no-js');</script><script>
+// @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+(() => {
+  const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
+  const STORAGE_NAME = 'dark-mode-toggle';
+  const LIGHT = 'light';
+  const DARK = 'dark';
+
+  let stylesheets = document.getElementById(ELEMENT_ID).textContent;
+
+  let mode = null;
+  try {
+    mode = localStorage.getItem(STORAGE_NAME);
+  } catch (e) {}
+
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
+
+  switch (mode) {
+    case LIGHT:
+      stylesheets = stylesheets
+        .replace(lightCSSMediaRegex, '$&, all')
+        .replace(darkCSSMediaRegex, '$& and not all');
+      break;
+
+    case DARK:
+      stylesheets = stylesheets
+        .replace(darkCSSMediaRegex, '$&, all')
+        .replace(lightCSSMediaRegex, '$& and not all');
+      break;
+  }
+
+  document.write(stylesheets);
+})();
+// @license-end</script><script type="module" src="/assets/dark-mode-toggle.js"></script><script src="/assets/i18n.js" defer></script><script src="/assets/dexie.min.js" defer></script><script src="/assets/dexie-export-import.js" defer></script><script src="/assets/store.js" defer></script><script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
@@ -587,7 +859,41 @@ body {
 }
 </style><noscript id="dark-mode-toggle-stylesheets"><link rel="stylesheet" href="assets/light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="assets/dark.css" media="(prefers-color-scheme: dark)"></noscript><script>
 // Remove no-js class as soon as JavaScript is available
-document.documentElement.classList.remove('no-js');</script><script src="assets/dark-mode-toggle-stylesheets-loader.js"></script><script type="module" src="assets/dark-mode-toggle.js"></script><script src="assets/i18n.js" defer></script><script src="assets/dexie.min.js" defer></script><script src="assets/dexie-export-import.js" defer></script><script src="assets/store.js" defer></script><script>
+document.documentElement.classList.remove('no-js');</script><script>
+// @license © 2024 Google LLC. Licensed under the Apache License, Version 2.0.
+(() => {
+  const ELEMENT_ID = 'dark-mode-toggle-stylesheets';
+  const STORAGE_NAME = 'dark-mode-toggle';
+  const LIGHT = 'light';
+  const DARK = 'dark';
+
+  let stylesheets = document.getElementById(ELEMENT_ID).textContent;
+
+  let mode = null;
+  try {
+    mode = localStorage.getItem(STORAGE_NAME);
+  } catch (e) {}
+
+  const lightCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*light\\s*\\)/gi;
+  const darkCSSMediaRegex = /\\(\\s*prefers-color-scheme\\s*:\\s*dark\\s*\\)/gi;
+
+  switch (mode) {
+    case LIGHT:
+      stylesheets = stylesheets
+        .replace(lightCSSMediaRegex, '$&, all')
+        .replace(darkCSSMediaRegex, '$& and not all');
+      break;
+
+    case DARK:
+      stylesheets = stylesheets
+        .replace(darkCSSMediaRegex, '$&, all')
+        .replace(lightCSSMediaRegex, '$& and not all');
+      break;
+  }
+
+  document.write(stylesheets);
+})();
+// @license-end</script><script type="module" src="assets/dark-mode-toggle.js"></script><script src="assets/i18n.js" defer></script><script src="assets/dexie.min.js" defer></script><script src="assets/dexie-export-import.js" defer></script><script src="assets/store.js" defer></script><script>
 window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="assets/prism/prism.js" defer></script><script src="assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="assets/prism/prism.css"><link rel="stylesheet" href="assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="assets/math/katex.min.css"><link rel="stylesheet" href="assets/shell.css"><link rel="stylesheet" href="assets/content.css"><link rel="stylesheet" href="assets/code.css"><script>
 HYPERBOOK_ASSETS = "assets/"
diff --git a/website/en/book/changelog.md b/website/en/book/changelog.md
index 573abdac4..dd59d4f2e 100644
--- a/website/en/book/changelog.md
+++ b/website/en/book/changelog.md
@@ -64,6 +64,8 @@ If you need a new feature, open an [issue](https://github.com/openpatch/hyperboo
 
 **shell**: The search and table of contents drawers no longer flash over the page for a moment while it loads.
 
+**shell**: Pages paint sooner. The script that loads the light and dark stylesheets is part of the page now, instead of a file that had to be fetched before anything could be drawn.
+
 :::
 
 ::::

From 78e1eecedabaf82750e134afc010573475708cff Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 11:35:58 +0000
Subject: [PATCH 3/7] Order pages and sections together by index

Pages were rendered before the sections of the same level, so a page
could not sit after or between them. The index of a page and the index
of a section are one order now, and the navigation renders a run of
pages as a list, broken by every section that falls between them.

The reading order follows the same order, so the previous and next
buttons, the breadcrumb and pagelist agree with the sidebar. That order
lives in one place now, instead of once in the shell and twice in the
page list.

Without an index nothing moves: a page still comes before a section, and
a page wins a tie against a section. A book that indexes its sections
but not a page does move that page behind them, which is why the
documentation now gives its changelog page an index and shifts the
sections after it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kkjvqifo7fQ5W6woRWiSW
---
 .changeset/khaki-moles-tap.md                 | 20 +++++
 packages/fs/src/hyperbook.ts                  | 21 +++--
 packages/markdown/src/rehypeShell.ts          | 80 +++++++++----------
 .../markdown/src/remarkDirectivePagelist.ts   | 19 +++--
 .../tests/__snapshots__/process.test.ts.snap  | 14 ++--
 packages/markdown/tests/rehypeShell.test.ts   | 76 ++++++++++++++++++
 packages/types/src/index.ts                   | 56 +++++++++++++
 website/de/book/configuration/page.md         |  2 +-
 website/de/book/configuration/section.md      |  1 +
 website/en/book/changelog.md                  |  3 +
 website/en/book/configuration/index.md        |  2 +-
 website/en/book/configuration/page.md         |  2 +-
 website/en/book/configuration/section.md      |  1 +
 website/en/book/elements/index.md             |  2 +-
 website/en/book/hosting/index.md              |  2 +-
 website/en/book/markdown/index.md             |  2 +-
 16 files changed, 237 insertions(+), 66 deletions(-)
 create mode 100644 .changeset/khaki-moles-tap.md

diff --git a/.changeset/khaki-moles-tap.md b/.changeset/khaki-moles-tap.md
new file mode 100644
index 000000000..a758c9061
--- /dev/null
+++ b/.changeset/khaki-moles-tap.md
@@ -0,0 +1,20 @@
+---
+"@hyperbook/types": minor
+"@hyperbook/fs": minor
+"@hyperbook/markdown": minor
+"hyperbook": minor
+"hyperbook-studio": minor
+---
+
+Order pages and sections together by `index`. Pages were always rendered before
+the sections of the same level, so a page could not sit after or between them.
+The `index` of a page and the `index` of a section are now one order, and a
+section that ends up between two pages is rendered between them.
+
+The reading order follows the navigation, so the previous and next buttons, the
+breadcrumb and `::pagelist` agree with the sidebar.
+
+A page or a section without an `index` keeps its old place: pages come before
+sections, and a page wins a tie against a section. A book that gives its
+sections an `index` but leaves it off a page will see that page move behind
+those sections. Give the page an `index` to place it.
diff --git a/packages/fs/src/hyperbook.ts b/packages/fs/src/hyperbook.ts
index 782949ac9..850f1a2f3 100644
--- a/packages/fs/src/hyperbook.ts
+++ b/packages/fs/src/hyperbook.ts
@@ -6,6 +6,7 @@ import {
   HyperbookSection,
   Navigation,
   PageNavigation,
+  sortNavigation,
 } from "@hyperbook/types";
 import { findUp } from "find-up";
 import { vfile } from ".";
@@ -254,17 +255,25 @@ export const getPageList = (
   sections: HyperbookSection[],
   pages: HyperbookPage[],
 ): HyperbookPage[] => {
-  let pageList = [...pages];
+  let pageList: HyperbookPage[] = [];
 
-  for (const section of sections) {
+  // Reading order follows the navigation, so the previous and next buttons
+  // agree with the sidebar when a section sits between two pages.
+  for (const entry of sortNavigation(pages, sections)) {
+    if (entry.type === "page") {
+      pageList.push(entry.page);
+      continue;
+    }
+
+    const section = entry.section;
     // Check if section is virtual or not
     const isVirtual = section.virtual || section.navigation === "virtual";
-    
+
     if (!isVirtual && section.href) {
       // For non-virtual sections with an href, add the index page first
-      const indexPage = section.pages.find(p => p.href === section.href);
-      const otherPages = section.pages.filter(p => p.href !== section.href);
-      
+      const indexPage = section.pages.find((p) => p.href === section.href);
+      const otherPages = section.pages.filter((p) => p.href !== section.href);
+
       if (indexPage) {
         pageList.push(indexPage);
       }
diff --git a/packages/markdown/src/rehypeShell.ts b/packages/markdown/src/rehypeShell.ts
index 1f993320f..670fc84f7 100644
--- a/packages/markdown/src/rehypeShell.ts
+++ b/packages/markdown/src/rehypeShell.ts
@@ -6,6 +6,7 @@ import {
   HyperbookContext,
   HyperbookPage,
   HyperbookSection,
+  sortNavigation,
 } from "@hyperbook/types";
 import { ElementContent, Root } from "hast";
 import { VFile } from "vfile";
@@ -483,53 +484,52 @@ const makeNavigationSectionElement = (
   };
 };
 
-// Helper type for navigation items that can be sorted together
-type NavigationItem = 
-  | { type: "page"; item: HyperbookPage }
-  | { type: "section"; item: HyperbookSection };
-
 const makeNavigationElements = (ctx: HyperbookContext): ElementContent[] => {
-  // Collect all navigation items (pages and sections in "page" mode go to pages list)
-  const pageItems: NavigationItem[] = ctx.navigation.pages
-    .filter((p) => !p.hide && p.navigation !== "hidden")
-    .map((p) => ({ type: "page" as const, item: p }));
-  
-  const pageModeSecions: NavigationItem[] = ctx.navigation.sections
-    .filter((s) => !s.hide && s.navigation !== "hidden" && s.navigation === "page" && !s.isEmpty)
-    .map((s) => ({ type: "section" as const, item: s }));
-  
-  const regularSections = ctx.navigation.sections
-    .filter((s) => !s.hide && s.navigation !== "hidden" && s.navigation !== "page");
-
-  // Merge pages and page-mode sections, then sort by index
-  const combinedItems = [...pageItems, ...pageModeSecions].sort((a, b) => {
-    const aIndex = a.item.index !== undefined ? a.item.index : 9999;
-    const bIndex = b.item.index !== undefined ? b.item.index : 9999;
-    if (aIndex !== bIndex) return aIndex - bIndex;
-    return a.item.name > b.item.name ? 1 : -1;
-  });
+  const pages = ctx.navigation.pages.filter(
+    (p) => !p.hide && p.navigation !== "hidden",
+  );
+  const sections = ctx.navigation.sections.filter(
+    (s) =>
+      !s.hide &&
+      s.navigation !== "hidden" &&
+      // A section shown as a page needs a page to link to.
+      (s.navigation !== "page" || !s.isEmpty),
+  );
+
+  // Pages and sections share one order, so a section can sit between two
+  // pages. A run of pages becomes one list, a section breaks the run.
+  const children: ElementContent[] = [];
+  let list: ElementContent[] | null = null;
+  const addToList = (element: ElementContent) => {
+    if (!list) {
+      list = [];
+      children.push({
+        type: "element",
+        tagName: "ul",
+        properties: {},
+        children: list,
+      });
+    }
+    list.push(element);
+  };
+
+  for (const entry of sortNavigation(pages, sections)) {
+    if (entry.type === "page") {
+      addToList(makeNavigationPageElement(ctx, entry.page));
+    } else if (entry.section.navigation === "page") {
+      addToList(makeNavigationSectionAsPageElement(ctx, entry.section));
+    } else {
+      children.push(makeNavigationSectionElement(ctx, entry.section));
+      list = null;
+    }
+  }
 
   return [
     {
       type: "element",
       tagName: "nav",
       properties: {},
-      children: [
-        {
-          type: "element",
-          tagName: "ul",
-          properties: {},
-          children: combinedItems.map((navItem) => {
-            if (navItem.type === "page") {
-              return makeNavigationPageElement(ctx, navItem.item);
-            } else {
-              // Render section in page mode as a page element
-              return makeNavigationSectionAsPageElement(ctx, navItem.item);
-            }
-          }),
-        },
-        ...regularSections.map((s) => makeNavigationSectionElement(ctx, s)),
-      ],
+      children,
     },
   ];
 };
diff --git a/packages/markdown/src/remarkDirectivePagelist.ts b/packages/markdown/src/remarkDirectivePagelist.ts
index e9a7e527e..8ef96ab5b 100644
--- a/packages/markdown/src/remarkDirectivePagelist.ts
+++ b/packages/markdown/src/remarkDirectivePagelist.ts
@@ -5,6 +5,7 @@ import {
   HyperbookContext,
   HyperbookPage,
   HyperbookSection,
+  sortNavigation,
 } from "@hyperbook/types";
 import { registerBasicHelpers } from "@hyperbook/fs";
 import handlebars from "handlebars";
@@ -25,13 +26,17 @@ const getPageList = (
   sections: HyperbookSection[],
   pages: HyperbookPage[],
 ): HyperbookPage[] => {
-  let pageList = [...pages];
-
-  for (const section of sections) {
-    pageList = [
-      ...pageList,
-      ...getPageList(section.sections, section.pages),
-    ];
+  let pageList: HyperbookPage[] = [];
+
+  for (const entry of sortNavigation(pages, sections)) {
+    if (entry.type === "page") {
+      pageList.push(entry.page);
+    } else {
+      pageList = [
+        ...pageList,
+        ...getPageList(entry.section.sections, entry.section.pages),
+      ];
+    }
   }
 
   return pageList;
diff --git a/packages/markdown/tests/__snapshots__/process.test.ts.snap b/packages/markdown/tests/__snapshots__/process.test.ts.snap
index ebb30b558..495f626d3 100644
--- a/packages/markdown/tests/__snapshots__/process.test.ts.snap
+++ b/packages/markdown/tests/__snapshots__/process.test.ts.snap
@@ -188,7 +188,7 @@ window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
 
-</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
+</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
 <div class="hyperbook-markdown">
   <div class="floating-buttons-container" id="floating-buttons-container"><button id="toc-toggle" onclick="hyperbook.ui.tocToggle()" title="Table of Contents"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div><div class="bar4"></div></button></div>
   <side-drawer id="toc-drawer" right>
@@ -285,7 +285,7 @@ window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
 
-</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
+</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
 <div class="hyperbook-markdown">
   <div class="floating-buttons-container" id="floating-buttons-container"><button id="toc-toggle" onclick="hyperbook.ui.tocToggle()" title="Table of Contents"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div><div class="bar4"></div></button></div>
   <side-drawer id="toc-drawer" right>
@@ -382,7 +382,7 @@ window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
 
-</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
+</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
 <div class="hyperbook-markdown">
   <div class="floating-buttons-container" id="floating-buttons-container"><button id="toc-toggle" onclick="hyperbook.ui.tocToggle()" title="Table of Contents"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div><div class="bar4"></div></button></div>
   <side-drawer id="toc-drawer" right>
@@ -477,7 +477,7 @@ window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
 
-</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
+</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
 <div class="hyperbook-markdown">
   <div class="floating-buttons-container" id="floating-buttons-container"><button id="toc-toggle" onclick="hyperbook.ui.tocToggle()" title="Table of Contents"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div><div class="bar4"></div></button></div>
   <side-drawer id="toc-drawer" right>
@@ -572,7 +572,7 @@ window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
 
-</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
+</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
 <div class="hyperbook-markdown">
   <div class="floating-buttons-container" id="floating-buttons-container"><button id="toc-toggle" onclick="hyperbook.ui.tocToggle()" title="Table of Contents"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div><div class="bar4"></div></button></div>
   <side-drawer id="toc-drawer" right>
@@ -669,7 +669,7 @@ window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
 
-</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
+</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
 <div class="hyperbook-markdown">
   <div class="floating-buttons-container" id="floating-buttons-container"><button id="toc-toggle" onclick="hyperbook.ui.tocToggle()" title="Table of Contents"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div><div class="bar4"></div></button></div>
   <side-drawer id="toc-drawer" right>
@@ -771,7 +771,7 @@ window.Prism = window.Prism || {};
 window.Prism.manual = true;</script><script src="/assets/prism/prism.js" defer></script><script src="/assets/prism/prism-typst.js" defer></script><link rel="stylesheet" href="/assets/prism/prism.css"><link rel="stylesheet" href="/assets/prism/prism-theme-github-dark.css" media="(prefers-color-scheme: dark)"><link rel="stylesheet" href="/assets/prism/prism-theme-github-light.css" media="(prefers-color-scheme: light)"><link rel="stylesheet" href="/assets/math/katex.min.css"><link rel="stylesheet" href="/assets/shell.css"><link rel="stylesheet" href="/assets/content.css"><link rel="stylesheet" href="/assets/code.css"><script>
 HYPERBOOK_ASSETS = "/assets/"
 
-</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script><link rel="stylesheet" href="/assets/directive-tabs/style.css"><link rel="stylesheet" href="/assets/directive-youtube/style.css"></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav><ul></ul></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
+</script><script type="module" src="/assets/side-drawer.js" async></script><script src="/assets/qrcode.js" async></script><link rel="stylesheet" href="/assets/directive-tabs/style.css"><link rel="stylesheet" href="/assets/directive-youtube/style.css"></head><body><div class="main-grid"><header><div class="mobile-nav"><button aria-label="Nav Toggle" class="toggle" onclick="hyperbook.ui.navToggle()"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div></button><side-drawer id="nav-drawer"><div class="nav-drawer-content"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div></side-drawer></div><a class="branding" href="/book/"><div class="name">My Hyperbook</div></a><button id="share-button" class="icon-button" title="Share" onclick="hyperbook.share.open()"><div class="share-icon"></div></button><dark-mode-toggle id="dark-mode-toggle" appearence="switch" title="Toggle between Dark and Light Mode" permanent></dark-mode-toggle></header><div class="sidebar"><nav></nav><a class="author" href="https://hyperbook.openpatch.org">Powered by <b>Hyperbook</b></a></div><main><article>
 <div class="hyperbook-markdown">
   <div class="floating-buttons-container" id="floating-buttons-container"><button id="toc-toggle" onclick="hyperbook.ui.tocToggle()" title="Table of Contents"><div class="bar1"></div><div class="bar2"></div><div class="bar3"></div><div class="bar4"></div></button></div>
   <side-drawer id="toc-drawer" right>
diff --git a/packages/markdown/tests/rehypeShell.test.ts b/packages/markdown/tests/rehypeShell.test.ts
index c9f02f604..d8103bd95 100644
--- a/packages/markdown/tests/rehypeShell.test.ts
+++ b/packages/markdown/tests/rehypeShell.test.ts
@@ -323,4 +323,80 @@ describe("rehypeShell", () => {
     const value = toHtml("", rootCtx).value;
     expect(value).not.toContain('class="breadcrumb"');
   });
+
+  describe("navigation order", () => {
+    // The order of the labels in the navigation, so a test reads like the
+    // sidebar looks. A section is a <details>, a page an <a class="page">.
+    const order = (navigation: Partial<HyperbookContext["navigation"]>) => {
+      const html = String(
+        toHtml("", {
+          ...ctx,
+          navigation: {
+            ...ctx.navigation,
+            sections: [],
+            pages: [],
+            ...navigation,
+          },
+        }).value,
+      );
+      // The breadcrumb is a <nav> too, and it comes first in the document.
+      const start = html.indexOf("<nav>");
+      const nav = html.slice(start, html.indexOf("</nav>", start));
+      return [
+        ...nav.matchAll(
+          /class="page[^"]*" href="[^"]*">([^<]*)<|class="label">([^<]*)</g,
+        ),
+      ].map((m) => m[1] ?? m[2]);
+    };
+
+    const page = (name: string, index?: number) => ({
+      name,
+      href: "/" + name,
+      index,
+    });
+    const section = (name: string, index?: number) => ({
+      name,
+      href: "/" + name,
+      index,
+      isEmpty: false,
+      pages: [],
+      sections: [],
+    });
+
+    it("puts a section between two pages by index", () => {
+      expect(
+        order({
+          pages: [page("one", 1), page("three", 3)],
+          sections: [section("two", 2)],
+        }),
+      ).toEqual(["one", "two", "three"]);
+    });
+
+    it("puts a page after a section by index", () => {
+      expect(
+        order({
+          pages: [page("last", 9)],
+          sections: [section("first", 1)],
+        }),
+      ).toEqual(["first", "last"]);
+    });
+
+    it("keeps pages before sections when nothing has an index", () => {
+      expect(
+        order({
+          pages: [page("zebra"), page("apple")],
+          sections: [section("beta"), section("alpha")],
+        }),
+      ).toEqual(["apple", "zebra", "alpha", "beta"]);
+    });
+
+    it("puts a page before a section that shares its index", () => {
+      expect(
+        order({
+          pages: [page("zebra", 1)],
+          sections: [section("alpha", 1)],
+        }),
+      ).toEqual(["zebra", "alpha"]);
+    });
+  });
 });
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index 805db9c6b..9224d85da 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -259,6 +259,62 @@ export interface HyperbookContext {
   dependencies?: Set<string>;
 }
 
+/** One entry of a navigation level, either a page or a section. */
+export type NavigationEntry =
+  | { type: "page"; page: HyperbookPage }
+  | { type: "section"; section: HyperbookSection };
+
+/**
+ * Pages and sections without an index keep their old order, pages first. A
+ * section that is shown as a page is one of the pages here, because that is
+ * how it is rendered.
+ */
+const FALLBACK_INDEX_PAGE = 9999;
+const FALLBACK_INDEX_SECTION = 10000;
+
+const isShownAsPage = (section: HyperbookSection): boolean =>
+  section.navigation === "page";
+
+/**
+ * Brings the pages and the sections of one navigation level into a single
+ * order. `index` decides, across both of them, so a section can sit between
+ * two pages. Entries without an `index` fall back to pages before sections,
+ * and entries that end up equal are ordered by name.
+ */
+export const sortNavigation = (
+  pages: HyperbookPage[],
+  sections: HyperbookSection[],
+): NavigationEntry[] => {
+  const entries: {
+    entry: NavigationEntry;
+    index: number;
+    /** Decides a tie on the index: a page comes before a section. */
+    kind: number;
+    name: string;
+  }[] = [
+    ...pages.map((page) => ({
+      entry: { type: "page" as const, page },
+      index: page.index ?? FALLBACK_INDEX_PAGE,
+      kind: 0,
+      name: page.name,
+    })),
+    ...sections.map((section) => ({
+      entry: { type: "section" as const, section },
+      index:
+        section.index ??
+        (isShownAsPage(section) ? FALLBACK_INDEX_PAGE : FALLBACK_INDEX_SECTION),
+      kind: isShownAsPage(section) ? 0 : 1,
+      name: section.name,
+    })),
+  ];
+
+  return entries
+    .sort((a, b) => (a.name > b.name ? 1 : -1))
+    .sort((a, b) => a.kind - b.kind)
+    .sort((a, b) => a.index - b.index)
+    .map(({ entry }) => entry);
+};
+
 /**
  * Matches a URI scheme at the start of a string, as defined by RFC 3986.
  * This covers `https://` and `data:` as well as schemes without an authority
diff --git a/website/de/book/configuration/page.md b/website/de/book/configuration/page.md
index bfd4046c5..609b6dc80 100644
--- a/website/de/book/configuration/page.md
+++ b/website/de/book/configuration/page.md
@@ -38,7 +38,7 @@ Hier sind die Eigenschaften, die im Frontmatter gesetzt werden können:
 | description | Beschreibung der Seite. Wird für SEO verwendet.                                                                                                |
 | permaid     | Eine id, welche die Seite auch unter zum Beispiel /@/audio verfügbar macht, wenn die permaid auf audio gesetzt wurde. |
 | keywords    | Eine Liste von Schlüsselwörter. Wird für SEO verwendet.                                                                                        |
-| index       | Eine Zahl, die die Position relative zu anderen Seiten auf dieser Navigationsebene angibt. Kleine Zahlen erscheinen zuerst in der Navigation.  |
+| index       | Eine Zahl, die die Position relativ zu den anderen Seiten und den Bereichen auf dieser Navigationsebene angibt. Kleine Zahlen erscheinen zuerst in der Navigation. Ohne sie steht eine Seite vor den Bereichen. |
 | prev        | Ein absoluter Pfad zur vorherigen Seite or ein absoluter Pfad zur permaid z. B. /@/audio. Dies überschreibt index und hide. Du kannst außerdem nichts setzen, sodass der Button versteckt wird. |
 | next        | Ein absoluter Pfad zur nächsten Seite or ein absoluter Pfad zur permaid z. B. /@/audio. Dies überschreibt index und hide. Du kannst außerdem nichts setzen, sodass der Button versteckt wird.   |
 | hide        | Verstecke die Seite von der Navigation. (veraltet, verwende stattdessen `navigation: hidden`)                                                  |
diff --git a/website/de/book/configuration/section.md b/website/de/book/configuration/section.md
index be8773b73..089049fc0 100644
--- a/website/de/book/configuration/section.md
+++ b/website/de/book/configuration/section.md
@@ -14,6 +14,7 @@ Folgenden dokumentiert sind.
 | Property   | Description                                                                                                                        |
 | :--------- | :--------------------------------------------------------------------------------------------------------------------------------- |
 | ...        | Jede Eigenschaft der [Seite](/configuration/page)                                                                                  |
+| index      | Eine Zahl, die die Position relativ zu den Seiten und den anderen Bereichen auf dieser Navigationsebene angibt. Ohne sie steht ein Bereich hinter den Seiten. |
 | virtual    | Alles erscheint auf derselben Ebene wie der drüberliegende Ordner. Vorsicht: Die Index-Eigenschaft wirkt nicht über Ordner hinweg. (veraltet, verwende stattdessen `navigation: virtual`) |
 | expanded   | Definiert, ob der Bereich in der Navigation ausgeklappt sein soll. (veraltet, verwende stattdessen `navigation: expanded`)        |
 | navigation | Steuert wie der Bereich in der Navigation angezeigt wird. Optionen: `default` (aufklappbarer Bereich), `hidden` (versteckt in der Navigation), `virtual` (Elemente erscheinen auf Elternebene), `page` (wird als normaler Seitenlink angezeigt ohne Kinder anzuzeigen), `expanded` (Bereich ist standardmäßig ausgeklappt) |
diff --git a/website/en/book/changelog.md b/website/en/book/changelog.md
index dd59d4f2e..b3718aebb 100644
--- a/website/en/book/changelog.md
+++ b/website/en/book/changelog.md
@@ -1,5 +1,6 @@
 ---
 name: Changelog
+index: 1
 ---
 
 # Changelog
@@ -44,6 +45,8 @@ If you need a new feature, open an [issue](https://github.com/openpatch/hyperboo
 
 :::tab{title="New :rocket:" id="new"}
 
+**navigation**: A section can sit between two pages, and a page can sit after a section. The `index` of a page and the `index` of a section are one order now, instead of pages always coming first. Without an `index` nothing moves: pages still come before sections.
+
 **emoji**: Emojis can be rendered as images, so they look the same on every platform instead of being drawn with the emoji font of the reader's operating system. Set `elements.emoji.style` to `twemoji` in your `hyperbook.json`. Only the emojis your book uses end up in your build.
 
 :::
diff --git a/website/en/book/configuration/index.md b/website/en/book/configuration/index.md
index faae029aa..b1c0a4d1d 100644
--- a/website/en/book/configuration/index.md
+++ b/website/en/book/configuration/index.md
@@ -1,4 +1,4 @@
 ---
 name: Configuration
-index: 1
+index: 3
 ---
diff --git a/website/en/book/configuration/page.md b/website/en/book/configuration/page.md
index ccfd4a757..761870cc1 100644
--- a/website/en/book/configuration/page.md
+++ b/website/en/book/configuration/page.md
@@ -29,7 +29,7 @@ Here are the properties you can set in the frontmatter:
 | description | Description of the page used for SEO                                                                                                |
 | permaid     | An id which will make the page also available at e.g. /@/audio, when setting permaid to audio |
 | keywords    | A list of keywords used for SEO                                                                                                     |
-| index       | A number indicating the position in the menu in relation to pages on the same level                                                 |
+| index       | A number indicating the position in the menu, in relation to the pages and the sections on the same level. Without it, a page comes before the sections. |
 | prev        | The absolute path to the prev page or a absolute path to a permaid e.g. /@/audio. This overrides index and hide. You can also set it to nothing and it will hide the prev button. |
 | next        | The absoulte path to the next page or a absolute path to a permaid e.g. /@/audio. This overrides index and hide. You can also set it to nothing and it will hide the next button. |
 | hide        | Hides the page from the navigation (deprecated, use `navigation: hidden` instead)                                                  |
diff --git a/website/en/book/configuration/section.md b/website/en/book/configuration/section.md
index 464e7434c..87a9dc8c8 100644
--- a/website/en/book/configuration/section.md
+++ b/website/en/book/configuration/section.md
@@ -18,6 +18,7 @@ To summarize, here are the properties you can set in the frontmatter:
 | Property   | Description                                                                                                            |
 | :--------- | :--------------------------------------------------------------------------------------------------------------------- |
 | ...        | Every Property from a [page](/configuration/page)                                                                      |
+| index      | A number indicating the position in the menu, in relation to the pages and the sections on the same level. Without it, a section comes after the pages. |
 | virtual    | Everything will appear on the same level as the parent. Be aware that the index property does not work across folders. (deprecated, use `navigation: virtual` instead) |
 | expanded   | Defines whether the section is expanded on page load. (deprecated, use `navigation: expanded` instead)                 |
 | navigation | Controls how the section appears in navigation. Options: `default` (collapsible section), `hidden` (hides from navigation), `virtual` (items appear at parent level), `page` (renders as a regular page link without showing children), `expanded` (section is expanded by default) |
diff --git a/website/en/book/elements/index.md b/website/en/book/elements/index.md
index 92999a921..bd6497366 100644
--- a/website/en/book/elements/index.md
+++ b/website/en/book/elements/index.md
@@ -1,4 +1,4 @@
 ---
 name: Elements
-index: 2
+index: 4
 ---
diff --git a/website/en/book/hosting/index.md b/website/en/book/hosting/index.md
index 714691de8..854114741 100644
--- a/website/en/book/hosting/index.md
+++ b/website/en/book/hosting/index.md
@@ -1,4 +1,4 @@
 ---
 name: Hosting
-index: 3
+index: 5
 ---
diff --git a/website/en/book/markdown/index.md b/website/en/book/markdown/index.md
index aba664d22..f904444b4 100644
--- a/website/en/book/markdown/index.md
+++ b/website/en/book/markdown/index.md
@@ -1,4 +1,4 @@
 ---
 name: Markdown Reference
-index: 0
+index: 2
 ---

From 939f5b01e9677bc149bbc877ca4c2f0749c30ae8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 11:43:35 +0000
Subject: [PATCH 4/7] Indent the pages of a section in the navigation

A page of a section sat one pixel to the right of a page of the level
above, so the only thing telling the two levels apart was the hairline
on the left of the list. That was harmless while every page came before
every section, but a page can sit after a section now, and it read as
one more page of that section.

The pages of a section are indented by 0.75rem, which puts them 13px in
instead of 1px, and a section block keeps a little room below it. Both
are scoped to a real section, so a virtual section still renders its
pages at the level of its parent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kkjvqifo7fQ5W6woRWiSW
---
 .changeset/spotty-jars-smash.md    | 11 +++++++++++
 packages/markdown/assets/shell.css |  4 ++++
 website/en/book/changelog.md       |  2 ++
 3 files changed, 17 insertions(+)
 create mode 100644 .changeset/spotty-jars-smash.md

diff --git a/.changeset/spotty-jars-smash.md b/.changeset/spotty-jars-smash.md
new file mode 100644
index 000000000..15fe8c97b
--- /dev/null
+++ b/.changeset/spotty-jars-smash.md
@@ -0,0 +1,11 @@
+---
+"@hyperbook/markdown": patch
+"hyperbook": patch
+"hyperbook-studio": patch
+---
+
+Indent the pages of a section in the navigation. They sat one pixel to the
+right of a page of the level above, so only a hairline told the two levels
+apart. That was harmless while every page came before every section, but a page
+can sit after a section now, and it has to be readable as a page of the level
+above.
diff --git a/packages/markdown/assets/shell.css b/packages/markdown/assets/shell.css
index 200dca032..2ed647c6a 100644
--- a/packages/markdown/assets/shell.css
+++ b/packages/markdown/assets/shell.css
@@ -669,6 +669,7 @@ nav li + li {
 
 .section {
   margin-top: 4px;
+  margin-bottom: 4px;
 }
 
 .section summary.name {
@@ -740,6 +741,9 @@ nav li + li {
 .section > .links {
   border-left-width: 1px;
   border-left-style: solid;
+  /* The pages of a section have to read as belonging to it, now that a page of
+     the level above can follow them. */
+  padding-left: 0.75rem;
 }
 
 .pages {
diff --git a/website/en/book/changelog.md b/website/en/book/changelog.md
index b3718aebb..05a31fb30 100644
--- a/website/en/book/changelog.md
+++ b/website/en/book/changelog.md
@@ -45,6 +45,8 @@ If you need a new feature, open an [issue](https://github.com/openpatch/hyperboo
 
 :::tab{title="New :rocket:" id="new"}
 
+**navigation**: The pages of a section are indented, so they read as belonging to it when a page of the level above follows them.
+
 **navigation**: A section can sit between two pages, and a page can sit after a section. The `index` of a page and the `index` of a section are one order now, instead of pages always coming first. Without an `index` nothing moves: pages still come before sections.
 
 **emoji**: Emojis can be rendered as images, so they look the same on every platform instead of being drawn with the emoji font of the reader's operating system. Set `elements.emoji.style` to `twemoji` in your `hyperbook.json`. Only the emojis your book uses end up in your build.

From dbf4508209a76da002e9948efb5d33b6dc075f2b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 11:49:48 +0000
Subject: [PATCH 5/7] Order pages and subsections together inside a section too

Only the top level of the navigation shared one order. Inside a section
the subsections were still rendered after every page of that section, so
a subsection could not sit between two pages, and the sidebar disagreed
with the previous and next buttons, which already followed the index.

One function renders a level now and calls itself through the section it
renders, which also drops the second copy of the merge that existed for
sections shown as a page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kkjvqifo7fQ5W6woRWiSW
---
 .changeset/quiet-jokes-melt.md              |  10 ++
 packages/markdown/src/rehypeShell.ts        | 183 ++++++++------------
 packages/markdown/tests/rehypeShell.test.ts |  16 ++
 website/en/book/changelog.md                |   2 +-
 4 files changed, 99 insertions(+), 112 deletions(-)
 create mode 100644 .changeset/quiet-jokes-melt.md

diff --git a/.changeset/quiet-jokes-melt.md b/.changeset/quiet-jokes-melt.md
new file mode 100644
index 000000000..0f771e5fb
--- /dev/null
+++ b/.changeset/quiet-jokes-melt.md
@@ -0,0 +1,10 @@
+---
+"@hyperbook/markdown": patch
+"hyperbook": patch
+"hyperbook-studio": patch
+---
+
+Order the pages and the subsections of a section together too. Only the top
+level of the navigation shared one order, so inside a section a subsection was
+still rendered after every page of that section, and the sidebar disagreed with
+the previous and next buttons, which already followed the index.
diff --git a/packages/markdown/src/rehypeShell.ts b/packages/markdown/src/rehypeShell.ts
index 670fc84f7..6ed68179c 100644
--- a/packages/markdown/src/rehypeShell.ts
+++ b/packages/markdown/src/rehypeShell.ts
@@ -322,6 +322,46 @@ const makeNavigationSectionAsPageElement = (
   };
 };
 
+/**
+ * Renders one level of the navigation. Pages and sections share one order, so
+ * a section can sit between two pages. A run of pages becomes one list, and a
+ * section breaks the run.
+ */
+const makeNavigationLevel = (
+  ctx: HyperbookContext,
+  pages: HyperbookPage[],
+  sections: HyperbookSection[],
+  listClass?: string,
+): ElementContent[] => {
+  const elements: ElementContent[] = [];
+  let list: ElementContent[] | null = null;
+  const addToList = (element: ElementContent) => {
+    if (!list) {
+      list = [];
+      elements.push({
+        type: "element",
+        tagName: "ul",
+        properties: listClass ? { class: listClass } : {},
+        children: list,
+      });
+    }
+    list.push(element);
+  };
+
+  for (const entry of sortNavigation(pages, sections)) {
+    if (entry.type === "page") {
+      addToList(makeNavigationPageElement(ctx, entry.page));
+    } else if (entry.section.navigation === "page") {
+      addToList(makeNavigationSectionAsPageElement(ctx, entry.section));
+    } else {
+      elements.push(makeNavigationSectionElement(ctx, entry.section));
+      list = null;
+    }
+  }
+
+  return elements;
+};
+
 const makeNavigationSectionElement = (
   ctx: HyperbookContext,
   section: HyperbookSection,
@@ -333,68 +373,20 @@ const makeNavigationSectionElement = (
   const isExpanded = navigation === "expanded" || (navigation === undefined && expanded) || 
     ctx.navigation.current?.href?.startsWith(href || "");
 
-  const pagesElements: ElementContent[] = pages
-    .filter((page) => !page.hide && page.navigation !== "hidden" && page.href !== href)
-    .map((page) => makeNavigationPageElement(ctx, page));
-
-  const linksElements: ElementContent[] = [];
-  if (pagesElements.length > 0) {
-    linksElements.push({
-      type: "element",
-      tagName: "ul",
-      properties: {
-        class: "pages",
-      },
-      children: pagesElements,
-    });
-  }
-
-  // Handle page-mode sections - they should be rendered as pages in the pages list
-  const pageModeChildSections = sections
-    .filter((s) => !s.hide && s.navigation !== "hidden" && s.navigation === "page" && !s.isEmpty);
-  
-  // Merge pages and page-mode sections, sort by index
-  if (pageModeChildSections.length > 0) {
-    // We need to combine the existing pages with page-mode sections
-    const combinedItems: { index?: number; name: string; element: ElementContent }[] = [
-      ...pages
-        .filter((page) => !page.hide && page.navigation !== "hidden" && page.href !== href)
-        .map((page) => ({ 
-          index: page.index, 
-          name: page.name, 
-          element: makeNavigationPageElement(ctx, page) 
-        })),
-      ...pageModeChildSections.map((s) => ({ 
-        index: s.index, 
-        name: s.name, 
-        element: makeNavigationSectionAsPageElement(ctx, s) 
-      })),
-    ].sort((a, b) => {
-      const aIndex = a.index !== undefined ? a.index : 9999;
-      const bIndex = b.index !== undefined ? b.index : 9999;
-      if (aIndex !== bIndex) return aIndex - bIndex;
-      return a.name > b.name ? 1 : -1;
-    });
-
-    // Replace pagesElements with combined sorted elements
-    linksElements.length = 0; // Clear existing
-    if (combinedItems.length > 0) {
-      linksElements.push({
-        type: "element",
-        tagName: "ul",
-        properties: {
-          class: "pages",
-        },
-        children: combinedItems.map((item) => item.element),
-      });
-    }
-  }
-
-  // Regular sections (not page-mode)
-  const sectionElements: ElementContent[] = sections
-    .filter((s) => !s.hide && s.navigation !== "hidden" && s.navigation !== "page")
-    .map((s) => makeNavigationSectionElement(ctx, s));
-  linksElements.push(...sectionElements);
+  const linksElements = makeNavigationLevel(
+    ctx,
+    pages.filter(
+      (page) =>
+        !page.hide && page.navigation !== "hidden" && page.href !== href,
+    ),
+    sections.filter(
+      (s) =>
+        !s.hide &&
+        s.navigation !== "hidden" &&
+        (s.navigation !== "page" || !s.isEmpty),
+    ),
+    "pages",
+  );
 
   // For virtual sections, just render the links without a container
   if (isVirtual) {
@@ -484,55 +476,24 @@ const makeNavigationSectionElement = (
   };
 };
 
-const makeNavigationElements = (ctx: HyperbookContext): ElementContent[] => {
-  const pages = ctx.navigation.pages.filter(
-    (p) => !p.hide && p.navigation !== "hidden",
-  );
-  const sections = ctx.navigation.sections.filter(
-    (s) =>
-      !s.hide &&
-      s.navigation !== "hidden" &&
-      // A section shown as a page needs a page to link to.
-      (s.navigation !== "page" || !s.isEmpty),
-  );
-
-  // Pages and sections share one order, so a section can sit between two
-  // pages. A run of pages becomes one list, a section breaks the run.
-  const children: ElementContent[] = [];
-  let list: ElementContent[] | null = null;
-  const addToList = (element: ElementContent) => {
-    if (!list) {
-      list = [];
-      children.push({
-        type: "element",
-        tagName: "ul",
-        properties: {},
-        children: list,
-      });
-    }
-    list.push(element);
-  };
-
-  for (const entry of sortNavigation(pages, sections)) {
-    if (entry.type === "page") {
-      addToList(makeNavigationPageElement(ctx, entry.page));
-    } else if (entry.section.navigation === "page") {
-      addToList(makeNavigationSectionAsPageElement(ctx, entry.section));
-    } else {
-      children.push(makeNavigationSectionElement(ctx, entry.section));
-      list = null;
-    }
-  }
-
-  return [
-    {
-      type: "element",
-      tagName: "nav",
-      properties: {},
-      children,
-    },
-  ];
-};
+const makeNavigationElements = (ctx: HyperbookContext): ElementContent[] => [
+  {
+    type: "element",
+    tagName: "nav",
+    properties: {},
+    children: makeNavigationLevel(
+      ctx,
+      ctx.navigation.pages.filter((p) => !p.hide && p.navigation !== "hidden"),
+      ctx.navigation.sections.filter(
+        (s) =>
+          !s.hide &&
+          s.navigation !== "hidden" &&
+          // A section shown as a page needs a page to link to.
+          (s.navigation !== "page" || !s.isEmpty),
+      ),
+    ),
+  },
+];
 
 const makeMetaElements = (ctx: HyperbookContext): ElementContent[] => {
   const elements: ElementContent[] = [];
diff --git a/packages/markdown/tests/rehypeShell.test.ts b/packages/markdown/tests/rehypeShell.test.ts
index d8103bd95..3dde388fe 100644
--- a/packages/markdown/tests/rehypeShell.test.ts
+++ b/packages/markdown/tests/rehypeShell.test.ts
@@ -390,6 +390,22 @@ describe("rehypeShell", () => {
       ).toEqual(["apple", "zebra", "alpha", "beta"]);
     });
 
+    it("puts a subsection between two pages of its section", () => {
+      // The pages of a section and its subsections share one order too, so the
+      // sidebar keeps agreeing with the previous and next buttons.
+      expect(
+        order({
+          sections: [
+            {
+              ...section("outer", 1),
+              pages: [page("early", 1), page("late", 3)],
+              sections: [section("middle", 2)],
+            },
+          ],
+        }),
+      ).toEqual(["outer", "early", "middle", "late"]);
+    });
+
     it("puts a page before a section that shares its index", () => {
       expect(
         order({
diff --git a/website/en/book/changelog.md b/website/en/book/changelog.md
index 05a31fb30..442bc6acb 100644
--- a/website/en/book/changelog.md
+++ b/website/en/book/changelog.md
@@ -47,7 +47,7 @@ If you need a new feature, open an [issue](https://github.com/openpatch/hyperboo
 
 **navigation**: The pages of a section are indented, so they read as belonging to it when a page of the level above follows them.
 
-**navigation**: A section can sit between two pages, and a page can sit after a section. The `index` of a page and the `index` of a section are one order now, instead of pages always coming first. Without an `index` nothing moves: pages still come before sections.
+**navigation**: A section can sit between two pages, and a page can sit after a section. This works at every level, so a subsection can sit between two pages of its section. The `index` of a page and the `index` of a section are one order now, instead of pages always coming first. Without an `index` nothing moves: pages still come before sections.
 
 **emoji**: Emojis can be rendered as images, so they look the same on every platform instead of being drawn with the emoji font of the reader's operating system. Set `elements.emoji.style` to `twemoji` in your `hyperbook.json`. Only the emojis your book uses end up in your build.
 

From 1aff77f0068ce4a602b8af43fb9313cd1f577f81 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 11:57:24 +0000
Subject: [PATCH 6/7] Move the changelog entries of this branch to their own
 release

The entries were written while the previous release was still open. That
release has shipped, so the drawers, the first paint and the navigation
order belong to the next one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kkjvqifo7fQ5W6woRWiSW
---
 website/en/book/changelog.md | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/website/en/book/changelog.md b/website/en/book/changelog.md
index 442bc6acb..671a5b14a 100644
--- a/website/en/book/changelog.md
+++ b/website/en/book/changelog.md
@@ -39,15 +39,37 @@ If you need a new feature, open an [issue](https://github.com/openpatch/hyperboo
 ::::
 -->
 
-## v0.101.0
+## v0.102.0
 
 ::::tabs
 
 :::tab{title="New :rocket:" id="new"}
 
+**navigation**: A section can sit between two pages, and a page can sit after a section. This works at every level, so a subsection can sit between two pages of its section. The `index` of a page and the `index` of a section are one order now, instead of pages always coming first. Without an `index` nothing moves: pages still come before sections.
+
+:::
+
+:::tab{title="Improved :+1:" id="improved"}
+
 **navigation**: The pages of a section are indented, so they read as belonging to it when a page of the level above follows them.
 
-**navigation**: A section can sit between two pages, and a page can sit after a section. This works at every level, so a subsection can sit between two pages of its section. The `index` of a page and the `index` of a section are one order now, instead of pages always coming first. Without an `index` nothing moves: pages still come before sections.
+:::
+
+:::tab{title="Fixed :bug:" id="fixed"}
+
+**shell**: The search and table of contents drawers no longer flash over the page for a moment while it loads.
+
+**shell**: Pages paint sooner. The script that loads the light and dark stylesheets is part of the page now, instead of a file that had to be fetched before anything could be drawn.
+
+:::
+
+::::
+
+## v0.101.0
+
+::::tabs
+
+:::tab{title="New :rocket:" id="new"}
 
 **emoji**: Emojis can be rendered as images, so they look the same on every platform instead of being drawn with the emoji font of the reader's operating system. Set `elements.emoji.style` to `twemoji` in your `hyperbook.json`. Only the emojis your book uses end up in your build.
 
@@ -67,10 +89,6 @@ If you need a new feature, open an [issue](https://github.com/openpatch/hyperboo
 
 **bookmarks**: A heading that contains a quote or a backslash can be bookmarked again.
 
-**shell**: The search and table of contents drawers no longer flash over the page for a moment while it loads.
-
-**shell**: Pages paint sooner. The script that loads the light and dark stylesheets is part of the page now, instead of a file that had to be fetched before anything could be drawn.
-
 :::
 
 ::::

From 7021ec0c03c66c503951955b0b3eb23de8d649f6 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 12:10:21 +0000
Subject: [PATCH 7/7] Merge the navigation lists instead of sorting them

sortNavigation concatenated the pages and the sections and sorted the
result, which reordered a list a caller had already put in order. Reading
a hyperbook orders both lists, so the only thing left to do is weave them
together. It merges them now, which keeps each list as it was given and
still lets an index place a section between two pages.

This restores the order the page list produces for a virtual section,
where the pages are kept as they are instead of the section's own page
being pulled to the front.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012kkjvqifo7fQ5W6woRWiSW
---
 packages/markdown/tests/rehypeShell.test.ts |  5 +-
 packages/types/src/index.ts                 | 76 +++++++++++++--------
 2 files changed, 51 insertions(+), 30 deletions(-)

diff --git a/packages/markdown/tests/rehypeShell.test.ts b/packages/markdown/tests/rehypeShell.test.ts
index 3dde388fe..8b1a94ea5 100644
--- a/packages/markdown/tests/rehypeShell.test.ts
+++ b/packages/markdown/tests/rehypeShell.test.ts
@@ -382,10 +382,11 @@ describe("rehypeShell", () => {
     });
 
     it("keeps pages before sections when nothing has an index", () => {
+      // Both lists arrive in order, so the navigation only weaves them.
       expect(
         order({
-          pages: [page("zebra"), page("apple")],
-          sections: [section("beta"), section("alpha")],
+          pages: [page("apple"), page("zebra")],
+          sections: [section("alpha"), section("beta")],
         }),
       ).toEqual(["apple", "zebra", "alpha", "beta"]);
     });
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index 9224d85da..d4eb5f897 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -280,39 +280,59 @@ const isShownAsPage = (section: HyperbookSection): boolean =>
  * order. `index` decides, across both of them, so a section can sit between
  * two pages. Entries without an `index` fall back to pages before sections,
  * and entries that end up equal are ordered by name.
+ *
+ * Both lists are expected to be in order already, which is what reading a
+ * hyperbook gives. They are merged rather than sorted, so the order a caller
+ * built stays intact and only the two lists are woven together.
  */
 export const sortNavigation = (
   pages: HyperbookPage[],
   sections: HyperbookSection[],
 ): NavigationEntry[] => {
-  const entries: {
-    entry: NavigationEntry;
-    index: number;
-    /** Decides a tie on the index: a page comes before a section. */
-    kind: number;
-    name: string;
-  }[] = [
-    ...pages.map((page) => ({
-      entry: { type: "page" as const, page },
-      index: page.index ?? FALLBACK_INDEX_PAGE,
-      kind: 0,
-      name: page.name,
-    })),
-    ...sections.map((section) => ({
-      entry: { type: "section" as const, section },
-      index:
-        section.index ??
-        (isShownAsPage(section) ? FALLBACK_INDEX_PAGE : FALLBACK_INDEX_SECTION),
-      kind: isShownAsPage(section) ? 0 : 1,
-      name: section.name,
-    })),
-  ];
-
-  return entries
-    .sort((a, b) => (a.name > b.name ? 1 : -1))
-    .sort((a, b) => a.kind - b.kind)
-    .sort((a, b) => a.index - b.index)
-    .map(({ entry }) => entry);
+  const pageKey = (page: HyperbookPage) => ({
+    index: page.index ?? FALLBACK_INDEX_PAGE,
+    kind: 0,
+    name: page.name,
+  });
+  const sectionKey = (section: HyperbookSection) => ({
+    index:
+      section.index ??
+      (isShownAsPage(section) ? FALLBACK_INDEX_PAGE : FALLBACK_INDEX_SECTION),
+    kind: isShownAsPage(section) ? 0 : 1,
+    name: section.name,
+  });
+
+  const entries: NavigationEntry[] = [];
+  let p = 0;
+  let s = 0;
+
+  while (p < pages.length || s < sections.length) {
+    if (s >= sections.length) {
+      entries.push({ type: "page", page: pages[p++] });
+      continue;
+    }
+    if (p >= pages.length) {
+      entries.push({ type: "section", section: sections[s++] });
+      continue;
+    }
+
+    const page = pageKey(pages[p]);
+    const section = sectionKey(sections[s]);
+    const takePage =
+      page.index !== section.index
+        ? page.index < section.index
+        : page.kind !== section.kind
+          ? page.kind < section.kind
+          : page.name <= section.name;
+
+    if (takePage) {
+      entries.push({ type: "page", page: pages[p++] });
+    } else {
+      entries.push({ type: "section", section: sections[s++] });
+    }
+  }
+
+  return entries;
 };
 
 /**