@dogsbay/format-astro 0.2.0-beta.146 → 0.2.0-beta.148

package/dist/project.d.ts

@@ -1,5 +1,5 @@
 import type { ExportPage, NavItem } from "@dogsbay/types";
-import { type ProductModel } from "@dogsbay/site-files";
+import { type VersionMenu, type ProductModel } from "@dogsbay/site-files";
 import { type BlogEmitConfig } from "./blog.js";
 import { type RedirectsConfig } from "./redirects.js";
 /**
@@ -189,8 +189,21 @@ export interface AstroProjectOptions {
         canonical?: "self";
         noindex?: boolean;
         sitemap?: boolean;
+        badge?: boolean;
         path?: "";
     }>;
+    /**
+     * Units whose home has no page, forwarded to their first page (site-files `homeForwards`):
+     * `[from, to]` site paths without the base path, written as redirects.
+     */
+    homeForwards?: Array<[string, string]>;
+    /** Leave out a redirect the build cannot honour, with a warning, instead of failing. */
+    allowBrokenRedirects?: boolean;
+    /**
+     * The version menu's links and limit (`content.versionMenu`, @dogsbay/site-files
+     * version-menu.ts). With a `products:` block each product's comes from the model.
+     */
+    versionMenu?: VersionMenu;
     /**
      * Which version is the default. Marked in switcherMap.json so
      * the switcher can highlight it, and drives the default-version
@@ -603,6 +616,8 @@ export interface SwitcherMap {
         default?: boolean;
         /** Served at the site root (`path: ""`): its pages have no version segment. */
         root?: boolean;
+        /** "Version: <label>" above each page's title. */
+        badge?: boolean;
     }>;
     /**
      * Declared locales in declaration order. Same role as
@@ -632,6 +647,30 @@ export interface SwitcherMap {
         eol?: boolean;
         prerelease?: boolean;
         default?: boolean;
+        badge?: boolean;
+        home: string;
+    }>>;
+    /**
+     * The version menu's links (hrefs as served, base path included) and limit,
+     * keyed by product name, `_` for the site-wide versions and the unnamed
+     * source. Left out when no menu has any.
+     */
+    versionMenu?: Record<string, {
+        links: Array<{
+            label: string;
+            href: string;
+        }>;
+        limit?: number;
+    }>;
+    /**
+     * With a `products:` block and two or more products: the product menu per
+     * locale (`<locale|_>`), in the block's order, each entry going to the
+     * product's home (its default version, in the locale when it has one) —
+     * site-files `productSwitcher`, as dogsbay-ssg's product menu.
+     */
+    products?: Record<string, Array<{
+        name: string;
+        label: string;
         home: string;
     }>>;
 }

package/dist/project.js

@@ -30,7 +30,7 @@ import { buildSitemapFiles, buildSitemapIndex } from "./sitemap.js";
 import { canonicalPlan } from "./canonical.js";
 import { headMetadata } from "./head-metadata.js";
 import { buildHeadersFile, buildRobotsTxt as buildRobotsTxtFile } from "@dogsbay/site-files";
-import { mergeHeaders, mergeRedirects, productRootRedirects, siteFiles, siteRootTarget, switcher as productSwitcherRows, toPagesScript, toScript, unitKeyString, unitManifest, unitOf, } from "@dogsbay/site-files";
+import { mergeHeaders, mergeRedirects, productRootRedirects, siteFiles, siteRootTarget, switcher as productSwitcherRows, productSwitcher, isVersionMenuHref, versionMenuHref, toPagesScript, toScript, unitKeyString, unitManifest, unitOf, } from "@dogsbay/site-files";
 import { assembleBook, estimateTreeBytes } from "./granularity.js";
 /**
  * The per-topic "Read as single page" affordance (granularity book view).
@@ -1479,6 +1479,8 @@ function emitNotFoundPage(outputDir, options) {
     const sitemap = withBasePath(combined, "/sitemap-index.xml");
     const llms = withBasePath(combined, "/llms.txt");
     const showLlms = options.llmsTxt !== false;
+    // The product menu (only its menu: the page is in no product, so it reads "Product")
+    const productMenu = options.products ? productMenuRows(options.products, combined) !== undefined : false;
     writeFileSync(path, `---
 // AUTO-GENERATED by dogsbay site build — safe to delete; will regenerate next build.
 // To customize this page, remove the marker line above (or modify the file
@@ -1487,7 +1489,8 @@ import "@/styles/global.css";
 import DocsLayout from "@dogsbay/docs-layout/DocsLayout.astro";
 import type { SiteConfig } from "@dogsbay/types";
 import navData from "@/data/nav.json";
-import siteConfigData from "@/data/site.json";
+import siteConfigData from "@/data/site.json";${productMenu ? `
+import switcherMapData from "@/data/switcherMap.json";` : ""}
 const siteConfig = siteConfigData as SiteConfig;
 const favicon = (siteConfigData as { favicon?: string }).favicon;
 ---
@@ -1502,7 +1505,8 @@ const favicon = (siteConfigData as { favicon?: string }).favicon;
   favicon={favicon}
   noindex={true}
   excludeFromSearch={true}
-  ogType="website"
+  ogType="website"${productMenu ? `
+  switcherMap={{ versions: [], byLogicalKey: {}, products: switcherMapData.products } as never}` : ""}
 >
   <article class="docs-prose">
     <h1>Page not found</h1>
@@ -2454,6 +2458,8 @@ export function emitConfigDerivedFiles(outputDir, options, pages = []) {
  */
 function emitRedirects(outputDir, options, pages) {
     const prefix = combinedPrefix(options);
+    // A product's root goes straight to where its default version's home forwards (one hop, no chain to report)
+    const forwarded = new Map(options.homeForwards ?? []);
     const { rules, errors, warnings } = collectRedirects({
         pages: pages.map((p) => ({
             slug: p.slug,
@@ -2462,11 +2468,13 @@ function emitRedirects(outputDir, options, pages) {
             // Front matter paths are relative to the page's language and version (#096): collectRedirects needs its original slug.
             multiSource: p.multiSource,
         })),
-        // A product's root forwards to its default version's home; a redirect the config gives for it wins.
-        config: options.products
-            ? { ...Object.fromEntries(productRootRedirects(options.products)), ...options.redirects }
+        // A product's root forwards to its default version's home, a unit with no home page to its
+        // first page (homeForwards); a redirect the config gives for either wins.
+        config: options.products || options.homeForwards?.length
+            ? { ...Object.fromEntries((options.products ? productRootRedirects(options.products) : []).map(([from, to]) => [from, forwarded.get(to) ?? to])), ...Object.fromEntries(forwarded), ...options.redirects }
             : options.redirects,
         prefix,
+        lenient: options.allowBrokenRedirects === true,
     });
     if (errors.length > 0) {
         throw new Error(`redirects: ${errors.length} problem(s) — refusing to build.\n  - ${errors.join("\n  - ")}`);
@@ -2621,14 +2629,54 @@ export function emitSwitcherMap(pages, outputDir, options) {
         byLogicalKey[key].push(variant);
     }
     const data = { versions, locales, byLogicalKey };
+    const menus = versionMenus(options, combined);
+    if (menus)
+        data.versionMenu = menus;
     if (options.products) {
         data.productVersions = productVersionRows(options.products, combined);
+        const productMenu = productMenuRows(options.products, combined);
+        if (productMenu)
+            data.products = productMenu;
         emitProductDataFiles(pages, outputDir, options, options.products);
     }
     mkdirSync(dataDir, { recursive: true });
     writeFileSync(outPath, JSON.stringify(data, null, 2));
 }
+/** The product menu per locale (`<locale|_>`), or nothing with fewer than two products. */
+function productMenuRows(model, combined) {
+    const locales = model.localeAxis ? [...new Set(model.units.map((u) => u.locale))] : [undefined];
+    const out = {};
+    for (const l of locales) {
+        const rows = productSwitcher(model, l);
+        if (rows.length < 2)
+            continue;
+        out[l ?? "_"] = rows.map((r) => ({ name: r.name, label: r.label, home: `${combined}${r.home}` }));
+    }
+    return Object.keys(out).length ? out : undefined;
+}
 /** Each product's switcher rows per locale (`<product|_>/<locale|_>`), with full home URLs. */
+/** Each version menu's links and limit, per product (`_`: site-wide), hrefs as the site serves them. */
+function versionMenus(options, combined) {
+    const out = {};
+    // A site path may be written with the base path (as redirects take it): dropped, then the served prefix added
+    const base = normalizeBasePath(options.basePath).replace(/\/+$/, "");
+    const unbased = (href) => (base && (href === base || href.startsWith(`${base}/`)) ? href.slice(base.length) || "/" : href);
+    const add = (key, m) => {
+        if (!m)
+            return;
+        // Checked at config load; options built in code are checked again, so a script URL never reaches the page
+        const links = m.links.filter((l) => typeof l.label === "string" && l.label.trim() && isVersionMenuHref(l.href));
+        if (!links.length && m.limit === undefined)
+            return;
+        out[key] = { links: links.map((l) => ({ label: l.label, href: versionMenuHref(unbased(l.href), combined) })), ...(m.limit !== undefined ? { limit: m.limit } : {}) };
+    };
+    if (options.products)
+        for (const p of options.products.products)
+            add(p.name ?? "_", p.versionMenu);
+    else
+        add("_", options.versionMenu);
+    return Object.keys(out).length ? out : undefined;
+}
 function productVersionRows(model, combined) {
     const out = {};
     const locales = model.localeAxis ? [...new Set(model.units.map((u) => u.locale))] : [undefined];
@@ -2645,6 +2693,7 @@ function productVersionRows(model, combined) {
                 ...(r.eol ? { eol: true } : {}),
                 ...(r.prerelease ? { prerelease: true } : {}),
                 ...(r.isDefault ? { default: true } : {}),
+                ...(r.badge ? { badge: true } : {}),
                 home: `${combined}${r.home}`,
             }));
         }
@@ -2715,6 +2764,7 @@ function composeAxisHeader(declared, seen, defaultId, allowEol) {
                 ...(allowEol && d.eol === true ? { eol: true } : {}),
                 ...(allowEol && d.prerelease === true ? { prerelease: true } : {}),
                 ...(allowEol && d.hidden === true ? { hidden: true } : {}),
+                ...(allowEol && d.badge === true ? { badge: true } : {}),
                 ...(defaultId === d.id ? { default: true } : {}),
             });
             seenInDeclared.add(d.id);

package/dist/redirects.d.ts

@@ -54,6 +54,8 @@ export interface CollectRedirectsInput {
     config?: RedirectsConfig;
     /** URL prefix the site is served under (urlBase + basePath), "" when at the root. */
     prefix: string;
+    /** A rule the build cannot honour is left out with a warning instead of failing (`--allow-broken-redirects`). */
+    lenient?: boolean;
 }
 export interface CollectRedirectsResult {
     rules: RedirectRule[];

package/dist/redirects.js

@@ -172,7 +172,7 @@ export function collectRedirects(input) {
         });
     }
     const resolved = resolveRedirects(candidates, {
-        strict: true,
+        strict: input.lenient !== true,
         // A target's "#anchor" or "?query" is not part of the page it names.
         isPage: (path) => livePaths.has(path.split(/[?#]/)[0]),
         cloudflareLimits: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-astro",
-  "version": "0.2.0-beta.146",
+  "version": "0.2.0-beta.148",
   "description": "Astro format plugin for Dogsbay — export TreeNode[] to Astro component markup",
   "type": "module",
   "main": "dist/index.js",
@@ -32,12 +32,12 @@
   "license": "MIT",
   "dependencies": {
     "markdown-it": "^14.3.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.146",
-    "@dogsbay/render-html": "0.2.0-beta.146",
-    "@dogsbay/serialize-core": "0.2.0-beta.146",
-    "@dogsbay/site-files": "0.2.0-beta.146",
-    "@dogsbay/types": "0.2.0-beta.146",
-    "@dogsbay/ui": "0.2.0-beta.146"
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.148",
+    "@dogsbay/serialize-core": "0.2.0-beta.148",
+    "@dogsbay/render-html": "0.2.0-beta.148",
+    "@dogsbay/site-files": "0.2.0-beta.148",
+    "@dogsbay/types": "0.2.0-beta.148",
+    "@dogsbay/ui": "0.2.0-beta.148"
   },
   "repository": {
     "type": "git",