@iyulab/canopy-page 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ Notable changes to canopy-page. The format follows
 The `settings.json` contract is what consuming projects plan their upgrades around, so changes
 to it — its fields, its validation, and what the checks reject — are what this file is about.
 
+## [0.6.0] — 2026-08-09
+
+### Added
+
+- **A `rehypePlugins` field**, naming installed rehype plugin packages to run on every page —
+  canopy's fixed extension point (after sanitize, before syntax highlighting) for markdown that
+  needs more than CommonMark and GFM, a diagram fence rendered to SVG being the case this exists
+  for. This site's own [guide to diagrams](https://iyulab.github.io/canopy-page/guide/writing/diagrams.html)
+  demonstrates it end to end, with [declart](https://github.com/iyulab/declart) rendered at build
+  time through `rehype-declart`.
+
+### Changed
+
+- **Upgraded to canopy 0.7.0**, the release `rehypePlugins` builds on. See
+  [canopy's changelog](https://github.com/iyulab/canopy/blob/main/CHANGELOG.md#070--2026-08-09)
+  for the plugin's fixed position and how it interacts with sanitizing and highlighting.
+
+## [0.5.0] — 2026-08-09
+
+### Added
+
+- **Search, wired up.** Every build now carries a search box in the top bar, a `Ctrl+K` /
+  `Cmd+K` shortcut to jump to it, and an on-page outline that highlights the section currently
+  in view while scrolling — all with no `settings.json` field to turn on, and all inert if a
+  reader's browser has scripts disabled.
+- **A dark/light toggle**, riding in the same script bundle. Remembers a reader's choice across
+  visits; without a stored choice, follows the system preference exactly as before.
+
+### Changed
+
+- **Upgraded to canopy 0.6.0.** The current page's sidebar entry is now highlighted, a reader
+  landing partway down a page can flip `data-theme` by hand, mobile navigation opens as a
+  full-screen panel instead of pushing the page down, an unlabeled or unrecognized code fence
+  highlights as plain text instead of falling back unstyled, and every page gains previous/next
+  links to its neighbors in the sidebar order — all on the next build, no `settings.json` field
+  changed. See
+  [canopy's changelog](https://github.com/iyulab/canopy/blob/main/CHANGELOG.md#060--2026-08-09)
+  for the underlying markup and CSS selector changes.
+
 ## [0.4.0] — 2026-08-08
 
 ### Changed

package/README.md

@@ -7,6 +7,9 @@ authoring pipeline around the rendering: the settings a site is configured by, t
 keep broken references from shipping, and the build that ties them together. The rendering
 itself is [canopy](https://github.com/iyulab/canopy)'s job, and canopy-page drives it.
 
+**Live docs**: <https://iyulab.github.io/canopy-page> — built with canopy-page itself, from the
+[`examples/site`](examples/site) in this repository, republished on every push to `main`.
+
 ---
 
 ## Why
@@ -23,6 +26,26 @@ the ones this package holds.
 - **One site, built in one pass.** Links and backlinks resolve across the whole of it, so a guide
   and the release notes it refers to stay connected.
 
+## What ships in every site
+
+No `settings.json` field turns these on — they are just there, on the next build. Reading a
+page never depends on any of the scripted ones: block scripts, or print the page, and only they
+go away.
+
+- **Search**, matching a query against every page's title, headings, and body — `Ctrl+K` /
+  `Cmd+K` jumps to it from anywhere
+- **The current page and section, marked** in the sidebar and the on-page outline, updating as
+  you scroll
+- **A dark/light toggle** that remembers a reader's choice; without one, pages follow the
+  system setting
+- **Prev/next cards** linking to a page's neighbors in the sidebar's own order, and **backlinks**
+  listing every page that points to it
+- **A full-screen menu on narrow screens**, rather than one that pushes the page's content down
+- **Sitemap and `robots.txt`**, once `siteUrl` is set
+
+See it live at <https://iyulab.github.io/canopy-page>, or read
+[What a reader gets](examples/site/guide/reading.md) for how each one behaves.
+
 ## Install
 
 ```sh
@@ -69,6 +92,7 @@ unpublished.
   "lang": "en-GB",
   "icon": "assets/favicon.png",
   "exclude": ["_drafts", "*.tmp"],
+  "rehypePlugins": ["rehype-declart"],
   "sections": [
     { "path": "guide", "label": "Guide", "items": [
       { "label": "Orders", "items": ["guide/orders/list", "guide/orders/detail"] },
@@ -90,6 +114,7 @@ unpublished.
 | `home` | A link back to the site this documentation sits beside: `{ url, label }`. Both are required together — naming half of it is not a valid setting. `url` must be an absolute http(s) URL; there is no default `label`, because link text has to be written in the site's own language. Absent: no link back to a surrounding site is rendered |
 | `siteUrl` | Absolute URL naming where the built site will stand. Every link canopy writes is relative, which is what lets a site be served from any sub-path — and exactly why a sitemap, whose entries must be absolute, needs this separately. **Only** when it is set does `build` write `sitemap.xml` and a `robots.txt` pointing at it. Absent: neither file is written |
 | `exclude` | Paths to leave unpublished: a directory (`_drafts` or `_drafts/**`), an extension at any depth (`*.tmp`), or one exact path. Patterns are relative to the settings file, and a shape outside that list — `images/*.md` — is refused rather than left to match nothing |
+| `rehypePlugins` | Package names of rehype plugins to run on every page, after canopy's own sanitize step and before syntax highlighting — canopy's fixed extension point for markdown that needs more than CommonMark and GFM, a diagram fence rendered to SVG being the case this exists for. Each entry is an installed package name (`"rehype-declart"`), never a filesystem path — a relative-looking entry is refused, since the directory it would resolve against is wherever the build happens to run from, not this file |
 | `sections` | Ordered regions of the site — see below |
 
 `tokens` is two blocks in practice, not one — a bare `:root` and a `prefers-color-scheme: dark`
@@ -215,6 +240,11 @@ door every other consumer uses, and a door only stays wide enough if the people
 gone around it do not. Where the command line cannot express something, that is worth raising
 with canopy rather than working around here.
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), including what a release has to update besides the
+version number.
+
 ## License
 
 MIT

package/dist/assets/scrollspy.css

@@ -0,0 +1,10 @@
+/* Scrollspy — pairs with assets/scrollspy.js. Styles the `.canopy-outline`
+   link whose section is currently in view. Reuses canopy's own tokens
+   (--accent, --font-weight-semibold) rather than introducing new ones, and
+   targets the standard `aria-current` attribute rather than a new class so
+   the same rule serves any script that sets it, not just this one. */
+
+.canopy-outline a[aria-current="location"] {
+  color: var(--accent);
+  font-weight: var(--font-weight-semibold);
+}

package/dist/assets/scrollspy.js

@@ -0,0 +1,98 @@
+/**
+ * canopy-page's on-page outline scrollspy — vanilla JS, no dependencies.
+ * Marks whichever `.canopy-outline` link points at the heading currently in
+ * view with `aria-current="location"`, the same attribute browsers already
+ * use for "current place in a set" (MDN: aria-current). No new class name,
+ * so a caller who wants to restyle it only needs `[aria-current="location"]`.
+ *
+ * `pickActive` is exposed for tests: it is the one piece of this file with
+ * real logic (choosing among several simultaneously-visible headings), and
+ * it needs no DOM to run.
+ */
+var CanopyScrollspy = (function () {
+  "use strict";
+
+  /**
+   * Given the outline's heading ids in document order and the subset
+   * currently intersecting the viewport, pick the one to mark current.
+   *
+   * The topmost visible heading wins — not the one with the largest
+   * intersection ratio, since a short section near the top of the viewport
+   * can be fully visible while a long section just below it is only
+   * fractionally visible, and a reader who just scrolled to that short
+   * section expects it, not its taller neighbor, to light up.
+   */
+  function pickActive(orderedIds, visibleIds) {
+    if (visibleIds.length === 0) return null;
+    var visible = new Set(visibleIds);
+    for (var i = 0; i < orderedIds.length; i++) {
+      if (visible.has(orderedIds[i])) return orderedIds[i];
+    }
+    return null;
+  }
+
+  function main() {
+    var outline = document.querySelector(".canopy-outline");
+    if (!outline) return;
+    var links = outline.querySelectorAll("a[href^='#']");
+    if (links.length === 0) return;
+
+    var orderedIds = [];
+    var linkById = {};
+    links.forEach(function (link) {
+      var id = link.getAttribute("href").slice(1);
+      orderedIds.push(id);
+      linkById[id] = link;
+    });
+
+    var headings = orderedIds
+      .map(function (id) {
+        return document.getElementById(id);
+      })
+      .filter(Boolean);
+    if (headings.length === 0) return;
+
+    if (typeof IntersectionObserver === "undefined") return;
+
+    var current = null;
+    function setCurrent(id) {
+      if (id === current) return;
+      if (current !== null && linkById[current]) {
+        linkById[current].removeAttribute("aria-current");
+      }
+      current = id;
+      if (current !== null && linkById[current]) {
+        linkById[current].setAttribute("aria-current", "location");
+      }
+    }
+
+    var visible = [];
+    var observer = new IntersectionObserver(
+      function (entries) {
+        entries.forEach(function (entry) {
+          var id = entry.target.id;
+          var at = visible.indexOf(id);
+          if (entry.isIntersecting) {
+            if (at === -1) visible.push(id);
+          } else if (at !== -1) {
+            visible.splice(at, 1);
+          }
+        });
+        setCurrent(pickActive(orderedIds, visible));
+      },
+      // A heading counts as "in view" while it sits in a band from the
+      // upper tenth to the upper third of the viewport — narrow enough that
+      // a reader scrolling past a short section still sees it light up, but
+      // wide enough to actually be a non-empty band (top + bottom margins
+      // here must sum to under 100%, or the observed strip is zero-height).
+      { rootMargin: "-10% 0px -70% 0px" },
+    );
+    headings.forEach(function (heading) {
+      observer.observe(heading);
+    });
+  }
+
+  if (typeof document !== "undefined") main();
+
+  return { pickActive: pickActive };
+})();

package/dist/assets/search.css

@@ -0,0 +1,53 @@
+/* Search UI — pairs with assets/search.js and the `.canopy-search` form
+   canopy's shell emits. Loaded only when a build carries both, so a site
+   with no search never pays for this either. Reuses canopy's own tokens
+   (--sp-*, --border, --radius-m, --bg-primary, --text-*) rather than
+   introducing new ones. */
+
+.canopy-search {
+  position: relative;
+}
+
+.canopy-search-results {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  z-index: 10;
+  margin: var(--sp-2) 0 0;
+  padding: var(--sp-2) 0;
+  width: min(24rem, 90vw);
+  max-height: 60vh;
+  overflow-y: auto;
+  list-style: none;
+  background: var(--bg-primary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-m);
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
+}
+
+.canopy-search-results li {
+  padding: var(--sp-2) var(--sp-3);
+}
+
+.canopy-search-results li.is-active,
+.canopy-search-results li:hover {
+  background: var(--bg-secondary);
+}
+
+.canopy-search-results a {
+  display: block;
+  font-weight: var(--font-weight-semibold);
+  color: var(--text-normal);
+  text-decoration: none;
+}
+
+.canopy-search-snippet {
+  margin: var(--sp-1, 4px) 0 0;
+  font-size: 0.85em;
+  color: var(--text-muted);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}

package/dist/assets/search.js

@@ -0,0 +1,220 @@
+/**
+ * canopy-page's client search — vanilla JS, no dependencies. Wires the
+ * `.canopy-search` form canopy's shell emits when `--search-index` and
+ * `--script` are both given.
+ *
+ * Substring matching, not stemming: Korean attaches particles to a word stem
+ * (주문 -> 주문을/주문이), so a substring search already finds the stem
+ * inside the inflected form — English queries use the same code path.
+ *
+ * One global (`CanopySearch`), so this adds exactly one name to whatever
+ * page carries it. `searchIndex` is exposed for tests, which load and
+ * evaluate this exact file rather than reimplementing it (search-ui.test.ts).
+ */
+var CanopySearch = (function () {
+  "use strict";
+
+  function normalize(s) {
+    return s.normalize("NFC").toLowerCase();
+  }
+
+  /**
+   * Score one entry against a query's terms. Every term has to appear
+   * somewhere (title, a heading, or the body) or the entry is dropped — an
+   * OR across terms would surface pages matching none of what was typed.
+   */
+  function scoreEntry(entry, terms) {
+    var title = normalize(entry.t);
+    var headings = entry.h.map(normalize);
+    var body = normalize(entry.b);
+    var score = 0;
+    for (var i = 0; i < terms.length; i++) {
+      var term = terms[i];
+      var inTitle = title.indexOf(term) !== -1;
+      var inHeading = headings.some(function (h) {
+        return h.indexOf(term) !== -1;
+      });
+      var inBody = body.indexOf(term) !== -1;
+      if (!inTitle && !inHeading && !inBody) return 0;
+      if (inTitle) score += 3;
+      if (inHeading) score += 2;
+      if (inBody) score += 1;
+    }
+    return score;
+  }
+
+  /** A short excerpt around the first matched term, for the result list. */
+  function snippet(entry, terms) {
+    var body = entry.b;
+    var lower = normalize(body);
+    var at = -1;
+    for (var i = 0; i < terms.length; i++) {
+      at = lower.indexOf(terms[i]);
+      if (at !== -1) break;
+    }
+    if (at === -1) return body.slice(0, 100);
+    var start = Math.max(0, at - 40);
+    var end = Math.min(body.length, at + 60);
+    return (start > 0 ? "…" : "") + body.slice(start, end) + (end < body.length ? "…" : "");
+  }
+
+  /** Search `entries` (the parsed search-index.json) for `query`. */
+  function searchIndex(entries, query, limit) {
+    var terms = normalize(query).split(/\s+/).filter(Boolean);
+    if (terms.length === 0) return [];
+    var results = [];
+    for (var i = 0; i < entries.length; i++) {
+      var score = scoreEntry(entries[i], terms);
+      if (score > 0) {
+        results.push({ entry: entries[i], score: score, snippet: snippet(entries[i], terms) });
+      }
+    }
+    results.sort(function (a, b) {
+      return b.score - a.score;
+    });
+    return results.slice(0, limit || 10);
+  }
+
+  // DOM wiring below is skipped outside a browser, so this file stays
+  // loadable in a plain Node sandbox for the test above.
+
+  var SCRIPT_SRC =
+    typeof document !== "undefined" && document.currentScript ? document.currentScript.src : "";
+
+  function main() {
+    var form = document.querySelector(".canopy-search");
+    var input = form ? form.querySelector("input[type=search]") : null;
+    if (!form || !input) return;
+
+    // canopy always writes this script to assets/script.js at the site root
+    // and links it relatively, so the resolved URL minus that suffix is the
+    // site root — the same root the index and every result link resolve
+    // against.
+    var root = SCRIPT_SRC.replace(/assets\/script\.js(\?.*)?$/, "");
+    var indexUrl = root + "search-index.json";
+
+    var list = document.createElement("ul");
+    list.className = "canopy-search-results";
+    list.hidden = true;
+    list.setAttribute("role", "listbox");
+    form.appendChild(list);
+
+    var indexPromise = null;
+    function loadIndex() {
+      if (!indexPromise) {
+        indexPromise = fetch(indexUrl).then(function (response) {
+          if (!response.ok) throw new Error("search index request failed");
+          return response.json();
+        });
+      }
+      return indexPromise;
+    }
+
+    var active = -1;
+
+    function render(results) {
+      active = -1;
+      list.textContent = "";
+      if (results.length === 0) {
+        list.hidden = true;
+        return;
+      }
+      results.forEach(function (result) {
+        var item = document.createElement("li");
+        item.setAttribute("role", "option");
+        var link = document.createElement("a");
+        link.href = root + result.entry.p;
+        link.textContent = result.entry.t;
+        var preview = document.createElement("p");
+        preview.className = "canopy-search-snippet";
+        preview.textContent = result.snippet;
+        item.appendChild(link);
+        item.appendChild(preview);
+        list.appendChild(item);
+      });
+      list.hidden = false;
+    }
+
+    var pending;
+    function handleInput() {
+      var query = input.value;
+      clearTimeout(pending);
+      pending = setTimeout(function () {
+        if (query.trim() === "") {
+          render([]);
+          return;
+        }
+        loadIndex()
+          .then(function (entries) {
+            render(searchIndex(entries, query, 10));
+          })
+          .catch(function () {
+            list.textContent = "";
+            var item = document.createElement("li");
+            item.textContent = "Search failed to load.";
+            list.appendChild(item);
+            list.hidden = false;
+          });
+      }, 120);
+    }
+
+    function setActive(index) {
+      var items = list.children;
+      if (active >= 0 && items[active]) items[active].classList.remove("is-active");
+      active = index;
+      if (active >= 0 && items[active]) {
+        items[active].classList.add("is-active");
+        items[active].scrollIntoView({ block: "nearest" });
+      }
+    }
+
+    function handleKeydown(event) {
+      if (list.hidden || list.children.length === 0) return;
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        setActive((active + 1) % list.children.length);
+      } else if (event.key === "ArrowUp") {
+        event.preventDefault();
+        setActive((active - 1 + list.children.length) % list.children.length);
+      } else if (event.key === "Enter") {
+        var target = active >= 0 ? list.children[active] : list.children[0];
+        var link = target && target.querySelector("a");
+        if (link) {
+          event.preventDefault();
+          location.href = link.href;
+        }
+      } else if (event.key === "Escape") {
+        render([]);
+      }
+    }
+
+    input.addEventListener("focus", loadIndex, { once: true });
+    input.addEventListener("input", handleInput);
+    input.addEventListener("keydown", handleKeydown);
+    document.addEventListener("click", function (event) {
+      if (!form.contains(event.target)) list.hidden = true;
+    });
+
+    // Ctrl+K / Cmd+K jumps to search from anywhere on the page — the
+    // convention readers already know from editors and other doc sites.
+    // Global rather than scoped to the form, since the point is not having
+    // to click the form first.
+    document.addEventListener("keydown", function (event) {
+      var key = (event.key || "").toLowerCase();
+      if ((event.ctrlKey || event.metaKey) && key === "k") {
+        event.preventDefault();
+        input.focus();
+        input.select();
+      }
+    });
+
+    // A script that ran this far is a script that can wire the form up —
+    // reveal it now, and not before, so a build with no script attached
+    // (or one that throws before this point) never shows a dead control.
+    form.hidden = false;
+  }
+
+  if (typeof document !== "undefined") main();
+
+  return { searchIndex: searchIndex };
+})();

package/dist/assets/theme-toggle.js

@@ -0,0 +1,87 @@
+/**
+ * canopy-page's dark/light toggle — vanilla JS, no dependencies. Wires the
+ * `.canopy-theme-toggle` hidden button canopy's shell always carries when a
+ * top bar exists, and flips `data-theme` on `<html>`, the attribute canopy's
+ * own stylesheet reads to override `prefers-color-scheme` (see canopy's
+ * tokens.ts).
+ *
+ * `effectiveTheme` and `nextTheme` are exposed for tests, which is also why
+ * the resolution logic is split out as pure functions taking primitives
+ * rather than reading `matchMedia`/`data-theme` inline — the same shape
+ * search.js's `searchIndex` and scrollspy.js's `pickActive` already use.
+ */
+var CanopyThemeToggle = (function () {
+  "use strict";
+
+  var STORAGE_KEY = "canopy-theme";
+
+  /**
+   * The theme actually in effect right now: an explicit data-theme
+   * attribute if one is set, otherwise the system preference. This is the
+   * "current" a click toggles away from — computing it fresh (rather than
+   * trusting a stored value) is what makes a first click always flip the
+   * theme the reader is actually looking at, even if that reader never
+   * clicked before and nothing was ever stored.
+   */
+  function effectiveTheme(dataThemeAttr, systemPrefersDark) {
+    if (dataThemeAttr === "dark" || dataThemeAttr === "light") return dataThemeAttr;
+    return systemPrefersDark ? "dark" : "light";
+  }
+
+  /** The theme a click moves to: simply the other one. */
+  function nextTheme(current) {
+    return current === "dark" ? "light" : "dark";
+  }
+
+  function systemPrefersDark() {
+    return typeof matchMedia === "function" && matchMedia("(prefers-color-scheme: dark)").matches;
+  }
+
+  // Storage access can throw (private browsing with storage disabled, a
+  // strict cookie/storage policy) — every call here is wrapped so that a
+  // reader who cannot persist a preference still gets a fully working
+  // toggle for the rest of the session, just not a remembered one.
+  function readStored() {
+    try {
+      return localStorage.getItem(STORAGE_KEY);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function writeStored(theme) {
+    try {
+      localStorage.setItem(STORAGE_KEY, theme);
+    } catch (e) {
+      // Nothing to recover: the theme is still applied for this page view.
+    }
+  }
+
+  function main() {
+    var button = document.querySelector(".canopy-theme-toggle");
+    if (!button) return;
+
+    var stored = readStored();
+    if (stored === "dark" || stored === "light") {
+      document.documentElement.setAttribute("data-theme", stored);
+    }
+
+    button.addEventListener("click", function () {
+      var current = effectiveTheme(
+        document.documentElement.getAttribute("data-theme"),
+        systemPrefersDark(),
+      );
+      var theme = nextTheme(current);
+      document.documentElement.setAttribute("data-theme", theme);
+      writeStored(theme);
+    });
+
+    // A script that ran this far can wire the button up — reveal it now,
+    // and not before, the same reasoning search.js's form reveal uses.
+    button.hidden = false;
+  }
+
+  if (typeof document !== "undefined") main();
+
+  return { effectiveTheme: effectiveTheme, nextTheme: nextTheme };
+})();

package/dist/assets-bundle.d.ts

@@ -0,0 +1,8 @@
+/** The single script every canopy-page site carries via canopy's `--script`. */
+export declare function assembleScript(): Promise<string>;
+/**
+ * CSS canopy-page contributes on top of a site's own tokens, carried via
+ * canopy's `--tokens-css` — the same channel a site's own `settings.tokens`
+ * already uses, so no new canopy surface is needed for this either.
+ */
+export declare function assembleTokensCss(userTokensCss: string | undefined): Promise<string>;

package/dist/assets-bundle.js

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Assembling canopy-page's own client-side surface for a build.
+ *
+ * canopy carries at most one `--script` and one `--tokens-css`, so every UI
+ * feature canopy-page ships (search, the outline scrollspy, and whatever
+ * follows) has to land in those two files rather than one each. Reading the
+ * pieces here — rather than at each call site — keeps the list of what
+ * ships in one place: adding a feature means adding one line below, not
+ * hunting for every place a script or stylesheet gets assembled.
+ *
+ * Resolved relative to this module rather than `process.cwd()`, so it finds
+ * `assets/` next to itself whether it is running as `src/assets-bundle.ts`
+ * (tests, dev) or the compiled `dist/assets-bundle.js` (published package) —
+ * `copy-assets.mjs` copies `src/assets` to `dist/assets` in the same
+ * position relative to the compiled output.
+ */
+const ASSETS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "assets");
+async function readAsset(name) {
+    return readFile(path.join(ASSETS_DIR, name), "utf8");
+}
+/** The single script every canopy-page site carries via canopy's `--script`. */
+export async function assembleScript() {
+    const [search, scrollspy, themeToggle] = await Promise.all([
+        readAsset("search.js"),
+        readAsset("scrollspy.js"),
+        readAsset("theme-toggle.js"),
+    ]);
+    return `${search}\n${scrollspy}\n${themeToggle}`;
+}
+/**
+ * CSS canopy-page contributes on top of a site's own tokens, carried via
+ * canopy's `--tokens-css` — the same channel a site's own `settings.tokens`
+ * already uses, so no new canopy surface is needed for this either.
+ */
+export async function assembleTokensCss(userTokensCss) {
+    const [search, scrollspy] = await Promise.all([readAsset("search.css"), readAsset("scrollspy.css")]);
+    const own = `${search}\n${scrollspy}`;
+    return userTokensCss === undefined ? own : `${userTokensCss}\n${own}`;
+}

package/dist/build.d.ts

@@ -14,14 +14,21 @@ export interface BuildOptions {
     /** Directory to write the site into. */
     out: string;
 }
+/** Assembled search/UI assets, written to real files so canopy's CLI can read them. */
+export interface SearchAssets {
+    /** Absolute path to the assembled tokens CSS (a site's own tokens, plus canopy-page's). */
+    tokensCssPath: string;
+    /** Absolute path to the assembled client script (search, scrollspy, ...). */
+    scriptPath: string;
+}
 /**
  * Translate settings into canopy's arguments.
  *
  * Everything a settings file says about the site itself is already something
  * canopy takes: this is a translation, not a layer of behaviour of its own. The
- * navigation spec is the one thing that has to be materialized, since canopy
- * reads it from a file.
+ * navigation spec and `searchAssets` are the things that have to be materialized
+ * first, since canopy reads all three from files.
  */
-export declare function canopyArgs(site: Awaited<ReturnType<typeof loadSite>>, out: string, navPath: string | undefined): string[];
+export declare function canopyArgs(site: Awaited<ReturnType<typeof loadSite>>, out: string, navPath: string | undefined, searchAssets: SearchAssets): string[];
 /** Build the site in `dir` into `out`, returning the exit code to leave with. */
 export declare function buildSite({ dir, out }: BuildOptions): Promise<number>;

package/dist/build.js

@@ -1,6 +1,7 @@
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { assembleScript, assembleTokensCss } from "./assets-bundle.js";
 import { runCanopy } from "./canopy.js";
 import { siteFindings } from "./check.js";
 import { listHtmlFiles, robotsTxt, sitemapXml } from "./sitemap.js";
@@ -10,10 +11,10 @@ import { loadSite, reportFindings } from "./site.js";
  *
  * Everything a settings file says about the site itself is already something
  * canopy takes: this is a translation, not a layer of behaviour of its own. The
- * navigation spec is the one thing that has to be materialized, since canopy
- * reads it from a file.
+ * navigation spec and `searchAssets` are the things that have to be materialized
+ * first, since canopy reads all three from files.
  */
-export function canopyArgs(site, out, navPath) {
+export function canopyArgs(site, out, navPath, searchAssets) {
     const { settings } = site;
     return [
         "build",
@@ -23,23 +24,33 @@ export function canopyArgs(site, out, navPath) {
         ...(settings.description === undefined ? [] : ["--site-description", settings.description]),
         ...(settings.lang === undefined ? [] : ["--lang", settings.lang]),
         ...(settings.icon === undefined ? [] : ["--site-icon", settings.icon]),
-        // canopy resolves --tokens-css against the working directory rather than the
-        // vault, so it gets an absolute path — unlike --site-icon just above.
-        ...(settings.tokens === undefined
-            ? []
-            : ["--tokens-css", path.join(site.root, settings.tokens)]),
+        // Always present: canopy-page's own CSS (search, scrollspy) rides here
+        // whether or not the site names a tokens file of its own (assembleTokensCss
+        // folds one into the other before this ever runs) — no settings field for
+        // this, matching the minimal-configuration principle Wave 2 already set.
+        "--tokens-css",
+        searchAssets.tokensCssPath,
         ...(settings.logo === undefined ? [] : ["--site-logo", settings.logo]),
         ...(settings.home === undefined
             ? []
             : ["--home-url", settings.home.url, "--home-label", settings.home.label]),
         ...(navPath === undefined ? [] : ["--nav", navPath]),
+        // Always on, same reasoning as --tokens-css above: a search index and the
+        // script that searches it are canopy-page's own contribution, not a site
+        // author's choice to make.
+        "--search-index",
+        "search-index.json",
+        "--script",
+        searchAssets.scriptPath,
         // The settings file is configuration rather than content, and canopy has no
         // reason to know it exists; excluding it keeps it off the published site.
         ...["--exclude", "settings.json"],
         // Configuration, not content — the same reason settings.json is excluded.
-        // Without this the same CSS ships twice: once as tokens.css, once copied.
+        // Without this the same CSS ships twice: once folded into tokens.css by
+        // assembleTokensCss, once copied as a plain asset.
         ...(settings.tokens === undefined ? [] : ["--exclude", settings.tokens]),
         ...(settings.exclude ?? []).flatMap((pattern) => ["--exclude", pattern]),
+        ...(settings.rehypePlugins ?? []).flatMap((specifier) => ["--rehype-plugin", specifier]),
     ];
 }
 /** Build the site in `dir` into `out`, returning the exit code to leave with. */
@@ -52,16 +63,24 @@ export async function buildSite({ dir, out }) {
     // The spec is derived from settings and means nothing on its own, so it lives
     // in a temporary file rather than in the site or its output: writing it beside
     // the source would leave a generated file for someone to edit by hand, and
-    // writing it into the output would ship it.
-    let workDir;
-    let navPath;
+    // writing it into the output would ship it. The assembled script/CSS are
+    // temporary for the same reason — they are canopy-page's own contribution,
+    // not something a site author edits or that belongs in the output tree.
+    const workDir = await mkdtemp(path.join(tmpdir(), "canopy-page-"));
     try {
+        let navPath;
         if (site.nav.spec !== undefined) {
-            workDir = await mkdtemp(path.join(tmpdir(), "canopy-page-"));
             navPath = path.join(workDir, "nav.json");
             await writeFile(navPath, JSON.stringify(site.nav.spec, null, 2), "utf8");
         }
-        const code = await runCanopy(canopyArgs(site, path.resolve(out), navPath));
+        const userTokensCss = site.settings.tokens === undefined
+            ? undefined
+            : await readFile(path.join(site.root, site.settings.tokens), "utf8");
+        const tokensCssPath = path.join(workDir, "tokens.css");
+        await writeFile(tokensCssPath, await assembleTokensCss(userTokensCss), "utf8");
+        const scriptPath = path.join(workDir, "script.js");
+        await writeFile(scriptPath, await assembleScript(), "utf8");
+        const code = await runCanopy(canopyArgs(site, path.resolve(out), navPath, { tokensCssPath, scriptPath }));
         // Only after canopy succeeded, and only over what it actually wrote: a
         // sitemap listing pages a failed build never produced would be a lie a
         // crawler acts on.
@@ -75,7 +94,6 @@ export async function buildSite({ dir, out }) {
         return code;
     }
     finally {
-        if (workDir !== undefined)
-            await rm(workDir, { recursive: true, force: true });
+        await rm(workDir, { recursive: true, force: true });
     }
 }

package/dist/settings.d.ts

@@ -99,6 +99,18 @@ export interface Settings {
      * points at it. Absent, neither is written.
      */
     siteUrl?: string;
+    /**
+     * Rehype plugins to run on every page, after canopy's own sanitize step and
+     * before syntax highlighting — canopy's fixed extension point for markdown
+     * that needs more than CommonMark and GFM, a diagram fence rendered to SVG
+     * being the case this exists for.
+     *
+     * Each entry is an installed package name (`"rehype-declart"`), never a
+     * filesystem path: this is a JSON settings file naming a dependency the site
+     * author already declared, not a script with a place of its own to resolve a
+     * relative path against.
+     */
+    rehypePlugins?: string[];
 }
 /**
  * Parse and validate a settings file from JSON text.

package/dist/settings.js

@@ -49,6 +49,7 @@ const SETTINGS_KEYS = new Set([
     "logo",
     "home",
     "siteUrl",
+    "rehypePlugins",
 ]);
 const SECTION_KEYS = new Set(["path", "label", "order", "items"]);
 const HOME_KEYS = new Set(["url", "label"]);
@@ -130,6 +131,31 @@ function asExclusionPattern(value, where) {
     }
     return pattern;
 }
+/**
+ * Check a `rehypePlugins` entry names a package rather than a file.
+ *
+ * canopy itself accepts either shape on `--rehype-plugin`, resolving a
+ * filesystem-looking specifier against its own process's working directory.
+ * That directory is canopy-page's spawning process, not the settings file —
+ * the same ambiguity every other path setting here avoids by resolving
+ * relative to the settings file instead. Rather than resolve it a second way
+ * here, a path-looking entry is refused with a message saying why, matching
+ * every other setting whose value must stay inside a stated shape.
+ */
+function asModuleSpecifier(value, where) {
+    const specifier = asString(value, where);
+    const looksLikeAPath = specifier.startsWith("./") ||
+        specifier.startsWith("../") ||
+        specifier.startsWith("/") ||
+        specifier.includes("\\") ||
+        /^[A-Za-z]:/.test(specifier);
+    if (looksLikeAPath) {
+        fail(`${where}: "${specifier}" looks like a file path, not a package name. ` +
+            "Install the plugin as a dependency and name it here the way its package.json does " +
+            '(e.g. "rehype-declart"), so resolution does not depend on the directory the build runs from.');
+    }
+    return specifier;
+}
 function parseNavItem(value, where) {
     // A bare string is the common case — a page in the order it should appear.
     if (typeof value === "string") {
@@ -201,7 +227,7 @@ export function parseSettings(json) {
     }
     const value = asObject(raw, "settings", "expected a JSON object");
     rejectUnknownKeys(value, SETTINGS_KEYS, "settings");
-    const { title, description, lang, icon, tokens, exclude, sections, logo, home, siteUrl } = value;
+    const { title, description, lang, icon, tokens, exclude, sections, logo, home, siteUrl, rehypePlugins } = value;
     if (title !== undefined)
         asString(title, "settings.title");
     if (description !== undefined)
@@ -219,6 +245,9 @@ export function parseSettings(json) {
         fail("settings.exclude: must be an array");
     if (sections !== undefined && !Array.isArray(sections))
         fail("settings.sections: must be an array");
+    if (rehypePlugins !== undefined && !Array.isArray(rehypePlugins)) {
+        fail("settings.rehypePlugins: must be an array");
+    }
     let parsedHome;
     if (home !== undefined) {
         const object = asObject(home, "settings.home", 'expected an object with "url" and "label"');
@@ -263,5 +292,10 @@ export function parseSettings(json) {
         ...(logo === undefined ? {} : { logo: asRelativePath(logo, "settings.logo") }),
         ...(parsedHome === undefined ? {} : { home: parsedHome }),
         ...(siteUrl === undefined ? {} : { siteUrl: siteUrl }),
+        ...(rehypePlugins === undefined
+            ? {}
+            : {
+                rehypePlugins: rehypePlugins.map((specifier, i) => asModuleSpecifier(specifier, `settings.rehypePlugins[${i}]`)),
+            }),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Authoring pipeline for documentation sites: one settings file, integrity checks, and a build.",
   "type": "module",
   "license": "MIT",
@@ -39,16 +39,18 @@
     "check": "tsc --noEmit",
     "lint": "biome lint ./src",
     "test": "vitest run",
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.0",
+    "@iyulab/declart": "^0.20.0",
     "@types/node": "^25.9.3",
+    "rehype-declart": "^0.20.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@iyulab/canopy": "^0.4.0"
+    "@iyulab/canopy": "^0.7.0"
   }
 }