@iyulab/canopy-page 0.8.0 → 0.9.0

package/CHANGELOG.md

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

package/README.md

@@ -217,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/nav.d.ts

@@ -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

@@ -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/site.js

@@ -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

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/canopy-page",
-  "version": "0.8.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.9.0"
+    "@iyulab/canopy": "^0.10.0"
   }
 }