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

@iyulab/canopy-page 0.13.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 (10) hide show

package/CHANGELOG.md CHANGED Viewed

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

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
@@ -53,6 +57,11 @@ go away.
 - **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

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

@@ -18,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";
@@ -222,6 +223,45 @@ export async function siteFindings(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/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.13.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.12.0",
+    "@iyulab/canopy": "^0.13.0",
     "chokidar": "^5.0.0"
   }
 }