npm - @iyulab/canopy-page - Versions diffs - 0.12.0 → 0.14.0 - Mend

@iyulab/canopy-page 0.12.0 → 0.14.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 (15) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,53 @@ 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.14.0] — 2026-09-17
+### Added
+- **`siteUrl` now reaches the pages, not just the sitemap.** It is passed to canopy as
+  `--site-url`, so every page carries `<link rel="canonical">` and `og:url` naming its one
+  address — by exactly the string the sitemap lists it under, since both now come from canopy's
+  own `pageUrl()` rule rather than two copies of it. A page's frontmatter `description:` fills
+  its own `<meta name="description">` (the site's stays the fallback), and the Open Graph basics
+  ride on every page with or without `siteUrl`. Body links stay relative either way.
+- **`previewImage`** — the image link previews show (`og:image`) for any page whose frontmatter
+  has no `image:` of its own. Validated like `icon`/`logo` (a published file), and rejected
+  without `siteUrl`, since the tag has to be absolute.
+- **`alternates`** — the site's other language editions, `hreflang` → that edition's own site
+  URL (`x-default` allowed). Each page lists its counterpart at the same path under every
+  edition, its own first, as `hreflang` links in `<head>` and as `xhtml:link` entries in
+  `sitemap.xml`. Rejected without `siteUrl`.
+- **`check` warns about pages with no `description:` of their own once `siteUrl` is set** — one
+  warning naming them all, never an error. A public site's pages otherwise present one
+  identical summary in every search result, and `siteUrl` is the setting that says the site is
+  public.
+### Changed
+- **Sidebar redesign, via canopy 0.13.0** — rows with padding, a hover surface and a focus
+  ring; the group chevron moves to the row's trailing edge so labels at one depth share a left
+  edge; nested lists carry a guide line. Two new tokens, `--sidebar-hover-bg` and `--sp-1`. A
+  `tokens` file that styled `.canopy-nav-group > summary::before` should target `::after`.
+## [0.13.0] — 2026-08-22
+### Added
+- **Upgraded to canopy 0.12.0** — an external-link icon on `home` when it points outside the
+  site, a scroll-edge shadow on code blocks wider than the viewport, and the on-page outline now
+  shows its own label instead of only an `aria-label`. See
+  [canopy's own changelog](https://github.com/iyulab/canopy/blob/main/CHANGELOG.md#0120--2026-08-22)
+  for details.
+- **A `Ctrl K`/`⌘K` badge on the search box**, so the keyboard shortcut that already worked has
+  something telling a reader it exists. Hidden once the box has focus, and on narrow viewports
+  where the box collapses to an icon and a shortcut is unlikely to matter anyway.
+- **`check` warns about a filename that needs percent-encoding in its own URL** — a stray space
+  or other ASCII character outside a URL's unreserved set, most often. The page still publishes
+  correctly (a static host serves the encoded URL fine), so this is a warning, not an error;
+  ignore it if the encoding is intended. Blind to non-ASCII on purpose: a Korean, Japanese, or
+  any other non-English filename needs encoding too, but that's the language, not a mistake.
 ## [0.12.0] — 2026-08-22
 ### Added

package/README.md CHANGED Viewed

@@ -10,6 +10,10 @@ itself is [canopy](https://github.com/iyulab/canopy)'s job, and canopy-page driv
 **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`.
+**Complete reference**: [`docs/USAGE.md`](docs/USAGE.md) — every command, every
+`settings.json` field, every markdown feature, and everything a published site ships with, in
+one document. This README stays the short version.
 ---
 ## Why
@@ -33,7 +37,8 @@ page never depends on any of the scripted ones: block scripts, or print the page
 go away.
 - **Search**, matching a query against every page's title, headings, and body — `Ctrl+K` /
-  `Cmd+K` jumps to it from anywhere
+  `Cmd+K` jumps to it from anywhere, badged on the search box itself so the shortcut is
+  discoverable without reading the docs
 - **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
@@ -45,9 +50,18 @@ go away.
 - **Sidebar groups collapse**, open exactly along the path to the page you're on and closed
   everywhere else
 - **A breadcrumb trail** in the topbar, when there's a title, a logo, `home`, or search for it to
-  sit beside
+  sit beside — and an icon on `home` specifically when it points off the site, so a link sitting
+  right next to that trail doesn't look like it stays on it
 - **A full-screen menu on narrow screens** that starts closed instead of opening on every page,
   remembering a reader's own choice to leave it open for the rest of that visit
+- **A code block wider than the screen shows a shadow at whichever edge still has more to
+  scroll to**, and nothing once you've scrolled there — a cue for a scrollbar that some
+  OS/browser combinations hide until hovered
+- **Search and link-preview metadata in every page's `<head>`** — a page's own frontmatter
+  `description:` (falling back to the site's), the Open Graph basics and a `twitter:card`; once
+  `siteUrl` is set, also a canonical URL, `og:url`, `og:image` (`previewImage`, or a page's own
+  `image:`), and `hreflang` links to the language editions `alternates` names. Body links stay
+  relative regardless, so the same output still opens from a local folder
 - **Sitemap and `robots.txt`**, once `siteUrl` is set
 See it live at <https://iyulab.github.io/canopy-page>, or read
@@ -236,6 +250,11 @@ Warnings — reported, and the build continues:
 - A section with no `label` and no index page, whose sidebar heading falls back to its own
   directory name — a filesystem detail, not a name anyone chose. Add a `label`, or an index page
   for the section to name itself
+- A filename whose published URL needs percent-encoding — a stray space or other ASCII
+  character outside a URL's unreserved set, most often. The page still publishes and works; this
+  is a nudge to check whether the encoding was intended, not a defect. Blind to non-ASCII on
+  purpose, so a Korean, Japanese, or any other non-English filename is never flagged for being
+  itself
 Checking reads the settings and each page. It never renders, so it is fast enough to sit at the
 front of a pipeline, at the scale a product manual reaches. References inside fenced

package/dist/assets/search.css CHANGED Viewed

@@ -8,6 +8,44 @@
   position: relative;
 }
+/* Reserve room so the shortcut badge below doesn't sit on top of typed
+   text — canopy's own input padding only accounts for its search icon on
+   the left. */
+.canopy-search input[type="search"] {
+  padding-right: 3rem;
+}
+/* Advertises Ctrl+K/Cmd+K (search.js). An inert glyph, not a button — same
+   masked-icon-adjacent technique canopy's own shell uses for its search and
+   theme-toggle icons: pointer-events: none lets a click straight through to
+   the input underneath it. Hidden once the input has focus, so it doesn't
+   crowd a query being typed, and on narrow viewports, where canopy's own
+   shell (styles.ts, the `max-width: 40rem` breakpoint) collapses the input
+   to an icon-sized 2.25rem with no room for a badge — and where a physical
+   keyboard, the whole reason the shortcut exists, is unlikely anyway. */
+.canopy-search-shortcut {
+  position: absolute;
+  top: 50%;
+  right: var(--sp-2);
+  transform: translateY(-50%);
+  padding: 0.05em 0.4em;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-m);
+  font-size: 0.75em;
+  line-height: 1.4;
+  color: var(--text-muted);
+  background: var(--bg-secondary);
+  pointer-events: none;
+}
+.canopy-search input[type="search"]:focus ~ .canopy-search-shortcut {
+  display: none;
+}
+@media (max-width: 40rem) {
+  .canopy-search-shortcut {
+    display: none;
+  }
+}
 .canopy-search-results {
   position: absolute;
   top: 100%;

package/dist/assets/search.js CHANGED Viewed

@@ -208,6 +208,19 @@ var CanopySearch = (function () {
       }
     });
+    // The shortcut above only works if a reader knows it exists — the badge
+    // is what tells them. Built here rather than in canopy's own shell markup
+    // because only this script knows the shortcut actually ended up wired
+    // (a build with no --script attached never reaches this line at all, so
+    // it never advertises a key that would do nothing). CSS hides it once
+    // the input has focus (search.css) so it doesn't crowd a query being
+    // typed.
+    var shortcut = document.createElement("kbd");
+    shortcut.className = "canopy-search-shortcut";
+    shortcut.setAttribute("aria-hidden", "true");
+    shortcut.textContent = /Mac|iPhone|iPad/.test(navigator.platform || "") ? "⌘K" : "Ctrl K";
+    form.appendChild(shortcut);
     // 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.

package/dist/build.js CHANGED Viewed

@@ -22,6 +22,14 @@ export function canopyArgs(site, out, navPath, searchAssets) {
         out,
         ...(settings.title === undefined ? [] : ["--site-title", settings.title]),
         ...(settings.description === undefined ? [] : ["--site-description", settings.description]),
+        // The same URL the sitemap below is written against, so canopy's canonical
+        // tags and the sitemap's entries name each page by one string.
+        ...(settings.siteUrl === undefined ? [] : ["--site-url", settings.siteUrl]),
+        ...(settings.previewImage === undefined ? [] : ["--site-image", settings.previewImage]),
+        ...Object.entries(settings.alternates ?? {}).flatMap(([hreflang, url]) => [
+            "--alternate",
+            `${hreflang}=${url}`,
+        ]),
         ...(settings.lang === undefined ? [] : ["--lang", settings.lang]),
         ...(settings.icon === undefined ? [] : ["--site-icon", settings.icon]),
         // Always present: canopy-page's own CSS (search, scrollspy) rides here
@@ -88,7 +96,10 @@ export async function buildSite({ dir, out }) {
         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, "sitemap.xml"), sitemapXml(site.settings.siteUrl, pages, {
+                ...(site.settings.lang === undefined ? {} : { lang: site.settings.lang }),
+                ...(site.settings.alternates === undefined ? {} : { alternates: site.settings.alternates }),
+            }), "utf8");
             await writeFile(path.join(outDir, "robots.txt"), robotsTxt(site.settings.siteUrl), "utf8");
             console.log(`canopy-page: sitemap.xml with ${pages.length} page(s)`);
         }

package/dist/check.d.ts CHANGED Viewed

@@ -1,4 +1,16 @@
 import { type Finding, type LoadedSite } from "./site.js";
+/**
+ * A published path's segments, exactly where percent-encoding canopy applies
+ * to the *link* (never the file, which keeps its raw name) turns out to
+ * matter: `relativeHref` (canopy's site-path.ts) encodes each segment with
+ * `encodeURIComponent`, so a name with a space or other URL-unsafe character
+ * still resolves — a static host serves "error%20messages.html" correctly —
+ * but nothing tells the author whether that was intended. Pages become
+ * `.html`; every other published file's segments are checked exactly as
+ * written, mirroring `toSitePath`'s own "everything but markdown passes
+ * through unchanged".
+ */
+export declare function filenameEncodingFindings(site: LoadedSite): Finding[];
 /** Check every page's references, returning one finding per broken reference. */
 export declare function referenceFindings(site: LoadedSite): Promise<Finding[]>;
 /**
@@ -6,5 +18,23 @@ export declare function referenceFindings(site: LoadedSite): Promise<Finding[]>;
  * the settings got wrong first, then what the pages point at.
  */
 export declare function siteFindings(site: LoadedSite): Promise<Finding[]>;
+/**
+ * Pages with no `description:` of their own, on a site that is going to be
+ * found by search.
+ *
+ * Such a page falls back to the site's one description, which is harmless for
+ * a site nobody searches and a duplicate summary on every result for one that
+ * is public. `siteUrl` is the setting that says which of the two this is — the
+ * same gate the sitemap already uses — so the warning waits for it rather than
+ * asking for a field of its own. One warning naming every such page, one per
+ * line, for the same reason `navFindings` lists uncovered pages that way: on a
+ * real site the list runs to dozens, and a warning per page would be a wall.
+ * Never an error: a site published somewhere but not meant to be found that way
+ * is entitled to ignore this.
+ *
+ * Frontmatter is read with canopy's own parser, so what counts as a
+ * description here is exactly what canopy will put in the page.
+ */
+export declare function descriptionFindings(site: LoadedSite): Promise<Finding[]>;
 /** Check the site in `dir`, returning the exit code to leave with. */
 export declare function checkSite(dir: string): Promise<number>;

package/dist/check.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { parseFrontmatter } from "@iyulab/canopy";
 import { decodeTarget, extractReferences, isExternalUrl, resolveFrom, targetPath, } from "./references.js";
 import { loadSite, navFindings, reportFindings, settingsFindings, } from "./site.js";
 import { toPageKey } from "./vault.js";
@@ -85,6 +86,57 @@ function wikilinkExists(site, target) {
         return site.index.resolve(target) !== undefined;
     return site.index.pages.some((page) => toPageKey(page).split("/").pop() === key);
 }
+/**
+ * `encodeURIComponent`'s unreserved set — the ASCII characters it leaves
+ * alone. Everything else ASCII (a space, `#`, `&`, `?`, …) is the kind of
+ * character that lands in a filename by accident — a stray space, a
+ * character copied from somewhere that meant it as punctuation, not a path.
+ */
+const ASCII_URI_SAFE = /^[A-Za-z0-9\-_.!~*'()]$/;
+/**
+ * True if `segment` contains an ASCII character `encodeURIComponent` would
+ * escape. Deliberately blind to non-ASCII: canopy percent-encodes every
+ * character outside the unreserved set, which means *any* non-English
+ * filename — a Korean directory name, an emoji — would otherwise trip this,
+ * and canopy-page's own demo site intentionally ships one (see
+ * `examples/site/guide/한국어-예시/`) as a *supported* pattern, not a mistake
+ * to flag. An ASCII character in the escaped set, on the other hand, is
+ * consistently a slip — nobody names a file "error#messages.md" on purpose.
+ */
+function hasAsciiEncodingIssue(segment) {
+    for (const char of segment) {
+        const code = char.codePointAt(0);
+        if (code !== undefined && code <= 0x7f && !ASCII_URI_SAFE.test(char))
+            return true;
+    }
+    return false;
+}
+/**
+ * A published path's segments, exactly where percent-encoding canopy applies
+ * to the *link* (never the file, which keeps its raw name) turns out to
+ * matter: `relativeHref` (canopy's site-path.ts) encodes each segment with
+ * `encodeURIComponent`, so a name with a space or other URL-unsafe character
+ * still resolves — a static host serves "error%20messages.html" correctly —
+ * but nothing tells the author whether that was intended. Pages become
+ * `.html`; every other published file's segments are checked exactly as
+ * written, mirroring `toSitePath`'s own "everything but markdown passes
+ * through unchanged".
+ */
+export function filenameEncodingFindings(site) {
+    const findings = [];
+    for (const file of [...site.index.pages, ...site.index.assets]) {
+        const published = file.replace(/\.md$/i, ".html");
+        const segments = published.split("/");
+        if (!segments.some(hasAsciiEncodingIssue))
+            continue;
+        const href = segments.map((segment) => encodeURIComponent(segment)).join("/");
+        findings.push({
+            level: "warning",
+            message: `${file}: published URL is "${href}" (rename to avoid the encoding, or ignore if intentional)`,
+        });
+    }
+    return findings;
+}
 /** Check every page's references, returning one finding per broken reference. */
 export async function referenceFindings(site) {
     const findings = [];
@@ -169,7 +221,47 @@ export async function siteFindings(site) {
     return [
         ...settingsFindings(site),
         ...navFindings(site.nav),
+        ...filenameEncodingFindings(site),
         ...(await referenceFindings(site)),
+        ...(await descriptionFindings(site)),
+    ];
+}
+/**
+ * Pages with no `description:` of their own, on a site that is going to be
+ * found by search.
+ *
+ * Such a page falls back to the site's one description, which is harmless for
+ * a site nobody searches and a duplicate summary on every result for one that
+ * is public. `siteUrl` is the setting that says which of the two this is — the
+ * same gate the sitemap already uses — so the warning waits for it rather than
+ * asking for a field of its own. One warning naming every such page, one per
+ * line, for the same reason `navFindings` lists uncovered pages that way: on a
+ * real site the list runs to dozens, and a warning per page would be a wall.
+ * Never an error: a site published somewhere but not meant to be found that way
+ * is entitled to ignore this.
+ *
+ * Frontmatter is read with canopy's own parser, so what counts as a
+ * description here is exactly what canopy will put in the page.
+ */
+export async function descriptionFindings(site) {
+    if (site.settings.siteUrl === undefined)
+        return [];
+    const missing = [];
+    for (const page of site.index.pages) {
+        const { data } = parseFrontmatter(await readFile(path.join(site.root, page), "utf8"));
+        const description = data.description;
+        if (typeof description !== "string" || description.trim() === "")
+            missing.push(page);
+    }
+    if (missing.length === 0)
+        return [];
+    return [
+        {
+            level: "warning",
+            message: `${missing.length} page(s) have no "description:" in their frontmatter, so search ` +
+                "results and link previews show the site's description for each of them:\n" +
+                missing.map((page) => `  ${page}`).join("\n"),
+        },
     ];
 }
 /** Check the site in `dir`, returning the exit code to leave with. */

package/dist/settings.d.ts CHANGED Viewed

@@ -95,10 +95,24 @@ export interface Settings {
      * 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.
+     * the things that must be absolute: `sitemap.xml`, the robots file that points
+     * at it, and the `<head>` tags a search engine reads as addresses — canonical,
+     * `og:url`, `og:image`, `hreflang`. Absent, none of them is written.
      */
     siteUrl?: string;
+    /**
+     * Image a link preview shows (`og:image`) for any page whose frontmatter has
+     * no `image` of its own, relative to the settings file. Must be a published
+     * file, like `icon` and `logo`. Needs `siteUrl`: the tag has to be absolute.
+     */
+    previewImage?: string;
+    /**
+     * The site's other language editions, `hreflang` tag → that edition's own
+     * absolute site URL (`x-default` allowed). Each page then names its
+     * counterpart at the same path under every edition, in `<head>` and in the
+     * sitemap. Needs `siteUrl`, which is the entry for this edition itself.
+     */
+    alternates?: Record<string, 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

package/dist/settings.js CHANGED Viewed

@@ -54,6 +54,8 @@ export const SETTINGS_KEYS = new Set([
     "logo",
     "home",
     "siteUrl",
+    "previewImage",
+    "alternates",
     "rehypePlugins",
     "strings",
 ]);
@@ -244,7 +246,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, rehypePlugins, strings, } = value;
+    const { title, description, lang, icon, tokens, exclude, sections, logo, home, siteUrl, previewImage, alternates, rehypePlugins, strings, } = value;
     if (title !== undefined)
         asString(title, "settings.title");
     if (description !== undefined)
@@ -286,6 +288,32 @@ export function parseSettings(json) {
             fail(`settings.siteUrl: "${url}" must be an absolute http(s) URL`);
         }
     }
+    // Both turn into absolute URLs, and siteUrl is the only thing they can be
+    // absolute against — so naming either without it is rejected here, where the
+    // message can say what is missing, rather than passed on for canopy to refuse.
+    if (previewImage !== undefined && siteUrl === undefined) {
+        fail("settings.previewImage: needs siteUrl, since a preview image has to be an absolute URL");
+    }
+    let parsedAlternates;
+    if (alternates !== undefined) {
+        const object = asObject(alternates, "settings.alternates", "expected an object of hreflang → site URL");
+        if (siteUrl === undefined) {
+            fail("settings.alternates: needs siteUrl, since this edition has to be listed alongside the others");
+        }
+        parsedAlternates = {};
+        for (const key of Object.keys(object)) {
+            // The same shape `lang` accepts, plus the one reserved value the
+            // protocol defines for "no better match".
+            if (key !== "x-default" && !/^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$/.test(key)) {
+                fail(`settings.alternates: "${key}" is not a language tag like "en" or "ko-KR", or "x-default"`);
+            }
+            const url = asString(object[key], `settings.alternates.${key}`);
+            if (!/^https?:\/\//i.test(url)) {
+                fail(`settings.alternates.${key}: "${url}" must be an absolute http(s) URL`);
+            }
+            parsedAlternates[key] = url;
+        }
+    }
     let parsedStrings;
     if (strings !== undefined) {
         const object = asObject(strings, "settings.strings", "expected an object");
@@ -317,6 +345,10 @@ export function parseSettings(json) {
         ...(logo === undefined ? {} : { logo: asRelativePath(logo, "settings.logo") }),
         ...(parsedHome === undefined ? {} : { home: parsedHome }),
         ...(siteUrl === undefined ? {} : { siteUrl: siteUrl }),
+        ...(previewImage === undefined
+            ? {}
+            : { previewImage: asRelativePath(previewImage, "settings.previewImage") }),
+        ...(parsedAlternates === undefined ? {} : { alternates: parsedAlternates }),
         ...(parsedStrings === undefined ? {} : { strings: parsedStrings }),
         ...(rehypePlugins === undefined
             ? {}

package/dist/sitemap.d.ts CHANGED Viewed

@@ -1,5 +1,19 @@
-/** A sitemap naming every published page, newline-terminated. */
-export declare function sitemapXml(siteUrl: string, htmlPaths: readonly string[]): string;
+/** The site's other language editions, for the sitemap's `xhtml:link` alternates. */
+export interface SitemapEditions {
+    /** This edition's own language tag; defaults to "en", as canopy's shell does. */
+    lang?: string;
+    /** `hreflang` → that edition's own site URL, `x-default` allowed. */
+    alternates?: Record<string, string>;
+}
+/**
+ * A sitemap naming every published page, newline-terminated.
+ *
+ * With an edition map, each entry also lists the page's counterpart in every
+ * edition, this one included — the sitemap form of the `hreflang` links the
+ * pages themselves carry, and the same rule: this edition leads unless the map
+ * already places its language explicitly.
+ */
+export declare function sitemapXml(siteUrl: string, htmlPaths: readonly string[], editions?: SitemapEditions): string;
 /**
  * A robots file whose only job is to point at the sitemap.
  *

package/dist/sitemap.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import { readdir } from "node:fs/promises";
 import path from "node:path";
+import { pageUrl } from "@iyulab/canopy";
 /**
  * The two files a site is found by.
  *
@@ -13,6 +14,13 @@ import path from "node:path";
  * 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.
+ *
+ * `pageUrl` is canopy's own rule for a page's canonical address (an index page
+ * is its directory) — the same function the shell uses for `rel="canonical"`,
+ * imported rather than restated so the sitemap's `<loc>` and the page's own
+ * canonical can never disagree by a character. canopy-page otherwise drives
+ * canopy through its command line (see `canopy.ts`); that stance is about the
+ * build, and a pure URL rule is not a second door into it.
  */
 function escapeXml(value) {
     return value
@@ -23,25 +31,33 @@ function escapeXml(value) {
         .replace(/'/g, "&apos;");
 }
 /**
- * The URL a page is canonically reached by.
+ * A sitemap naming every published page, newline-terminated.
  *
- * 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.
+ * With an edition map, each entry also lists the page's counterpart in every
+ * edition, this one included — the sitemap form of the `hreflang` links the
+ * pages themselves carry, and the same rule: this edition leads unless the map
+ * already places its language explicitly.
  */
-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(/\/+$/, "");
+export function sitemapXml(siteUrl, htmlPaths, editions = {}) {
+    const editionList = [];
+    if (editions.alternates !== undefined) {
+        const lang = editions.lang ?? "en";
+        if (!Object.hasOwn(editions.alternates, lang))
+            editionList.push([lang, siteUrl]);
+        editionList.push(...Object.entries(editions.alternates));
+    }
     const entries = [...htmlPaths]
         .sort()
-        .map((htmlPath) => `  <url><loc>${escapeXml(pageUrl(base, htmlPath))}</loc></url>`)
+        .map((htmlPath) => {
+        const alternates = editionList
+            .map(([hreflang, base]) => `<xhtml:link rel="alternate" hreflang="${escapeXml(hreflang)}" href="${escapeXml(pageUrl(base, htmlPath))}"/>`)
+            .join("");
+        return `  <url><loc>${escapeXml(pageUrl(siteUrl, htmlPath))}</loc>${alternates}</url>`;
+    })
         .join("\n");
+    const xhtmlNamespace = editionList.length > 0 ? ' xmlns:xhtml="http://www.w3.org/1999/xhtml"' : "";
     return `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${xhtmlNamespace}>
 ${entries}
 </urlset>
 `;

package/dist/vault.d.ts CHANGED Viewed

@@ -1,3 +1,21 @@
+/**
+ * Reading the source tree a settings file describes.
+ *
+ * canopy-page has to see the same files canopy will publish, because everything
+ * it does is about them: expanding `guide/*` into pages, reporting a link to a
+ * page that does not exist, deciding what a section contains. The checks are
+ * only worth anything if the file list they run against is the one that ships.
+ *
+ * That means the exclusion rules here have to agree with canopy's, and they are
+ * stated in canopy's README as the interface they are: dot-prefixed directories
+ * and `node_modules` are never published, and caller patterns come in three
+ * shapes. Agreeing by restating is a seam — if canopy ever widens its dialect,
+ * a check here would quietly disagree with the build. See
+ * TODO(upstream: claudedocs/issues/ISSUE-canopy-20260806-published-file-listing.md)
+ * for the proposal that would let a consumer ask canopy instead of restating it.
+ */
+/** Directories whose contents are never published, whatever the settings say. */
+export declare function isSkippedDir(name: string): boolean;
 /**
  * Match a site-relative POSIX path against one exclusion pattern.
  *

package/dist/vault.js CHANGED Viewed

@@ -17,7 +17,7 @@ import path from "node:path";
  * for the proposal that would let a consumer ask canopy instead of restating it.
  */
 /** Directories whose contents are never published, whatever the settings say. */
-function isSkippedDir(name) {
+export function isSkippedDir(name) {
     return name.startsWith(".") || name === "node_modules";
 }
 /**

package/dist/watch.js CHANGED Viewed

@@ -3,6 +3,7 @@ import http from "node:http";
 import { basename, extname, resolve, sep } from "node:path";
 import { watch as watchFiles } from "chokidar";
 import { buildSite } from "./build.js";
+import { isSkippedDir } from "./vault.js";
 /**
  * Serving a build's output locally during authoring.
  *
@@ -240,8 +241,7 @@ export async function watchSite(options) {
                 return false;
             if (resolved === resolvedOut || resolved.startsWith(outWithSep))
                 return true;
-            const name = basename(resolved);
-            return name === "node_modules" || name.startsWith(".");
+            return isSkippedDir(basename(resolved));
         },
     });
     // chokidar.watch() returns before its initial directory scan finishes

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Authoring pipeline for documentation sites: one settings file, integrity checks, and a build.",
   "type": "module",
   "license": "MIT",
@@ -53,7 +53,7 @@
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@iyulab/canopy": "^0.11.2",
+    "@iyulab/canopy": "^0.13.0",
     "chokidar": "^5.0.0"
   }
 }