@dogsbay/ssg 0.2.0-beta.144 → 0.2.0-beta.149

package/dist/package/types/core/build.d.ts

@@ -19,6 +19,7 @@ import { type BuildUnit, type SiteConfig } from "./config.js";
 import { type NavCache } from "../theme/regions.js";
 import { ThemeTemplates } from "../theme/page.js";
 import type { CssOptions } from "../theme/css-build.js";
+import type { LinkStyle } from "./config.js";
 import { type FileRef, type TextRef, type TextStream } from "./detach.js";
 import { type TemplateBudget } from "./preprocess.js";
 import { ParseCache } from "@dogsbay/minja/browser";
@@ -31,12 +32,6 @@ export type FileContent = string | Uint8Array | FileRef | TextRef;
 export type SinkContent = string | Uint8Array | FileRef | TextStream;
 /** A built file held in memory (no sink). */
 export type OutputContent = string | Uint8Array;
-/**
- * An SVG with nothing a browser runs when it is opened on its own: no script, event handler,
- * `javascript:` URL, embedded HTML (`foreignObject`), link, animation (which can set a link) or
- * entity declaration. Conservative: an SVG it refuses is left out of an untrusted build, not changed.
- */
-export declare function passiveSvg(text: string): boolean;
 /**
  * Icon name → SVG markup or an emoji (undefined when unknown). `notices`, when the host has it,
  * returns the attribution for the icon sets the pages drew from, for THIRD-PARTY-NOTICES.txt.
@@ -220,8 +215,19 @@ export interface SiteState {
     pageOut: Map<string, string>;
     /** Sitemap files, relative to the site root, by unit prefix. */
     sitemaps: Map<string, string[]>;
-    /** Site-level files a content root supplies itself (robots.txt, _headers…); they win over generated ones. */
+    /** Site-level files a content root supplies itself (robots.txt, the sitemap index); they win over generated ones. */
     supplied: Set<string>;
+    /** The root's own `_headers` and `_redirects`, merged with the generated ones (@dogsbay/site-files host-files.ts). */
+    hostFiles: Map<string, FileContent>;
+    /**
+     * Units with no home page, by prefix: the page their home forwards to (site-relative output),
+     * so the site root and product roots go there in one hop rather than through the home.
+     */
+    homeForward: Map<string, string>;
+    /** `content.static`'s files, folder-relative (dot files left out), read before any unit so links into it resolve. */
+    staticFiles?: Map<string, FileContent>;
+    /** The static file a site path names, as a host serves it (`x/` → `x/index.html`, `x` → `x.html`). */
+    staticFile?: (sitePath: string) => string | undefined;
     /** A page rendered math, so the KaTeX stylesheet and fonts are written. */
     usedMath: boolean;
     /** Rendered diagrams, shared by the units of the build. */
@@ -350,6 +356,9 @@ export declare const copiedPath: (p: string) => boolean;
 /**
  * Whether a file `copiedPath` lets through is copied: an untrusted build takes only passive files
  * and no host configuration ("untrusted"), a sanitizing one no HTML, XML or script ("active").
+ * Passive is site-files' list, shared with the Astro pipeline's importers and `content.static`
+ * (images, fonts, media, documents, archives, data; no HTML, script, CSS or XML), and an SVG only
+ * when `passiveSvgBytes` (strict UTF-8, then one parse of every tag) finds nothing in it that runs.
  * The dev session's changed assets go through it too.
  */
 export declare function assetVerdict(p: string, c: FileContent, untrusted: boolean, sanitizing: boolean): Promise<"copy" | "untrusted" | "active">;
@@ -423,12 +432,14 @@ export interface BuildHooks {
 /** Build one unit again without rendering its pages (they are rendered on request). */
 export declare function rebuildUnitLazy(ctx: BuildContext, unit: BuildUnit): Promise<UnitHandle>;
 export declare function build(input: BuildInput, hooks?: BuildHooks): Promise<BuildResult>;
-/** robots.txt, _headers, the sitemap index and redirects: the files that belong to the whole site. */
 /**
- * The units `--unit` names: by prefix, and a version served at the root
- * (prefix "" or the locale) also by its id. Throws on a name that is no unit.
+ * The units `--unit` names: by prefix; a version served at the root (prefix "", the locale or
+ * the product) also by its id, and inside a product by `<product>/<id>`; and a product by its
+ * name, which is all its versions and locales. Throws on a name that is no unit.
  */
 export declare function selectUnits(allUnits: BuildUnit[], names: string[] | undefined): BuildUnit[];
+/** A static folder's file the build copies: no dot paths, except `.well-known/` (security.txt, assetlinks.json). */
+export declare function staticPath(rel: string): boolean;
 /**
  * Whether a page may render a formula: a math node, or `$` or `:math[` in a
  * prop the renderer parses as markdown (a caption, a callout or card title). A false
@@ -451,6 +462,14 @@ export interface LoadedTheme {
         css: string;
     }[];
 }
+/**
+ * A versionMenu link as a page writes it: an http(s) address as is; a site path from the page's
+ * site root (a leading `basePath` dropped, as redirects do), `/x/` as `x/index.html` and `/x` as
+ * `x.html` (a folder's index needs the slash), with pretty links as the site serves them (`x/`, `x`).
+ * A file (`.pdf`, `.html`, MENU_FILE) is kept. At the site root the link starts with `./`, so
+ * nothing in the path can read as a scheme.
+ */
+export declare function menuHref(href: string, siteRoot: string, style: LinkStyle, basePath?: string): string;
 /**
  * Pages for missing translations (plans/astro-feature-parity.md, batch 2), as the Astro
  * pipeline writes them: where a language lacks a page its version has in the default

package/dist/package/types/core/canonical.d.ts

@@ -31,8 +31,7 @@ export type FrontMatterOf = (path: string, c: FileContent) => Promise<Record<str
  */
 export declare function frontMatterCache(read: Read): FrontMatterOf;
 /**
- * One table per language of the default version, keyed by locale (`""`
- * without a locale axis). Empty when none of the units being built is an
+ * One table per language of the default version and per product, keyed by `tableKey`. Empty when none of the units being built is an
  * older version (then nothing points elsewhere, and nothing is read).
  */
 export declare function defaultTables(cfg: SiteConfig, units: BuildUnit[], built: BuildUnit[], files: Map<string, FileContent>, read: Read, warn?: (m: string) => void, fm?: FrontMatterOf): Promise<Map<string, DefaultTable>>;

package/dist/package/types/core/config.d.ts

@@ -1,3 +1,4 @@
+import { type ProductModel } from "@dogsbay/site-files";
 export type LinkStyle = "html" | "pretty";
 export type TocMode = "top" | "popover" | "rail" | "off";
 export interface VersionDef {
@@ -14,9 +15,43 @@ export interface VersionDef {
     noindex?: boolean;
     /** Override whether the version's pages are in the sitemap. */
     sitemap?: boolean;
-    /** `""`: the version is served at the root (no version segment). Only the default version may set it. */
-    path?: "";
+    /**
+     * The version's URL segment when it is not its id. `""`: served at the root (no version segment),
+     * only on the default version. Any other segment (`latest`) only inside `content.products:`.
+     */
+    path?: string;
+    /** The version's own banner text (`content.products:` only), instead of the standard one. */
+    banner?: string;
+    /** Show "Version: <label>" above the title of the version's pages (Docusaurus's version badge). */
+    badge?: boolean;
+}
+/** A call into @dogsbay/site-files' product model, its config errors reported as ours (dev and the CLI tell them apart). */
+export declare function shared<T>(f: () => T): T;
+/** The versions a unit's product has, and its default. */
+export interface ProductVersions {
+    versions: VersionDef[];
+    defaultVersion?: string;
+    /** The version menu's extras: the product's own `versionMenu:`, else the site's. */
+    menu?: VersionMenu;
 }
+/**
+ * `versionMenu:` (content, or a product in `content.products:`): links listed after the versions
+ * ("All versions" → /archive, Docusaurus's dropdownItemsAfter), and how many versions to list.
+ */
+export interface VersionMenu {
+    /** `href` is a site path (`/archive`, `/archive/`) or an http(s) address. */
+    links: {
+        label: string;
+        href: string;
+    }[];
+    /** List the first `limit` versions (in config order), plus the page's own when it is further down. */
+    limit?: number;
+}
+/**
+ * A product's versions and default: its own with `content.products:`, else the site-wide `versions:`
+ * and `defaultVersion` (the unnamed source's, and every product's without the block).
+ */
+export declare function versionsOf(cfg: Pick<SiteConfig, "versions" | "defaultVersion" | "productVersions" | "versionMenu">, product: string | undefined): ProductVersions;
 export interface LocaleDef {
     id: string;
     label: string;
@@ -72,6 +107,12 @@ export interface SiteConfig {
     routablesFrom: "all" | "nav";
     versions: VersionDef[];
     defaultVersion?: string;
+    /** `content.versionMenu:` (VersionMenu), for every product without its own. */
+    versionMenu?: VersionMenu;
+    /** `content.products:`, read by @dogsbay/site-files' `productModel` (plans/product-versions-ssg.md). Undefined without the block. */
+    products?: ProductModel;
+    /** With `products`: each product's versions and default (key `""` for the unnamed source's), read through `versionsOf`. */
+    productVersions?: Map<string, ProductVersions>;
     locales: LocaleDef[];
     defaultLocale?: string;
     search: boolean;
@@ -109,6 +150,14 @@ export interface SiteConfig {
     /** Extra stylesheets, project-relative, appended after the theme. */
     css: string[];
     breadcrumbs: boolean;
+    /**
+     * UI string overrides (ssg.strings): `{ key: text }` for every language, and `{ <locale>: { key: text } }`
+     * for one, which wins. Keys are those of strings.ts.
+     */
+    strings: {
+        all: Record<string, string>;
+        byLocale: Record<string, Record<string, string>>;
+    };
     /** Fail the build when a layout or partial reads a variable that does not exist (ssg.strictTemplates). */
     strictTemplates: boolean;
     /** Line under the site name in the sidebar header ("Documentation" in the Astro sites). */
@@ -159,6 +208,11 @@ export interface SiteConfig {
      */
     dataDir: string;
     dataDirSet: boolean;
+    /**
+     * `content.static`: a folder served as it is at the site root (Docusaurus `static/`, Astro
+     * `public/`), shared with the Astro pipeline (site-files static-folder.ts). Project-relative.
+     */
+    staticDir?: string;
     /** Click-to-zoom images, from `plugins: [@dogsbay/plugin-image-zoom]` with its options. */
     imageZoom?: {
         background: string;
@@ -250,6 +304,8 @@ export interface RedirectDef {
 }
 export declare class ConfigError extends Error {
 }
+/** `versionMenu:` (links and limit), read and checked by site-files for both pipelines. */
+export declare function versionMenuOf(raw: unknown, where: string): VersionMenu | undefined;
 export declare function parseConfig(text: string | undefined, overrides?: Partial<SiteConfig>): SiteConfig;
 /**
  * The unit a site path belongs to: the one with the longest prefix that
@@ -274,10 +330,26 @@ export interface BuildUnit {
     /** Every source the unit builds, the main one included, in config order. */
     members: UnitMember[];
     version?: string;
+    /** The version's URL segment: its id, its `path` (`latest`), or `""` when served without one. */
+    versionPath?: string;
     locale?: string;
-    /** Output prefix inside the site, e.g. "en/3.31" or "" when neither axis is active. */
+    /**
+     * The named source the unit publishes, when named sources are combined with versions or locales
+     * (a product): its first prefix segment, as the CLI's `/<name>/<locale>/<version>/` order.
+     * Units of one product share it; the unnamed source's units have none.
+     */
+    product?: string;
+    /** Output prefix inside the site, e.g. "en/3.31", "calico/3.31", or "" when no axis is active. */
     prefix: string;
 }
+/**
+ * The prefix of a unit's product and locale, without its version: where the unit's
+ * versions sit side by side ("calico/en", "en", or ""). A version served at the root
+ * (`path: ""`) has this as its prefix.
+ */
+export declare function groupPrefix(u: Pick<BuildUnit, "product" | "locale">): string;
+/** Whether two units are versions or languages of the same product (or both of no product). */
+export declare const sameProduct: (a: Pick<BuildUnit, "product">, b: Pick<BuildUnit, "product">) => boolean;
 /**
  * Expand sources into units. An axis is "active" (adds a URL segment)
  * when the sources carry two or more distinct values for it, or when

package/dist/package/types/core/links.d.ts

@@ -24,6 +24,13 @@ export interface LinkTable {
      * would silently turn `/1/install` (another version) into this unit's page.
      */
     stripPrefixes?: string[];
+    /**
+     * `content.static`: the file a root-absolute link names in the static folder (a site path without
+     * its leading slash: `files/x.yaml`, `about/` for `about/index.html`), else undefined. Links from
+     * any unit resolve to it, relative to the page's place in the site (`unitPrefix`).
+     */
+    staticFile?: (sitePath: string) => string | undefined;
+    unitPrefix?: string;
 }
 /** URL for `targetOut` as seen from the page at `fromOut`, both unit-relative files. */
 export declare function hrefBetween(fromOut: string, targetOut: string, style: LinkStyle): string;

package/dist/package/types/theme/compose.d.ts

@@ -68,9 +68,13 @@ export interface PageModel {
         updatedDatetime?: string;
         hero?: string;
     };
+    /** The product switcher (content.products:); none when absent. */
+    products?: R.SwitchOption[];
     versions: R.SwitchOption[];
     locales: R.SwitchOption[];
     banner?: string;
+    /** The version's label, when the version has `badge: true`: "Version: <label>" above the title. */
+    versionBadge?: string;
     editUrl?: string;
     /** Page URL relative to the page itself, for .md mirror links. */
     mdHref?: string;

package/dist/package/types/theme/regions.d.ts

@@ -59,6 +59,10 @@ export interface SwitchOption {
     current: boolean;
     prefix: string;
     note?: string;
+    /** Shown but not choosable: the product switcher's "none" entry on a page outside every product. */
+    disabled?: boolean;
+    /** A versionMenu link after the versions: the client goes straight to it. */
+    link?: boolean;
 }
 export declare function pageActions(o: {
     mdHref: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/ssg",
-  "version": "0.2.0-beta.144",
+  "version": "0.2.0-beta.149",
   "type": "module",
   "description": "Documentation static site generator for Dogsbay-MD that builds inside Cloudflare Workers and publishes sites that work offline",
   "license": "Apache-2.0",
@@ -49,38 +49,38 @@
     "tailwindcss": "^4.3.2"
   },
   "peerDependencies": {
-    "@dogsbay/elements": "0.2.0-beta.144",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.144",
-    "@dogsbay/format-openapi": "0.2.0-beta.144",
-    "@dogsbay/format-topicmap": "0.2.0-beta.144",
-    "@dogsbay/highlight": "0.2.0-beta.144",
-    "@dogsbay/minja": "0.2.0-beta.144",
-    "@dogsbay/primitives": "0.2.0-beta.144",
-    "@dogsbay/render-html": "0.2.0-beta.144",
-    "@dogsbay/search": "0.2.0-beta.144",
-    "@dogsbay/serialize-core": "0.2.0-beta.144",
-    "@dogsbay/site-check": "0.2.0-beta.144",
-    "@dogsbay/site-files": "0.2.0-beta.144",
-    "@dogsbay/types": "0.2.0-beta.144"
+    "@dogsbay/elements": "0.2.0-beta.149",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.149",
+    "@dogsbay/format-openapi": "0.2.0-beta.149",
+    "@dogsbay/format-topicmap": "0.2.0-beta.149",
+    "@dogsbay/highlight": "0.2.0-beta.149",
+    "@dogsbay/minja": "0.2.0-beta.149",
+    "@dogsbay/primitives": "0.2.0-beta.149",
+    "@dogsbay/render-html": "0.2.0-beta.149",
+    "@dogsbay/search": "0.2.0-beta.149",
+    "@dogsbay/serialize-core": "0.2.0-beta.149",
+    "@dogsbay/site-check": "0.2.0-beta.149",
+    "@dogsbay/site-files": "0.2.0-beta.149",
+    "@dogsbay/types": "0.2.0-beta.149"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.12.1",
     "@cloudflare/workers-types": "^5.20260921.1",
-    "@dogsbay/elements": "0.2.0-beta.144",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.144",
-    "@dogsbay/format-openapi": "0.2.0-beta.144",
-    "@dogsbay/format-topicmap": "0.2.0-beta.144",
-    "@dogsbay/highlight": "0.2.0-beta.144",
-    "@dogsbay/icons": "0.2.0-beta.144",
-    "@dogsbay/minja": "0.2.0-beta.144",
-    "@dogsbay/primitives": "0.2.0-beta.144",
-    "@dogsbay/render-html": "0.2.0-beta.144",
-    "@dogsbay/search": "0.2.0-beta.144",
-    "@dogsbay/serialize-core": "0.2.0-beta.144",
-    "@dogsbay/site-check": "0.2.0-beta.144",
-    "@dogsbay/site-files": "0.2.0-beta.144",
-    "@dogsbay/types": "0.2.0-beta.144",
-    "@dogsbay/ui": "0.2.0-beta.144",
+    "@dogsbay/elements": "0.2.0-beta.149",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.149",
+    "@dogsbay/format-openapi": "0.2.0-beta.149",
+    "@dogsbay/format-topicmap": "0.2.0-beta.149",
+    "@dogsbay/highlight": "0.2.0-beta.149",
+    "@dogsbay/icons": "0.2.0-beta.149",
+    "@dogsbay/minja": "0.2.0-beta.149",
+    "@dogsbay/primitives": "0.2.0-beta.149",
+    "@dogsbay/render-html": "0.2.0-beta.149",
+    "@dogsbay/search": "0.2.0-beta.149",
+    "@dogsbay/serialize-core": "0.2.0-beta.149",
+    "@dogsbay/site-check": "0.2.0-beta.149",
+    "@dogsbay/site-files": "0.2.0-beta.149",
+    "@dogsbay/types": "0.2.0-beta.149",
+    "@dogsbay/ui": "0.2.0-beta.149",
     "@mermanjs/web": "0.7.0",
     "@playwright/test": "1.61.1",
     "@types/node": "^22.10.0",