npm - @iyulab/canopy-page - Versions diffs - 0.1.0 → 0.2.0 - Mend

@iyulab/canopy-page 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,24 @@ 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.2.0] — 2026-08-07
+### Added
+- `tokens`: a CSS file of design-token overrides, relative to the settings file. It is appended
+  after the renderer's own tokens rather than replacing them, so a file naming one custom
+  property keeps every other default. It is configuration rather than content, so it is excluded
+  from the published site automatically — the same file does not ship twice
+- `logo` and `home`: a site can now say what makes a documentation set read as part of the
+  product it belongs to. `logo` is an image shown beside the site title and must be a published
+  file, the opposite direction from `tokens`. `home` is a link back to the surrounding site —
+  `{ url, label }`, both required together, since naming half of it is not a valid setting. There
+  is no default `label`, because link text has to be written in the site's own language
+- `siteUrl`: an absolute URL naming where the built site will stand. Every link the renderer
+  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 stated separately. Setting it makes `build`
+  write `sitemap.xml` and a `robots.txt` pointing at it; leaving it unset writes neither
 ## [0.1.0] — 2026-08-07
 First release. Development before it is recorded here in one block rather than reconstructed as

package/README.md CHANGED Viewed

@@ -85,9 +85,36 @@ unpublished.
 | `description` | Fills `<meta name="description">`, which is what link previews show |
 | `lang` | BCP 47 tag for `<html lang>`. Worth setting for any non-English site: assistive technology reads pronunciation from it |
 | `icon` | Favicon, relative to the settings file. Must be a published file |
+| `tokens` | CSS of design-token overrides, relative to the settings file. Appended *after* canopy's own tokens, so a file naming one value keeps the rest. It is configuration rather than content, so — unlike `icon` and `logo` — it is excluded from the published site automatically. Absent: canopy's default palette |
+| `logo` | Image shown beside the site title, relative to the settings file. Must be a published file — the opposite direction from `tokens`, because this one is content. Rendered with an empty `alt`, deliberately: the site title beside it already names the site, so there is no separate text to give it. Absent: the sidebar header shows the title text alone |
+| `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 |
 | `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`
+override:
+```css
+/* brand.css */
+:root {
+  --accent: #0a7c5a;
+  --accent-hover: #096a4d;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --accent: #4ecfa2;
+    --accent-hover: #6fdcb5;
+  }
+}
+```
+canopy's own tokens end with a `prefers-color-scheme: dark` block, and a media query adds no
+specificity over a bare selector — so a bare `:root` appended after that block wins in *both*
+schemes. A one-block file naming only a light-mode colour would ship that colour onto a dark
+sidebar too.
 The settings file itself is never published, and neither is anything `exclude` names. A file
 named `settings.json` deeper in the site is content, and ships.
@@ -168,6 +195,10 @@ What canopy states it leaves alone is left alone here too — absolute URLs, pro
 bare fragments, and paths above the site root. A target ending in `/` names a directory, and is
 answered by the index page that directory is entered by.
+`build` writes two files `check` never sees: with `siteUrl` set, a `sitemap.xml` listing every
+published page and a `robots.txt` pointing at it. Neither is checked, because neither exists until
+the build has already succeeded.
 ## What belongs where
 canopy-page owns the authoring pipeline; canopy owns the rendering.

package/dist/build.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { loadSite } from "./site.js";
 /**
  * Building a site: check first, then hand the whole of it to canopy in one pass.
  *
@@ -13,5 +14,14 @@ export interface BuildOptions {
     /** Directory to write the site into. */
     out: 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.
+ */
+export declare function canopyArgs(site: Awaited<ReturnType<typeof loadSite>>, out: string, navPath: string | undefined): 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 CHANGED Viewed

@@ -3,6 +3,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import { runCanopy } from "./canopy.js";
 import { siteFindings } from "./check.js";
+import { listHtmlFiles, robotsTxt, sitemapXml } from "./sitemap.js";
 import { loadSite, reportFindings } from "./site.js";
 /**
  * Translate settings into canopy's arguments.
@@ -12,7 +13,7 @@ import { loadSite, reportFindings } from "./site.js";
  * navigation spec is the one thing that has to be materialized, since canopy
  * reads it from a file.
  */
-function canopyArgs(site, out, navPath) {
+export function canopyArgs(site, out, navPath) {
     const { settings } = site;
     return [
         "build",
@@ -22,10 +23,22 @@ 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)]),
+        ...(settings.logo === undefined ? [] : ["--site-logo", settings.logo]),
+        ...(settings.home === undefined
+            ? []
+            : ["--home-url", settings.home.url, "--home-label", settings.home.label]),
         ...(navPath === undefined ? [] : ["--nav", navPath]),
         // 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.
+        ...(settings.tokens === undefined ? [] : ["--exclude", settings.tokens]),
         ...(settings.exclude ?? []).flatMap((pattern) => ["--exclude", pattern]),
     ];
 }
@@ -48,7 +61,18 @@ export async function buildSite({ dir, out }) {
             navPath = path.join(workDir, "nav.json");
             await writeFile(navPath, JSON.stringify(site.nav.spec, null, 2), "utf8");
         }
-        return await runCanopy(canopyArgs(site, path.resolve(out), navPath));
+        const code = await runCanopy(canopyArgs(site, path.resolve(out), navPath));
+        // 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.
+        if (code === 0 && site.settings.siteUrl !== undefined) {
+            const outDir = path.resolve(out);
+            const pages = await listHtmlFiles(outDir);
+            await writeFile(path.join(outDir, "sitemap.xml"), sitemapXml(site.settings.siteUrl, pages), "utf8");
+            await writeFile(path.join(outDir, "robots.txt"), robotsTxt(site.settings.siteUrl), "utf8");
+            console.log(`canopy-page: sitemap.xml with ${pages.length} page(s)`);
+        }
+        return code;
     }
     finally {
         if (workDir !== undefined)

package/dist/references.d.ts CHANGED Viewed

@@ -63,7 +63,7 @@ export declare function targetPath(url: string): string;
  * undefined, and the reference is left alone — which is what the renderer does
  * with it, and the checker's job is to agree with the renderer.
  *
- * TODO(upstream: claudedocs/upstream-issues/ISSUE-canopy-20260807-link-target-resolution.md)
+ * TODO(upstream: claudedocs/issues/ISSUE-canopy-20260807-link-target-resolution.md)
  * — canopy applies this same rule when it rewrites links, and does not expose
  * it, so the rule is spelled out twice and can drift. It just did: canopy
  * learned to read this encoding one release before this file did.

package/dist/references.js CHANGED Viewed

@@ -136,7 +136,7 @@ export function targetPath(url) {
  * undefined, and the reference is left alone — which is what the renderer does
  * with it, and the checker's job is to agree with the renderer.
  *
- * TODO(upstream: claudedocs/upstream-issues/ISSUE-canopy-20260807-link-target-resolution.md)
+ * TODO(upstream: claudedocs/issues/ISSUE-canopy-20260807-link-target-resolution.md)
  * — canopy applies this same rule when it rewrites links, and does not expose
  * it, so the rule is spelled out twice and can drift. It just did: canopy
  * learned to read this encoding one release before this file did.

package/dist/settings.d.ts CHANGED Viewed

@@ -66,10 +66,39 @@ export interface Settings {
     lang?: string;
     /** Favicon, relative to the settings file. Must be a published file. */
     icon?: string;
+    /**
+     * CSS of design-token overrides, relative to the settings file.
+     *
+     * Appended after canopy's own tokens, so a file naming one value keeps the
+     * rest. It is configuration rather than content: it is read at build time and
+     * left off the published site.
+     */
+    tokens?: string;
     /** Paths to leave unpublished: a directory, an extension (`*.tmp`), or one exact path. */
     exclude?: string[];
     /** Ordered regions of the site. Without them, navigation follows the folder tree. */
     sections?: SettingsSection[];
+    /** Logo shown beside the site title, relative to the settings file. Must be a published file. */
+    logo?: string;
+    /**
+     * A link back to the site this documentation sits beside.
+     *
+     * Both halves or neither: a URL with no text renders an empty link, and text
+     * with no URL links nowhere. Stating them as one object makes the half-filled
+     * state unrepresentable rather than merely rejected.
+     */
+    home?: {
+        url: string;
+        label: string;
+    };
+    /**
+     * Where the built site will stand, as an absolute URL.
+     *
+     * Every link canopy writes is relative, so a site needs this for nothing except
+     * the things that must be absolute: `sitemap.xml` and the robots file that
+     * points at it. Absent, neither is written.
+     */
+    siteUrl?: string;
 }
 /**
  * Parse and validate a settings file from JSON text.

package/dist/settings.js CHANGED Viewed

@@ -43,10 +43,15 @@ const SETTINGS_KEYS = new Set([
     "description",
     "lang",
     "icon",
+    "tokens",
     "exclude",
     "sections",
+    "logo",
+    "home",
+    "siteUrl",
 ]);
 const SECTION_KEYS = new Set(["path", "label", "order", "items"]);
+const HOME_KEYS = new Set(["url", "label"]);
 const NAV_ITEM_KEYS = new Set(["label", "path", "items"]);
 /**
  * Unknown keys are rejected rather than ignored.
@@ -196,7 +201,7 @@ export function parseSettings(json) {
     }
     const value = asObject(raw, "settings", "expected a JSON object");
     rejectUnknownKeys(value, SETTINGS_KEYS, "settings");
-    const { title, description, lang, icon, exclude, sections } = value;
+    const { title, description, lang, icon, tokens, exclude, sections, logo, home, siteUrl } = value;
     if (title !== undefined)
         asString(title, "settings.title");
     if (description !== undefined)
@@ -214,11 +219,34 @@ export function parseSettings(json) {
         fail("settings.exclude: must be an array");
     if (sections !== undefined && !Array.isArray(sections))
         fail("settings.sections: must be an array");
+    let parsedHome;
+    if (home !== undefined) {
+        const object = asObject(home, "settings.home", 'expected an object with "url" and "label"');
+        rejectUnknownKeys(object, HOME_KEYS, "settings.home");
+        if (object.url === undefined)
+            fail('settings.home.url: needed alongside "label"');
+        if (object.label === undefined)
+            fail('settings.home.label: needed alongside "url"');
+        const url = asString(object.url, "settings.home.url");
+        // The target is normally outside the published site, so a relative path has
+        // nothing here to resolve against.
+        if (!/^https?:\/\//i.test(url)) {
+            fail(`settings.home.url: "${url}" must be an absolute http(s) URL`);
+        }
+        parsedHome = { url, label: asString(object.label, "settings.home.label") };
+    }
+    if (siteUrl !== undefined) {
+        const url = asString(siteUrl, "settings.siteUrl");
+        if (!/^https?:\/\//i.test(url)) {
+            fail(`settings.siteUrl: "${url}" must be an absolute http(s) URL`);
+        }
+    }
     return {
         ...(title === undefined ? {} : { title: title }),
         ...(description === undefined ? {} : { description: description }),
         ...(lang === undefined ? {} : { lang: lang }),
         ...(icon === undefined ? {} : { icon: asRelativePath(icon, "settings.icon") }),
+        ...(tokens === undefined ? {} : { tokens: asRelativePath(tokens, "settings.tokens") }),
         ...(exclude === undefined
             ? {}
             : {
@@ -232,5 +260,8 @@ export function parseSettings(json) {
             : {
                 sections: sections.map((section, i) => parseSection(section, `settings.sections[${i}]`)),
             }),
+        ...(logo === undefined ? {} : { logo: asRelativePath(logo, "settings.logo") }),
+        ...(parsedHome === undefined ? {} : { home: parsedHome }),
+        ...(siteUrl === undefined ? {} : { siteUrl: siteUrl }),
     };
 }

package/dist/site.js CHANGED Viewed

@@ -42,7 +42,7 @@ export async function loadSite(dir) {
         }
         throw error;
     }
-    const listing = await listSite(root, settings.exclude);
+    const listing = await listSite(root, settings.exclude, settings.tokens === undefined ? [] : [settings.tokens]);
     const index = indexSite(listing.files);
     return {
         root,

package/dist/sitemap.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/** A sitemap naming every published page, newline-terminated. */
+export declare function sitemapXml(siteUrl: string, htmlPaths: readonly string[]): string;
+/**
+ * A robots file whose only job is to point at the sitemap.
+ *
+ * Written only alongside one. A robots.txt with nothing to say would be canopy-page
+ * asserting a crawl policy nobody stated.
+ */
+export declare function robotsTxt(siteUrl: string): string;
+/** Every `.html` file under `outDir`, as sorted POSIX paths relative to it. */
+export declare function listHtmlFiles(outDir: string): Promise<string[]>;

package/dist/sitemap.js ADDED Viewed

@@ -0,0 +1,66 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+/**
+ * The two files a site is found by.
+ *
+ * Both need one thing canopy deliberately does not know: where the site
+ * actually stands. 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, cannot be derived from the output alone. `siteUrl` supplies
+ * it, and without it neither file is written.
+ *
+ * The page list comes from the *output* rather than from the source: canopy adds
+ * a synthetic `index.html` to a site whose root has no index page, and a sitemap
+ * that omitted it would omit the site's front door. Listing files is not reading
+ * them — nothing here parses the HTML canopy produced.
+ */
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * The URL a page is canonically reached by.
+ *
+ * A directory's index page is the directory: `guide/index.html` and `guide/` are
+ * one page, and listing both would ask a crawler to treat it as two.
+ */
+function pageUrl(base, htmlPath) {
+    const canonical = htmlPath.replace(/(^|\/)index\.html$/, "$1");
+    // encodeURI leaves the separators alone and fixes what a URL cannot carry raw.
+    return `${base}/${encodeURI(canonical)}`;
+}
+/** A sitemap naming every published page, newline-terminated. */
+export function sitemapXml(siteUrl, htmlPaths) {
+    const base = siteUrl.replace(/\/+$/, "");
+    const entries = [...htmlPaths]
+        .sort()
+        .map((htmlPath) => `  <url><loc>${escapeXml(pageUrl(base, htmlPath))}</loc></url>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries}
+</urlset>
+`;
+}
+/**
+ * A robots file whose only job is to point at the sitemap.
+ *
+ * Written only alongside one. A robots.txt with nothing to say would be canopy-page
+ * asserting a crawl policy nobody stated.
+ */
+export function robotsTxt(siteUrl) {
+    const base = siteUrl.replace(/\/+$/, "");
+    return `User-agent: *\nAllow: /\nSitemap: ${base}/sitemap.xml\n`;
+}
+/** Every `.html` file under `outDir`, as sorted POSIX paths relative to it. */
+export async function listHtmlFiles(outDir) {
+    const entries = await readdir(outDir, { recursive: true, withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".html"))
+        .map((entry) => path.relative(outDir, path.join(entry.parentPath, entry.name)).replace(/\\/g, "/"))
+        .sort();
+}

package/dist/vault.d.ts CHANGED Viewed

@@ -25,7 +25,9 @@ export interface SiteListing {
  * The settings file itself is not content and never ships: it is configuration
  * that happens to live next to what it configures.
  */
-export declare function listSite(root: string, exclude?: readonly string[]): Promise<SiteListing>;
+export declare function listSite(root: string, exclude?: readonly string[],
+/** Files that configure the site rather than belong to it — never published. */
+configFiles?: readonly string[]): Promise<SiteListing>;
 /** The published files alone, for callers with nothing to say about exclusions. */
 export declare function listSiteFiles(root: string, exclude?: readonly string[]): Promise<string[]>;
 /** The settings file a site is configured by, found at the root of the site. */

package/dist/vault.js CHANGED Viewed

@@ -137,12 +137,15 @@ async function walk(root, rel, found, use) {
  * The settings file itself is not content and never ships: it is configuration
  * that happens to live next to what it configures.
  */
-export async function listSite(root, exclude = []) {
+export async function listSite(root, exclude = [],
+/** Files that configure the site rather than belong to it — never published. */
+configFiles = []) {
     const found = [];
     const use = new ExclusionUse(exclude.filter((pattern) => pattern.trim() !== ""));
     await walk(root, "", found, use);
+    const config = new Set([SETTINGS_FILENAME, ...configFiles]);
     return {
-        files: found.filter((file) => file !== SETTINGS_FILENAME).sort(),
+        files: found.filter((file) => !config.has(file)).sort(),
         unusedExclusions: use.unused(),
     };
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Authoring pipeline for documentation sites: one settings file, integrity checks, and a build.",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,6 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@iyulab/canopy": "^0.1.2"
+    "@iyulab/canopy": "^0.2.0"
   }
 }