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

@iyulab/canopy-page 0.7.0 → 0.9.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 (11) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,41 @@ 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.9.0] — 2026-08-11
+### Added
+- **`check` warns when a section's sidebar heading falls back to a raw directory name.** A
+  section with no `label` and no index page was already published this way — the fallback
+  itself is sound — but silently: the directory name it falls back to is a filesystem detail,
+  not a name an author chose, and there was previously no way to find out a sidebar's top-level
+  heading was about to read that way instead. `check`/`build` now report it as a warning (the
+  build still succeeds) naming the section and the label it fell back to.
+### Changed
+- **Upgraded to canopy 0.10.0**, the release the heading custom-id syntax, the sidebar
+  active-page tint, and page-content typography build on.
+## [0.8.0] — 2026-08-11
+### Added
+- **`strings` gains `indexTitle`, `backlinks`, and `searchFailed`.** The `strings` field
+  covered the reader chrome's search/theme-toggle/navigation text, but three more reader-facing
+  literals stayed hardcoded English regardless of `lang` and `strings`: the auto-generated
+  contents page's title/heading (`indexTitle`), a page's "Linked references" section heading
+  (`backlinks`), and the client search's failure message (`searchFailed`). All three follow the
+  same pattern as the existing five keys — optional override, English default when unset.
+- **`$schema` support.** A settings file can now name
+  [`settings.schema.json`](https://iyulab.github.io/canopy-page/settings.schema.json), hosted
+  at that fixed URL, so an editor offers completion and inline validation for every field —
+  canopy-page itself already read and ignored this key, unvalidated.
+### Changed
+- **Upgraded to canopy 0.9.0**, the release `indexTitle` and `backlinks` build on.
 ## [0.7.0] — 2026-08-09
 ### Added
@@ -29,6 +64,13 @@ to it — its fields, its validation, and what the checks reject — are what th
   absolute origin differs between environments.
 - **Upgraded to canopy 0.8.0**, the release the relative `home.url` and `strings` support build on.
+### Fixed
+- **A `siteUrl` missing its host (`"http://"` alone, for instance) no longer crashes `check`.**
+  Only the scheme was validated, so `new URL()` threw on the rest and took the whole check run
+  down with it; a `siteUrl` that fails to parse is now treated as absent for the sub-path warning,
+  leaving `sitemapXml` to report the malformed value on its own terms.
 ## [0.6.0] — 2026-08-09
 ### Added

package/README.md CHANGED Viewed

@@ -87,6 +87,7 @@ unpublished.
 ```json
 {
+  "$schema": "https://iyulab.github.io/canopy-page/settings.schema.json",
   "title": "Product Help",
   "description": "How to use it",
   "lang": "en-GB",
@@ -105,10 +106,11 @@ unpublished.
 | Field | Meaning |
 |---|---|
+| `$schema` | Optional. Points an editor (VS Code, JetBrains) at [`settings.schema.json`](https://iyulab.github.io/canopy-page/settings.schema.json) for completion and inline validation. Read and ignored by canopy-page itself |
 | `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 |
+| `strings` | Overrides for the reader chrome's own text — `search`, `toggleTheme`, `siteNav`, `pageNav`, `onThisPage`, `indexTitle` (the auto-generated contents page's title/heading), `backlinks` (a page's "linked references" heading), `searchFailed` (the client search's failure message). `lang` only changes what `<html lang>` declares; this text is canopy's own UI or canopy-page's own search script, 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 |
@@ -215,6 +217,9 @@ Warnings — reported, and the build continues:
 - 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
+- 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
 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-bundle.d.ts CHANGED Viewed

@@ -1,5 +1,14 @@
-/** The single script every canopy-page site carries via canopy's `--script`. */
-export declare function assembleScript(): Promise<string>;
+/**
+ * The single script every canopy-page site carries via canopy's `--script`.
+ *
+ * `searchFailed` overrides the message `search.js` shows when its fetch of the
+ * search index fails — the one reader-facing string in canopy-page's own
+ * assets, `settings.strings.searchFailed` in the settings surface. The other
+ * two files carry no site-specific text, so only `search.js` takes this
+ * substitution; a source literal, not a template placeholder, so the shipped
+ * asset stays valid, readable JavaScript on its own.
+ */
+export declare function assembleScript(searchFailed?: string): Promise<string>;
 /**
  * CSS canopy-page contributes on top of a site's own tokens, carried via
  * canopy's `--tokens-css` — the same channel a site's own `settings.tokens`

package/dist/assets-bundle.js CHANGED Viewed

@@ -21,14 +21,31 @@ const ASSETS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "asse
 async function readAsset(name) {
     return readFile(path.join(ASSETS_DIR, name), "utf8");
 }
-/** The single script every canopy-page site carries via canopy's `--script`. */
-export async function assembleScript() {
+/** The literal `search.js` falls back to when no override is given — the substitution target. */
+const SEARCH_FAILED_DEFAULT = "Search failed to load.";
+/**
+ * The single script every canopy-page site carries via canopy's `--script`.
+ *
+ * `searchFailed` overrides the message `search.js` shows when its fetch of the
+ * search index fails — the one reader-facing string in canopy-page's own
+ * assets, `settings.strings.searchFailed` in the settings surface. The other
+ * two files carry no site-specific text, so only `search.js` takes this
+ * substitution; a source literal, not a template placeholder, so the shipped
+ * asset stays valid, readable JavaScript on its own.
+ */
+export async function assembleScript(searchFailed) {
     const [search, scrollspy, themeToggle] = await Promise.all([
         readAsset("search.js"),
         readAsset("scrollspy.js"),
         readAsset("theme-toggle.js"),
     ]);
-    return `${search}\n${scrollspy}\n${themeToggle}`;
+    // A function replacer, not a replacement string: String.replace treats
+    // "$&"/"$'"/"$$" etc. in a replacement string as patterns, and a site
+    // author's searchFailed text is free to contain a literal "$".
+    const searchWithStrings = searchFailed === undefined
+        ? search
+        : search.replace(JSON.stringify(SEARCH_FAILED_DEFAULT), () => JSON.stringify(searchFailed));
+    return `${searchWithStrings}\n${scrollspy}\n${themeToggle}`;
 }
 /**
  * CSS canopy-page contributes on top of a site's own tokens, carried via

package/dist/build.js CHANGED Viewed

@@ -80,7 +80,7 @@ export async function buildSite({ dir, out }) {
         const tokensCssPath = path.join(workDir, "tokens.css");
         await writeFile(tokensCssPath, await assembleTokensCss(userTokensCss), "utf8");
         const scriptPath = path.join(workDir, "script.js");
-        await writeFile(scriptPath, await assembleScript(), "utf8");
+        await writeFile(scriptPath, await assembleScript(site.settings.strings?.searchFailed), "utf8");
         const code = await runCanopy(canopyArgs(site, path.resolve(out), navPath, { tokensCssPath, scriptPath }));
         // 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

package/dist/nav.d.ts CHANGED Viewed

@@ -42,6 +42,13 @@ export interface NavTranslation {
     orphans: string[];
     /** Pages the settings place more than once. */
     duplicates: string[];
+    /**
+     * Top-level section paths labeled by their own directory name because the
+     * settings file wrote no `label` and the section has no index page to name
+     * it instead — see `NavReport.rawSlugLabels` for why this is scoped to
+     * sections rather than every subdirectory that falls back the same way.
+     */
+    rawSlugLabels: string[];
 }
 /**
  * Turn settings plus the site's pages into the spec canopy builds from.

package/dist/nav.js CHANGED Viewed

@@ -162,7 +162,10 @@ function translateSection(section, index, report) {
     // Same rule as a derived directory: the page fronting a section names it, and
     // only a section with no index page needs a name written for it here. A label
     // in the settings file still wins — that is what writing one is for.
-    const label = section.label ?? (sectionIndex === undefined ? lastSegment(section.path) : undefined);
+    const usesRawSlugLabel = section.label === undefined && sectionIndex === undefined;
+    if (usesRawSlugLabel)
+        report.rawSlugLabels.push(section.path);
+    const label = section.label ?? (usesRawSlugLabel ? lastSegment(section.path) : undefined);
     return {
         ...(label === undefined ? {} : { label }),
         ...(sectionIndex === undefined ? {} : { path: sectionIndex }),
@@ -191,14 +194,20 @@ function narrowTo(pages, index) {
 export function translateNav(settings, index) {
     const sections = settings.sections ?? [];
     if (sections.length === 0) {
-        return { missing: [], orphans: [], duplicates: [] };
+        return { missing: [], orphans: [], duplicates: [], rawSlugLabels: [] };
     }
     const placements = new Map();
     const missing = [];
+    const rawSlugLabels = [];
     const place = (page) => {
         placements.set(page, (placements.get(page) ?? 0) + 1);
     };
-    const report = { missing, place, isPlaced: (page) => placements.has(page) };
+    const report = {
+        missing,
+        place,
+        isPlaced: (page) => placements.has(page),
+        rawSlugLabels,
+    };
     const items = sections.map((section) => translateSection(section, index, report));
     // The root index is the site's home page: it is reached without navigation, so
     // it is neither placed by a section nor counted as something nobody placed.
@@ -231,5 +240,5 @@ export function translateNav(settings, index) {
         .filter(([, count]) => count > 1)
         .map(([page]) => page)
         .sort();
-    return { spec: { items }, missing, orphans, duplicates };
+    return { spec: { items }, missing, orphans, duplicates, rawSlugLabels };
 }

package/dist/settings.d.ts CHANGED Viewed

@@ -127,8 +127,31 @@ export interface Settings {
         siteNav?: string;
         pageNav?: string;
         onThisPage?: string;
+        /** Title and heading of the auto-generated contents page at the site root. */
+        indexTitle?: string;
+        /** Heading over a page's list of pages that link to it. */
+        backlinks?: string;
+        /**
+         * Message shown in place of results when the client search index fails to
+         * load. This key rides the same JSON `--strings` flag as every other one
+         * here (canopy just never reads it), but it is consumed by canopy-page's
+         * own script assembly (`assembleScript`), not by canopy — every other key
+         * styles canopy's own shell markup, this one styles canopy-page's own
+         * search UI (see `assets/search.js`).
+         */
+        searchFailed?: string;
     };
 }
+/**
+ * Exported so `settings.schema.json` (`examples/site/`) can be tested against
+ * the parser's own allowlists rather than a hand-copied duplicate — the two
+ * are otherwise free to drift silently apart as fields are added.
+ */
+export declare const SETTINGS_KEYS: Set<string>;
+export declare const SECTION_KEYS: Set<string>;
+export declare const HOME_KEYS: Set<string>;
+export declare const STRINGS_KEYS: Set<string>;
+export declare const NAV_ITEM_KEYS: Set<string>;
 /**
  * Parse and validate a settings file from JSON text.
  *

package/dist/settings.js CHANGED Viewed

@@ -38,7 +38,12 @@ function fail(message) {
  * so it has to survive a strict key check.
  */
 const IGNORED_KEYS = new Set(["$schema"]);
-const SETTINGS_KEYS = new Set([
+/**
+ * Exported so `settings.schema.json` (`examples/site/`) can be tested against
+ * the parser's own allowlists rather than a hand-copied duplicate — the two
+ * are otherwise free to drift silently apart as fields are added.
+ */
+export const SETTINGS_KEYS = new Set([
     "title",
     "description",
     "lang",
@@ -52,10 +57,19 @@ const SETTINGS_KEYS = new Set([
     "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"]);
+export const SECTION_KEYS = new Set(["path", "label", "order", "items"]);
+export const HOME_KEYS = new Set(["url", "label"]);
+export const STRINGS_KEYS = new Set([
+    "search",
+    "toggleTheme",
+    "siteNav",
+    "pageNav",
+    "onThisPage",
+    "indexTitle",
+    "backlinks",
+    "searchFailed",
+]);
+export const NAV_ITEM_KEYS = new Set(["label", "path", "items"]);
 /**
  * Unknown keys are rejected rather than ignored.
  *

package/dist/site.js CHANGED Viewed

@@ -94,6 +94,20 @@ export function navFindings(nav) {
                 nav.orphans.map((page) => `  ${page}`).join("\n"),
         });
     }
+    for (const path of nav.rawSlugLabels) {
+        // Publishable either way — canopy-page's own fallback is sound, and the
+        // build is not wrong to use it. What is wrong is doing so silently: the
+        // directory name it falls back to is written for a filesystem, not a
+        // reader, and the author has no other way to find out their sidebar's
+        // top-level heading is about to read that way instead of a name they chose.
+        const slug = path.split("/").pop() ?? path;
+        findings.push({
+            level: "warning",
+            message: `settings: section "${path}" has no "label" and no index page, ` +
+                `so its sidebar heading falls back to the directory name "${slug}". ` +
+                'Add a "label", or an index page for the section to name itself',
+        });
+    }
     return findings;
 }
 /** Print findings in the order given, and report whether any of them stops a build. */

package/package.json CHANGED Viewed

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