@iyulab/canopy-page 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ 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

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/build.js

@@ -50,6 +50,7 @@ export function canopyArgs(site, out, navPath, searchAssets) {
         // 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. */

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.5.0",
+  "version": "0.6.0",
   "description": "Authoring pipeline for documentation sites: one settings file, integrity checks, and a build.",
   "type": "module",
   "license": "MIT",
@@ -44,11 +44,13 @@
   },
   "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.6.0"
+    "@iyulab/canopy": "^0.7.0"
   }
 }