npm - @iyulab/canopy-page - Versions diffs - 0.6.0 → 0.7.0 - Mend

@iyulab/canopy-page 0.6.0 → 0.7.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 (7) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,28 @@ 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.7.0] — 2026-08-09
+### Added
+- **A `strings` field** overriding the reader chrome's own built-in text — search, the theme
+  toggle, and the navigation landmarks. `lang` only ever changed what `<html lang>` declares;
+  this text is canopy's own UI, not vault content, so it stayed English regardless. No built-in
+  translation table, the same reasoning `home.label` already follows. Threaded to canopy as a
+  JSON `--strings` flag.
+- **`check` warns about a root-absolute reference that resolves today but would only be correct
+  if the site is served from the domain root**, whenever `siteUrl` already declares a non-root
+  mount path — reusing the one signal a settings file already carries about where the site is
+  served from, rather than requiring a new field.
+### Changed
+- **`home.url` no longer requires an absolute http(s) URL.** A relative one (a sibling of the
+  published site, at the same origin) is now resolved against each page's depth, the same as
+  every other internal link canopy writes — useful when the site is mounted at a sub-path whose
+  absolute origin differs between environments.
+- **Upgraded to canopy 0.8.0**, the release the relative `home.url` and `strings` support build on.
 ## [0.6.0] — 2026-08-09
 ### Added

package/README.md CHANGED Viewed

@@ -108,10 +108,11 @@ unpublished.
 | `title` | Site name. Defaults to the folder's name |
 | `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 |
+| `strings` | Overrides for the reader chrome's own text — `search`, `toggleTheme`, `siteNav`, `pageNav`, `onThisPage`. `lang` only changes what `<html lang>` declares; this text is canopy's own UI, not vault content, so it stays English otherwise. No built-in translation table — the same reasoning `home.label` already follows: link text has to be written in the site's own language. Keys left out keep their English default |
 | `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 |
+| `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` is absolute when the target is a different origin, relative when it is a sibling of the published site (each page resolves it against its own depth, the same as every other internal link); 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 |
@@ -208,7 +209,9 @@ Warnings — reported, and the build continues:
   path resolves depends on what the site is served from, which is not a checker's to know — but a
   site served from its own root is the ordinary case, and a `public/`-style folder that other
   generators map onto the root does not exist here, so these silently 404. A warning rather than
-  an error, because mounting the site elsewhere would make it right
+  an error, because mounting the site elsewhere would make it right. When `siteUrl` already
+  declares a sub-path mount, a root-absolute reference warns even if it resolves today, since that
+  is the one case the checker can actually judge
 - An `exclude` pattern that matched nothing, which usually means a path written from the wrong
   place. Extension patterns are left alone: `*.tmp` in a site with no scratch files is a rule
   about what may never ship, not a claim that something is there

package/dist/build.js CHANGED Viewed

@@ -34,6 +34,7 @@ export function canopyArgs(site, out, navPath, searchAssets) {
         ...(settings.home === undefined
             ? []
             : ["--home-url", settings.home.url, "--home-label", settings.home.label]),
+        ...(settings.strings === undefined ? [] : ["--strings", JSON.stringify(settings.strings)]),
         ...(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

package/dist/check.js CHANGED Viewed

@@ -28,6 +28,31 @@ import { toPageKey } from "./vault.js";
 function isRootAbsolute(url) {
     return url.startsWith("/") && !url.startsWith("//");
 }
+/**
+ * The mount path `siteUrl` declares, when it says the site stands under a
+ * sub-path rather than a domain root.
+ *
+ * `siteUrl` is the one place settings already say where the site is served
+ * from — set today only to address a sitemap, but its path component answers
+ * exactly the question a root-absolute reference otherwise leaves open.
+ */
+function siteBasePath(site) {
+    const { siteUrl } = site.settings;
+    if (siteUrl === undefined)
+        return undefined;
+    // settings.ts only checks the "http(s)://" prefix, which "http://" itself
+    // satisfies without naming a host — malformed enough that `new URL` throws.
+    // That is a settings mistake for `sitemapXml` to report, not a reason for
+    // this unrelated check to crash the whole run.
+    let pathname;
+    try {
+        ({ pathname } = new URL(siteUrl));
+    }
+    catch {
+        return undefined;
+    }
+    return pathname === "/" ? undefined : pathname;
+}
 /**
  * Does anything published sit at this path — a page, a copied file, or the index
  * page a directory is entered by?
@@ -81,14 +106,20 @@ export async function referenceFindings(site) {
             const url = targetPath(reference.target);
             if (isRootAbsolute(url)) {
                 const atRoot = decodeTarget(url.replace(/^\/+/, "")) ?? url.replace(/^\/+/, "");
-                if (atRoot === "" || existsInSite(site, atRoot))
+                const resolves = atRoot === "" || existsInSite(site, atRoot);
+                const basePath = siteBasePath(site);
+                if (resolves && basePath === undefined)
                     continue;
                 findings.push({
                     level: "warning",
-                    message: `${where}: ${reference.kind} "${reference.target}" — ` +
-                        `nothing is published at "${atRoot}". A root-absolute path resolves ` +
-                        "against wherever the site is served from, so this is right only if " +
-                        "something else answers it there",
+                    message: resolves
+                        ? `${where}: ${reference.kind} "${reference.target}" resolves only when the ` +
+                            `site is served from the domain root, but settings.siteUrl declares it is ` +
+                            `mounted under "${basePath}"`
+                        : `${where}: ${reference.kind} "${reference.target}" — ` +
+                            `nothing is published at "${atRoot}". A root-absolute path resolves ` +
+                            "against wherever the site is served from, so this is right only if " +
+                            "something else answers it there",
                 });
                 continue;
             }

package/dist/settings.d.ts CHANGED Viewed

@@ -111,6 +111,23 @@ export interface Settings {
      * relative path against.
      */
     rehypePlugins?: string[];
+    /**
+     * Overrides for the reader chrome's own text — search, the theme toggle,
+     * and the navigation landmarks.
+     *
+     * `lang` changes what `<html lang>` declares, but that text is canopy's own
+     * UI, not vault content, so `lang` alone leaves it English. There is no
+     * built-in translation table: like `home.label`, link text has to be
+     * written in the site's own language, and canopy cannot know what that
+     * language calls "Search". Keys left out keep their English default.
+     */
+    strings?: {
+        search?: string;
+        toggleTheme?: string;
+        siteNav?: string;
+        pageNav?: string;
+        onThisPage?: string;
+    };
 }
 /**
  * Parse and validate a settings file from JSON text.

package/dist/settings.js CHANGED Viewed

@@ -50,9 +50,11 @@ const SETTINGS_KEYS = new Set([
     "home",
     "siteUrl",
     "rehypePlugins",
+    "strings",
 ]);
 const SECTION_KEYS = new Set(["path", "label", "order", "items"]);
 const HOME_KEYS = new Set(["url", "label"]);
+const STRINGS_KEYS = new Set(["search", "toggleTheme", "siteNav", "pageNav", "onThisPage"]);
 const NAV_ITEM_KEYS = new Set(["label", "path", "items"]);
 /**
  * Unknown keys are rejected rather than ignored.
@@ -227,7 +229,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 } = value;
+    const { title, description, lang, icon, tokens, exclude, sections, logo, home, siteUrl, rehypePlugins, strings, } = value;
     if (title !== undefined)
         asString(title, "settings.title");
     if (description !== undefined)
@@ -256,12 +258,11 @@ export function parseSettings(json) {
             fail('settings.home.url: needed alongside "label"');
         if (object.label === undefined)
             fail('settings.home.label: needed alongside "url"');
+        // Absolute when the target is a different origin, relative when it is a
+        // sibling of the published site (a product this documentation is mounted
+        // beside) — canopy resolves a relative one against each page's depth, the
+        // same way it resolves every other internal link.
         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) {
@@ -270,6 +271,15 @@ export function parseSettings(json) {
             fail(`settings.siteUrl: "${url}" must be an absolute http(s) URL`);
         }
     }
+    let parsedStrings;
+    if (strings !== undefined) {
+        const object = asObject(strings, "settings.strings", "expected an object");
+        rejectUnknownKeys(object, STRINGS_KEYS, "settings.strings");
+        parsedStrings = {};
+        for (const key of Object.keys(object)) {
+            parsedStrings[key] = asString(object[key], `settings.strings.${key}`);
+        }
+    }
     return {
         ...(title === undefined ? {} : { title: title }),
         ...(description === undefined ? {} : { description: description }),
@@ -292,6 +302,7 @@ export function parseSettings(json) {
         ...(logo === undefined ? {} : { logo: asRelativePath(logo, "settings.logo") }),
         ...(parsedHome === undefined ? {} : { home: parsedHome }),
         ...(siteUrl === undefined ? {} : { siteUrl: siteUrl }),
+        ...(parsedStrings === undefined ? {} : { strings: parsedStrings }),
         ...(rehypePlugins === undefined
             ? {}
             : {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Authoring pipeline for documentation sites: one settings file, integrity checks, and a build.",
   "type": "module",
   "license": "MIT",
@@ -46,11 +46,13 @@
     "@biomejs/biome": "^2.5.0",
     "@iyulab/declart": "^0.20.0",
     "@types/node": "^25.9.3",
+    "playwright": "^1.62.1",
     "rehype-declart": "^0.20.0",
+    "rehype-mermaid": "^3.0.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
   },
   "dependencies": {
-    "@iyulab/canopy": "^0.7.0"
+    "@iyulab/canopy": "^0.8.0"
   }
 }