@dogsbay/ssg 0.2.0-beta.146 → 0.2.0-beta.151

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

@@ -1,4 +1,4 @@
-import { type ProductModel } from "@dogsbay/site-files";
+import { type SiteChrome, type ProductModel } from "@dogsbay/site-files";
 export type LinkStyle = "html" | "pretty";
 export type TocMode = "top" | "popover" | "rail" | "off";
 export interface VersionDef {
@@ -22,6 +22,8 @@ export interface VersionDef {
     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;
@@ -29,12 +31,27 @@ export declare function shared<T>(f: () => T): T;
 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">, product: string | undefined): ProductVersions;
+export declare function versionsOf(cfg: Pick<SiteConfig, "versions" | "defaultVersion" | "productVersions" | "versionMenu">, product: string | undefined): ProductVersions;
 export interface LocaleDef {
     id: string;
     label: string;
@@ -82,7 +99,15 @@ export interface SiteConfig {
     basePath: string;
     repoUrl?: string;
     editUri?: string;
+    /** Inline Markdown (site-files `inlineMarkdownHtml`), as `chrome.copyright`. */
     copyright?: string;
+    /**
+     * The site's chrome, read and checked by site-files `siteChrome` for both pipelines: the logo,
+     * the first-visit colour mode, the announcement bar, header links and icons, footer columns and
+     * icons (`site.logo`, `site.colorMode`, `site.announcement`, `header:`, `footer:`). Its
+     * `warnings` are reported by the build. plans/site-chrome.md.
+     */
+    chrome: SiteChrome;
     linkStyle: LinkStyle;
     attributes: Record<string, unknown>;
     sources: SourceDef[];
@@ -90,6 +115,8 @@ 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`. */
@@ -131,6 +158,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). */
@@ -181,6 +216,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;
@@ -272,6 +312,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
@@ -338,8 +380,8 @@ export declare function projectPath(unit: BuildUnit, path: string): string;
 export declare const TOPIC_MAP: RegExp;
 /**
  * The project folders and files a build reads: every source's root, the theme folder, extra
- * stylesheets, the folder of each source's own nav file (a topic map's includes sit beside it), and
- * the data folders (the site's, and any source's own; one that does not exist is not read).
+ * stylesheets, the folder of each source's own nav file (a topic map's includes sit beside it), the
+ * data folders (the site's, and any source's own; one that does not exist is not read), and the logo files.
  * [""] when a source is the whole project. What the CLI reads from disk, and a dev session watches.
  */
 export declare function projectRoots(cfg: SiteConfig): string[];

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;
@@ -37,3 +44,11 @@ export declare function createResolver(table: LinkTable, page: {
     source: string;
     out: string;
 }): LinkResolver;
+/**
+ * A versionMenu or site chrome 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;

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;
@@ -85,6 +89,11 @@ export interface PageModel {
     math?: boolean;
     /** The page's front matter, for templates (`page.meta.*`). */
     meta?: Record<string, unknown>;
+    /** The site logo's files as the build wrote them, from the site root (`_dogsbay/site/logo-light.svg`); none without `site.logo` or when it was left out. */
+    logo?: {
+        light: string;
+        dark?: string;
+    };
     /** Search-engine and social metadata; see seo.ts. */
     seo?: Omit<SeoInput, "title" | "siteName" | "description" | "headings" | "tags" | "lastUpdated">;
     t: (k: string) => string;
@@ -96,4 +105,11 @@ export interface PageModel {
  * template can only read plain data.
  */
 export declare function plainData(v: unknown): unknown;
+/**
+ * What a reader's close is stored under (`db-announcement-closed:<key>`): the id after the site's
+ * URL path and base path, as the Astro pipeline writes it (`/docs#launch-2026`), so sites on one
+ * host keep their own. Without either, the site's name: sites published under paths of the Worker,
+ * or opened from disk, share an origin too.
+ */
+export declare function announcementKey(cfg: SiteConfig): string;
 export declare function composePage(p: PageModel, cfg: SiteConfig, templates: ThemeTemplates): Promise<string>;

package/dist/package/types/theme/docs-layout/site-chrome.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The site's chrome as DocsLayout draws it: the `chrome` object format-astro writes into
+ * site.json (its `chromeData`), links already carrying the site's prefix, texts already HTML
+ * (@dogsbay/site-files inline Markdown), icons already SVG. dogsbay-ssg draws the same keys with
+ * its own markup and these classes. See plans/site-chrome.md.
+ */
+export interface SiteChromeLink {
+    label: string;
+    href: string;
+}
+export interface SiteChromeMenu {
+    label: string;
+    items: SiteChromeLink[];
+}
+export interface SiteChromeSocial {
+    label: string;
+    href: string;
+    svg: string;
+}
+export interface SiteChromeData {
+    colorMode?: "light" | "dark" | "system";
+    logo?: {
+        light: string;
+        dark?: string;
+        alt: string;
+        replacesName: boolean;
+    };
+    /** `key` (format-astro): the stored id, with the site's prefix; older site.json files have only `id`. */
+    announcement?: {
+        id: string;
+        key?: string;
+        html: string;
+        tone: string;
+        closeable: boolean;
+    };
+    header?: {
+        links: Array<SiteChromeLink | SiteChromeMenu>;
+        social: SiteChromeSocial[];
+    };
+    footer?: {
+        columns: Array<{
+            title: string;
+            links: SiteChromeLink[];
+        }>;
+        social: SiteChromeSocial[];
+    };
+}
+export declare const isMenu: (l: SiteChromeLink | SiteChromeMenu) => l is SiteChromeMenu;
+/** An http(s) address on another site: opened as the version menu's are, in the same tab, marked external for link icons. */
+export declare const isExternal: (href: string) => boolean;
+/** The announcement's colours by tone: the callout tokens, so the theme and dark mode apply. */
+export declare const ANNOUNCEMENT_TONE_CLASS: Record<string, string>;

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

@@ -1,15 +1,19 @@
 import type { NavNode } from "../core/nav.js";
-/** Icons the region partials place (pager chevrons, the "Powered by" mark). */
+/** Icons the region partials place (pager chevrons, the "Powered by" mark, the header menus' chevron, the announcement's close). */
 export declare const ICONS: {
+    chevronDown: string;
+    close: string;
     chevronLeft: string;
     chevronRight: string;
     layers: string;
 };
 export declare const BOOK_ICON: string;
+/** `links`: the header's links as a list, shown here below lg (DocsLayout's SidebarGroup with HeaderLinks layout="list"). */
 export declare function sidebar(opts: {
     header: string;
     nav: string;
     label: string;
+    links?: string;
 }): string;
 export declare function sidebarTrigger(label: string): string;
 export interface NavOptions {
@@ -52,13 +56,16 @@ export declare function compactNav(nodes: NavNode[], href: (slug: string) => str
 export declare function navSize(nodes: NavNode[]): number;
 export declare function searchButton(label: string): string;
 export declare function themeToggle(label: string): string;
-export declare function repoLink(url: string, label: string): string;
 export interface SwitchOption {
     label: string;
     href: string;
     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.146",
+  "version": "0.2.0-beta.151",
   "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.146",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.146",
-    "@dogsbay/format-openapi": "0.2.0-beta.146",
-    "@dogsbay/format-topicmap": "0.2.0-beta.146",
-    "@dogsbay/highlight": "0.2.0-beta.146",
-    "@dogsbay/minja": "0.2.0-beta.146",
-    "@dogsbay/primitives": "0.2.0-beta.146",
-    "@dogsbay/render-html": "0.2.0-beta.146",
-    "@dogsbay/search": "0.2.0-beta.146",
-    "@dogsbay/serialize-core": "0.2.0-beta.146",
-    "@dogsbay/site-check": "0.2.0-beta.146",
-    "@dogsbay/site-files": "0.2.0-beta.146",
-    "@dogsbay/types": "0.2.0-beta.146"
+    "@dogsbay/elements": "0.2.0-beta.151",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.151",
+    "@dogsbay/format-openapi": "0.2.0-beta.151",
+    "@dogsbay/format-topicmap": "0.2.0-beta.151",
+    "@dogsbay/highlight": "0.2.0-beta.151",
+    "@dogsbay/minja": "0.2.0-beta.151",
+    "@dogsbay/primitives": "0.2.0-beta.151",
+    "@dogsbay/render-html": "0.2.0-beta.151",
+    "@dogsbay/search": "0.2.0-beta.151",
+    "@dogsbay/serialize-core": "0.2.0-beta.151",
+    "@dogsbay/site-check": "0.2.0-beta.151",
+    "@dogsbay/site-files": "0.2.0-beta.151",
+    "@dogsbay/types": "0.2.0-beta.151"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.12.1",
     "@cloudflare/workers-types": "^5.20260921.1",
-    "@dogsbay/elements": "0.2.0-beta.146",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.146",
-    "@dogsbay/format-openapi": "0.2.0-beta.146",
-    "@dogsbay/format-topicmap": "0.2.0-beta.146",
-    "@dogsbay/highlight": "0.2.0-beta.146",
-    "@dogsbay/icons": "0.2.0-beta.146",
-    "@dogsbay/minja": "0.2.0-beta.146",
-    "@dogsbay/primitives": "0.2.0-beta.146",
-    "@dogsbay/render-html": "0.2.0-beta.146",
-    "@dogsbay/search": "0.2.0-beta.146",
-    "@dogsbay/serialize-core": "0.2.0-beta.146",
-    "@dogsbay/site-check": "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/elements": "0.2.0-beta.151",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.151",
+    "@dogsbay/format-openapi": "0.2.0-beta.151",
+    "@dogsbay/format-topicmap": "0.2.0-beta.151",
+    "@dogsbay/highlight": "0.2.0-beta.151",
+    "@dogsbay/icons": "0.2.0-beta.151",
+    "@dogsbay/minja": "0.2.0-beta.151",
+    "@dogsbay/primitives": "0.2.0-beta.151",
+    "@dogsbay/render-html": "0.2.0-beta.151",
+    "@dogsbay/search": "0.2.0-beta.151",
+    "@dogsbay/serialize-core": "0.2.0-beta.151",
+    "@dogsbay/site-check": "0.2.0-beta.151",
+    "@dogsbay/site-files": "0.2.0-beta.151",
+    "@dogsbay/types": "0.2.0-beta.151",
+    "@dogsbay/ui": "0.2.0-beta.151",
     "@mermanjs/web": "0.7.0",
     "@playwright/test": "1.61.1",
     "@types/node": "^22.10.0",