@dogsbay/format-astro 0.2.0-beta.13 → 0.2.0-beta.131

package/dist/sitemap.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Sitemap builders — sitemaps.org 0.9 format.
+ *
+ * Pure functions: take pages + siteUrl + basePath, return strings.
+ * Output goes to `public/<basePath>/sitemap-{index,0}.xml` so
+ * multi-mount deploys don't collide at the host root (the same
+ * per-mount layout we use for `llms.txt`).
+ *
+ * `@astrojs/sitemap` was the historical generator, but it
+ * hard-codes output to `dist/` root with no scoping option, which
+ * breaks the `acme.com/docs/` + `acme.com/api/` shared-host case.
+ * This module replaces it.
+ */
+import type { ExportPage } from "@dogsbay/types";
+export { assertLeafSitemap } from "@dogsbay/site-files";
+export interface BuildSitemapOptions {
+    /**
+     * Required. Origin of the deployed site (`https://acme.example`)
+     * — used to make `<loc>` entries absolute. Path component is
+     * ignored; pass the origin only.
+     */
+    siteUrl: string;
+    /**
+     * Mount prefix (`/docs`, `/api`, `""` for host root). Page slugs
+     * are joined under this so `<loc>` matches the actual URL.
+     */
+    basePath: string;
+    /**
+     * Site-level noindex lockdown. When true, the sitemap emits its
+     * `<urlset>` wrapper with zero entries — there's no point
+     * advertising URLs we're also telling crawlers to skip via
+     * meta-robots. Keeps the file present so per-mount discovery /
+     * llms.txt references don't 404.
+     */
+    siteNoindex?: boolean;
+    /**
+     * Leaf sitemap URLs from other sites on this host to list in the
+     * index alongside our own. See `AggregateSource` in `@dogsbay/cli`.
+     *
+     * Must be `<urlset>` documents, not other indexes — the sitemaps.org
+     * protocol forbids nesting index files. `buildSitemapIndex` cannot
+     * fetch them to check, so the caller validates; see
+     * `assertLeafSitemap`.
+     */
+    extraSitemaps?: string[];
+    /** How many `sitemap-N.xml` files this site wrote (`buildSitemapFiles`). Default 1. */
+    sitemapCount?: number;
+}
+/**
+ * Build `<basePath>/sitemap-0.xml` — one `<url>` per non-excluded
+ * page.
+ *
+ * Filters:
+ *   - frontmatter.noindex === true   (matches @astrojs/sitemap)
+ *   - frontmatter.draft === true     (drafts shouldn't be indexed)
+ *   - page.redirect set              (redirect pages aren't real URLs)
+ *
+ * `<lastmod>` is read from frontmatter.lastUpdated, then
+ * frontmatter.lastmod. Omitted (rather than fabricated) when
+ * neither is present — fabricated mtimes churn the sitemap on
+ * every build and waste crawler budget.
+ */
+export declare function buildSitemap(pages: ExportPage[], options: BuildSitemapOptions): string;
+/**
+ * The sitemap files for the site: `sitemap-0.xml`, and more past the
+ * 50,000 URLs one file may hold. Pass their count to
+ * `buildSitemapIndex` as `sitemapCount`.
+ */
+export declare function buildSitemapFiles(pages: ExportPage[], options: BuildSitemapOptions): [string, string][];
+/**
+ * Build `<basePath>/sitemap-index.xml`: this site's sitemap files, then
+ * the aggregated leaf sitemaps of other sites on the host.
+ */
+export declare function buildSitemapIndex(options: BuildSitemapOptions): string;
+/**
+ * Compose a page's URL path under the mount prefix. The slug
+ * "index" / "" maps to the mount root. A nested `<section>/index`
+ * slug maps to `<section>/` (with trailing slash) — same shape
+ * Astro serves: `dist/foo/index.html` is reached at `/foo/`, not
+ * `/foo/index`. Without this normalisation the sitemap emitted
+ * `/foo/index` while the actual URL was `/foo/`, and the
+ * `seo/sitemap-complete` audit then flagged every section index
+ * as missing.
+ *
+ * ALWAYS ends in a trailing slash. It used to omit the slash for
+ * ordinary pages while adding it for `/index` ones, so a sitemap
+ * disagreed with itself AND with the canonical every layout emits.
+ * Measured on the live blog before the fix:
+ *
+ *   sitemap    /blog/migrating-asciidoc-to-markdown   -> 307
+ *   canonical  /blog/migrating-asciidoc-to-markdown/  -> 200
+ *
+ * Every URL in every generated sitemap redirected. Google follows the
+ * redirect and indexes the canonical, so nothing was broken for
+ * readers — it burns crawl budget and reports "Page with redirect"
+ * against every URL in Search Console.
+ *
+ * The slash is correct because Astro's default `build.format` is
+ * `"directory"`: a page is emitted as `slug/index.html` and served at
+ * `slug/`. Neither the scaffold nor any generated config sets
+ * `build.format` or `trailingSlash`, so the default holds everywhere.
+ * If `build.format: "file"` is ever supported this must become
+ * conditional; the tests pin the coupling so it cannot pass silently.
+ */
+export declare function pageHref(slug: string | undefined, prefix: string): string;
+export declare function normalizePrefix(basePath: string | undefined): string;
+export declare function originOf(siteUrl: string): string;

package/dist/sitemap.js

@@ -0,0 +1,126 @@
+import { buildSitemapIndex as buildSitemapIndexXml, buildSitemaps, buildUrlset, lastmodOf, } from "@dogsbay/site-files";
+export { assertLeafSitemap } from "@dogsbay/site-files";
+/**
+ * Build `<basePath>/sitemap-0.xml` — one `<url>` per non-excluded
+ * page.
+ *
+ * Filters:
+ *   - frontmatter.noindex === true   (matches @astrojs/sitemap)
+ *   - frontmatter.draft === true     (drafts shouldn't be indexed)
+ *   - page.redirect set              (redirect pages aren't real URLs)
+ *
+ * `<lastmod>` is read from frontmatter.lastUpdated, then
+ * frontmatter.lastmod. Omitted (rather than fabricated) when
+ * neither is present — fabricated mtimes churn the sitemap on
+ * every build and waste crawler budget.
+ */
+export function buildSitemap(pages, options) {
+    return buildUrlset(sitemapEntries(pages, options));
+}
+/**
+ * The sitemap files for the site: `sitemap-0.xml`, and more past the
+ * 50,000 URLs one file may hold. Pass their count to
+ * `buildSitemapIndex` as `sitemapCount`.
+ */
+export function buildSitemapFiles(pages, options) {
+    return buildSitemaps(sitemapEntries(pages, options));
+}
+function sitemapEntries(pages, options) {
+    // Site-level noindex: the file stays (the index and robots.txt point
+    // at it), with no entries.
+    if (options.siteNoindex)
+        return [];
+    const origin = stripTrailingSlash(originOf(options.siteUrl));
+    const prefix = normalizePrefix(options.basePath);
+    const entries = [];
+    for (const page of pages) {
+        if (isExcluded(page))
+            continue;
+        const lastmod = pageLastmod(page);
+        entries.push({ loc: `${origin}${pageHref(page.slug, prefix)}`, ...(lastmod ? { lastmod } : {}) });
+    }
+    return entries;
+}
+/**
+ * Build `<basePath>/sitemap-index.xml`: this site's sitemap files, then
+ * the aggregated leaf sitemaps of other sites on the host.
+ */
+export function buildSitemapIndex(options) {
+    const origin = stripTrailingSlash(originOf(options.siteUrl));
+    const prefix = normalizePrefix(options.basePath);
+    const ours = Array.from({ length: Math.max(1, options.sitemapCount ?? 1) }, (_, i) => `${origin}${prefix}/sitemap-${i}.xml`);
+    return buildSitemapIndexXml(ours, options.extraSitemaps ?? []);
+}
+// ── Internals ────────────────────────────────────────────────────
+function isExcluded(page) {
+    const fm = page.frontmatter ?? {};
+    if (fm["noindex"] === true)
+        return true;
+    if (fm["draft"] === true)
+        return true;
+    if (page.redirect && typeof page.redirect === "string")
+        return true;
+    return false;
+}
+function pageLastmod(page) {
+    // Modification fields first, then creation: a post that was never
+    // edited has only a creation date (blog posts carry `created`), and
+    // no <lastmod> at all tells a crawler less than the publish date.
+    return lastmodOf(page.frontmatter ?? {}) ?? null;
+}
+/**
+ * Compose a page's URL path under the mount prefix. The slug
+ * "index" / "" maps to the mount root. A nested `<section>/index`
+ * slug maps to `<section>/` (with trailing slash) — same shape
+ * Astro serves: `dist/foo/index.html` is reached at `/foo/`, not
+ * `/foo/index`. Without this normalisation the sitemap emitted
+ * `/foo/index` while the actual URL was `/foo/`, and the
+ * `seo/sitemap-complete` audit then flagged every section index
+ * as missing.
+ *
+ * ALWAYS ends in a trailing slash. It used to omit the slash for
+ * ordinary pages while adding it for `/index` ones, so a sitemap
+ * disagreed with itself AND with the canonical every layout emits.
+ * Measured on the live blog before the fix:
+ *
+ *   sitemap    /blog/migrating-asciidoc-to-markdown   -> 307
+ *   canonical  /blog/migrating-asciidoc-to-markdown/  -> 200
+ *
+ * Every URL in every generated sitemap redirected. Google follows the
+ * redirect and indexes the canonical, so nothing was broken for
+ * readers — it burns crawl budget and reports "Page with redirect"
+ * against every URL in Search Console.
+ *
+ * The slash is correct because Astro's default `build.format` is
+ * `"directory"`: a page is emitted as `slug/index.html` and served at
+ * `slug/`. Neither the scaffold nor any generated config sets
+ * `build.format` or `trailingSlash`, so the default holds everywhere.
+ * If `build.format: "file"` is ever supported this must become
+ * conditional; the tests pin the coupling so it cannot pass silently.
+ */
+export function pageHref(slug, prefix) {
+    let clean = (slug ?? "").replace(/^\/+|\/+$/g, "");
+    if (!clean || clean === "index")
+        return prefix ? `${prefix}/` : "/";
+    if (clean.endsWith("/index"))
+        clean = clean.slice(0, -"/index".length);
+    return `${prefix}/${clean}/`;
+}
+export function normalizePrefix(basePath) {
+    if (!basePath)
+        return "";
+    const trimmed = basePath.replace(/\/+$/, "");
+    return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+export function originOf(siteUrl) {
+    try {
+        const u = new URL(siteUrl);
+        return `${u.protocol}//${u.host}`;
+    }
+    catch {
+        return siteUrl;
+    }
+}
+function stripTrailingSlash(s) {
+    return s.replace(/\/+$/, "");
+}

package/dist/taxonomy.d.ts

@@ -1,4 +1,4 @@
-import type { ExportPage } from "@dogsbay/types";
+import type { ExportPage, TreeNode } from "@dogsbay/types";
 /** Per-taxonomy emit config — resolved (defaults filled). */
 export interface TaxonomyEmitConfig {
     /** Path prefix for emitted index/term pages, e.g. "/tags". */
@@ -68,6 +68,29 @@ export interface TaxonomyData {
  * name to the right `PageMeta` slot.
  */
 export declare function getPageTerms(page: ExportPage, taxonomy: string): string[];
+/**
+ * Derive a short description for one page, used to populate
+ * `TaxonomyPageRef.description` on the term data file. Card layouts
+ * in `<TaxonomyTerm>` consume this — title-only cards read as
+ * empty, so a working fallback matters.
+ *
+ * Resolution order:
+ * 1. `frontmatter.description` (string) when set — explicit
+ *    author-supplied summary always wins.
+ * 2. First paragraph of `page.tree`, plain-text-extracted and
+ *    truncated to {@link DESCRIPTION_LIMIT}. Skips headings so the
+ *    page title doesn't echo as the description.
+ * 3. `undefined` — caller omits the field, card renders title-only.
+ */
+export declare function derivePageDescription(page: ExportPage): string | undefined;
+/**
+ * Pull plain text from a TreeNode. Tolerates both shapes used by
+ * importers:
+ * - `node.inline` array (dogsbay-md parser).
+ * - `node.children[{type: "prose", inline: ...}]` (Starlight).
+ * - `node.html` prerendered HTML (fallback — strips tags).
+ */
+export declare function textOfNode(node: TreeNode): string;
 /**
  * Build the taxonomy data structure for one taxonomy across all pages.
  * Pure function. Test-friendly. Sorts terms alphabetically by full
@@ -75,7 +98,25 @@ export declare function getPageTerms(page: ExportPage, taxonomy: string): string
  */
 export declare function buildTaxonomyData(pages: ExportPage[], taxonomy: string, config: TaxonomyEmitConfig, options?: {
     section?: string;
+    /**
+     * Dogsbay basePath — drives FILESYSTEM layout via `data.basePath`
+     * (route files live at `src/pages/<basePath>/<indexPath>/...`).
+     */
     basePath?: string;
+    /**
+     * URL prefix that all hrefs inside `data` (page URLs, indexPath
+     * baked for chip composition, term hrefs) carry. Should be the
+     * combined prefix (urlBase from site.url's path + basePath) so
+     * URLs resolve correctly on subpath-mounted deploys. When
+     * omitted, defaults to `basePath` for back-compat (single-site
+     * deploys without a urlBase). Without this split, callers that
+     * pass `combined` as the only basePath blow up the filesystem
+     * layout into `src/pages/<urlBase>/<basePath>/<indexPath>/...`,
+     * which then double-prefixes once Astro's `base` config kicks
+     * in at request time. Same family as the section-llms.txt fix
+     * (commit 47db909).
+     */
+    urlPrefix?: string;
 }): TaxonomyData;
 /**
  * Emit route files + data file for one taxonomy.
@@ -95,6 +136,11 @@ export declare function emitTaxonomyForName(data: TaxonomyData, outputDir: strin
  */
 export declare function emitTaxonomyRoutes(pages: ExportPage[], outputDir: string, taxonomies: Record<string, TaxonomyEmitConfig>, options?: {
     section?: string;
+    /** Dogsbay basePath — filesystem layout under src/pages/. */
     basePath?: string;
+    /**
+     * Combined URL prefix (urlBase + basePath) baked into URLs in
+     * emitted data. Defaults to `basePath` when omitted.
+     */
+    urlPrefix?: string;
 }): string[];
-//# sourceMappingURL=taxonomy.d.ts.map

package/dist/taxonomy.js

@@ -25,7 +25,9 @@
  *
  * See plans/metadata-and-taxonomies.md.
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+// Unchanged files are not rewritten, so `site dev` reloads only what changed
+import { writeFileSync } from "./write-if-changed.js";
 import { dirname, join } from "node:path";
 import { joinBaseUrl, normalizeBasePath, withBasePath, basePathSegments } from "./base-path.js";
 /** Cap on description length emitted into taxonomy data. */
@@ -75,7 +77,7 @@ function pageUrl(slug, section, basePath) {
  *    page title doesn't echo as the description.
  * 3. `undefined` — caller omits the field, card renders title-only.
  */
-function derivePageDescription(page) {
+export function derivePageDescription(page) {
     const fm = page.frontmatter;
     const fmDesc = fm?.description;
     if (typeof fmDesc === "string" && fmDesc.trim().length > 0) {
@@ -106,7 +108,7 @@ function findFirstParagraph(nodes) {
  * - `node.children[{type: "prose", inline: ...}]` (Starlight).
  * - `node.html` prerendered HTML (fallback — strips tags).
  */
-function textOfNode(node) {
+export function textOfNode(node) {
     const parts = [];
     if (Array.isArray(node.inline)) {
         parts.push(textOfInline(node.inline));
@@ -173,6 +175,9 @@ export function buildTaxonomyData(pages, taxonomy, config, options = {}) {
     // Map a path key (joined by "/") → term entry under construction
     const termMap = new Map();
     const basePath = normalizeBasePath(options.basePath);
+    const urlPrefix = options.urlPrefix !== undefined
+        ? normalizeBasePath(options.urlPrefix)
+        : basePath;
     for (const page of pages) {
         const terms = getPageTerms(page, taxonomy);
         if (terms.length === 0)
@@ -181,7 +186,10 @@ export function buildTaxonomyData(pages, taxonomy, config, options = {}) {
         const ref = {
             slug: page.slug,
             title: page.title,
-            url: pageUrl(page.slug, options.section, basePath),
+            // URLs go through urlPrefix (combined) so chip links resolve
+            // under subpath-mounted deploys. Filesystem layout uses
+            // basePath alone — split via `data.basePath` below.
+            url: pageUrl(page.slug, options.section, urlPrefix),
             ...(description ? { description } : {}),
         };
         // Track which path keys this page has already contributed to so a
@@ -219,15 +227,15 @@ export function buildTaxonomyData(pages, taxonomy, config, options = {}) {
     allTerms.sort((a, b) => a.fullPath.join("/").localeCompare(b.fullPath.join("/")));
     // `data.indexPath` is the URL-bearing form — components compose
     // hrefs as `${data.indexPath}/${term}/`, so it has to include
-    // basePath here. Without this, taxonomy chip strips, breadcrumbs,
-    // sub-tag pills, and the type/status badge hrefs all 404 on any
-    // site with `site.basePath` set. The route-file location (computed
-    // separately in `emitTaxonomyForName` from `config.indexPath`)
-    // still uses the raw form so Astro's `base` config handles the
-    // file-system → URL mapping.
+    // the combined URL prefix here (urlBase + basePath). Without
+    // urlBase, chip strips / breadcrumbs / sub-tag pills 404 on
+    // subpath-mounted deploys; without basePath, they 404 on sites
+    // with `site.basePath` set. `data.basePath` carries the
+    // basePath-only form for the file-system layout step in
+    // `emitTaxonomyForName`.
     return {
         name: taxonomy,
-        indexPath: withBasePath(basePath, config.indexPath),
+        indexPath: withBasePath(urlPrefix, config.indexPath),
         basePath,
         hierarchical: config.hierarchical,
         terms: allTerms,
@@ -356,6 +364,21 @@ export function emitTaxonomyRoutes(pages, outputDir, taxonomies, options = {}) {
 // Writers who want a custom shell (different layout, no sidebar) can
 // drop their own `src/pages<indexPath>/{index,[...path]}.astro` —
 // `emitTaxonomyForName` skips emission when those files exist.
+/**
+ * The prefix the host actually serves this site under, recovered from
+ * the urlPrefix-composed `indexPath`.
+ *
+ * DocsLayout builds the llms.txt link, the sitemap fallback and the
+ * switcher hrefs from its `basePath` prop. Taxonomy routes never passed
+ * one, so on a sub-path-mounted site those came out as `/llms.txt` and
+ * `/sitemap-index.xml` — outside the mount, 404 for every one of them.
+ */
+function servingPrefix(data, config) {
+    const suffix = normalizeBasePath(config.indexPath);
+    return suffix && data.indexPath.endsWith(suffix)
+        ? data.indexPath.slice(0, data.indexPath.length - suffix.length)
+        : "";
+}
 function buildIndexAstro(data, config, routeSegments) {
     const dataImport = dataImportPath(routeSegments, data);
     const title = displayName(data.name);
@@ -372,11 +395,13 @@ import data from "${dataImport}";
 import navData from "@/data/nav.json";
 import siteConfigData from "@/data/site.json";
 const siteConfig = siteConfigData as SiteConfig;
+const favicon = (siteConfigData as { favicon?: string }).favicon;
 const title = ${JSON.stringify(title)};
 ${displayConfig}
 ---
 <DocsLayout
   siteName={siteConfig.siteName}
+  siteTagline={siteConfig.tagline}
   title={title}
   nav={navData as any[]}
   headings={[]}
@@ -386,12 +411,16 @@ ${displayConfig}
   twitterHandle={siteConfig.twitterHandle || undefined}
   themeColor={siteConfig.themeColor || undefined}
   repoUrl={siteConfig.repoUrl || undefined}
+  poweredBy={siteConfig.poweredBy !== false}
   plausibleDomain={siteConfig.plausible?.domain}
   plausibleScriptUrl={siteConfig.plausible?.scriptUrl}
   tagPrefixes={siteConfig.tagPrefixes}
   tagLabels={siteConfig.tagLabels}
+  tagAutoColor={siteConfig.tagAutoColor}
   taxonomyIndexPaths={siteConfig.taxonomyIndexPaths}
   taxonomyDisplay={siteConfig.taxonomyDisplay}
+  favicon={favicon}
+  basePath={${JSON.stringify(servingPrefix(data, config))}}
   noindex={true}
   excludeFromSearch={true}
 >
@@ -415,6 +444,7 @@ import data from "${dataImport}";
 import navData from "@/data/nav.json";
 import siteConfigData from "@/data/site.json";
 const siteConfig = siteConfigData as SiteConfig;
+const favicon = (siteConfigData as { favicon?: string }).favicon;
 
 export async function getStaticPaths() {
   return data.terms.map((term) => ({
@@ -429,6 +459,7 @@ const title = \`\${term.label} — ${escapeTemplate(taxonomyDisplay)}\`;
 ---
 <DocsLayout
   siteName={siteConfig.siteName}
+  siteTagline={siteConfig.tagline}
   title={title}
   nav={navData as any[]}
   headings={[]}
@@ -438,12 +469,16 @@ const title = \`\${term.label} — ${escapeTemplate(taxonomyDisplay)}\`;
   twitterHandle={siteConfig.twitterHandle || undefined}
   themeColor={siteConfig.themeColor || undefined}
   repoUrl={siteConfig.repoUrl || undefined}
+  poweredBy={siteConfig.poweredBy !== false}
   plausibleDomain={siteConfig.plausible?.domain}
   plausibleScriptUrl={siteConfig.plausible?.scriptUrl}
   tagPrefixes={siteConfig.tagPrefixes}
   tagLabels={siteConfig.tagLabels}
+  tagAutoColor={siteConfig.tagAutoColor}
   taxonomyIndexPaths={siteConfig.taxonomyIndexPaths}
   taxonomyDisplay={siteConfig.taxonomyDisplay}
+  favicon={favicon}
+  basePath={${JSON.stringify(servingPrefix(data, config))}}
   noindex={true}
   excludeFromSearch={true}
 >
@@ -499,4 +534,3 @@ function escapeHtml(s) {
         .replace(/>/g, "&gt;")
         .replace(/"/g, "&quot;");
 }
-//# sourceMappingURL=taxonomy.js.map

package/dist/theme-css.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Build the `@source inline("...")` directive that pins the
+ * grid-tone palette into the generated stylesheet.
+ *
+ * Why we need it: tone classes like `bg-primary/10` only appear in
+ * `.astro` pages emitted by Dogsbay's grid-item serializer. When
+ * Tailwind's content scanner doesn't pick them up — because the
+ * page lives outside the default scan globs, or because a class
+ * is composed at the boundary of an interpolation — they get
+ * purged. Result observed in dogsbay-docs-markdown audit: half
+ * the grid demo cells render with no background. Pinning forces
+ * generation regardless of scanner reach.
+ *
+ * Single source of truth: derived from TONE_CLASSES so any new
+ * tone added to the palette is automatically safelisted.
+ */
+export declare function buildToneSafelist(): string;
+/**
+ * The same pin for the variant, tone and theme-scope tables
+ * (plans/dita-variants-themes.md). A line of its own, marked ASTRO-ONLY:
+ * render-html copies this stylesheet, and a renderer that compiles from the
+ * page's own classes (render-html, dogsbay-ssg) needs no safelist — there it
+ * put every variant's classes on every page (scripts/sources.mjs drops it).
+ */
+export declare function buildVariantSafelist(): string;
+export declare function generateGlobalCss(): string;
+/** The theme presets by name. A name not here falls back to "default", as writeThemeFile always did. */
+export declare const THEMES: Record<string, {
+    light: string;
+    dark: string;
+}>;
+/** A site's src/styles/theme.css for a preset: the Tailwind theme mapping plus the preset's tokens. */
+export declare function themeCss(themeName?: string): string;