@dogsbay/site-files 0.0.0-stage → 0.2.0-beta.117

package/dist/canonical.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Which URL a page of a versioned site names as its canonical, and whether
+ * it goes in the sitemap (dogsbay-ssg plans/canonical-versions.md, step 2).
+ * Both pipelines call this per page and turn the result into their own
+ * URLs: a page of an older version points at the same page in the default
+ * version, so search engines index the current docs.
+ *
+ * | Page | Canonical | Sitemap |
+ * |---|---|---|
+ * | in the default version | itself | yes |
+ * | older, and the default version has the page | that page | no |
+ * | older, and a redirect in the default version covers its path | the redirect's target | no |
+ * | older, only in its version | itself | yes |
+ * | in a `noindex: true` version | itself (robots noindex) | no |
+ * | in a `canonical: self` version | itself | yes |
+ *
+ * `sitemap: true | false` on a version overrides the last column (with
+ * `noindex`, true is refused at config load). A page's own front matter
+ * `canonicalUrl` (an absolute URL) wins over all of it; a redirect is
+ * followed only when it ends on a page of the default version or on
+ * another site.
+ */
+/** Per-version settings (`content.versions[]`). */
+export interface VersionSeo {
+    /** `self`: every page is its own canonical. Default: the canonical-to-latest rule. */
+    canonical?: "self";
+    noindex?: boolean;
+    /** Override whether the version's pages are listed in the sitemap. */
+    sitemap?: boolean;
+}
+export interface CanonicalQuery {
+    /** The page is in the default version (or the site has no version axis). */
+    isDefault: boolean;
+    /** The page's path inside its version (`guide/install`, `index`). */
+    path: string;
+    /** Its version's settings. */
+    version?: VersionSeo;
+    /** The page's front matter `canonicalUrl`, when set. Only an absolute URL counts. */
+    frontmatter?: string;
+    /** The page's own absolute URL, when known: a `canonicalUrl` equal to it is the page itself. */
+    selfUrl?: string;
+    /** Whether the default version (same language) has a live page at this path. */
+    defaultHas: (path: string) => boolean;
+    /**
+     * Where a redirect in the default version sends this path, chains
+     * collapsed: a path inside the version, a site path with a leading slash
+     * (outside the version: not followed), or a URL. Undefined when none.
+     */
+    defaultRedirect?: (path: string) => string | undefined;
+}
+export type CanonicalTarget = 
+/** The page itself. */
+{
+    kind: "self";
+}
+/** A page of the default version, by its path inside it. */
+ | {
+    kind: "default";
+    path: string;
+}
+/** An absolute URL, as written. */
+ | {
+    kind: "url";
+    url: string;
+};
+export interface CanonicalDecision {
+    target: CanonicalTarget;
+    /** List the page in the sitemap. */
+    sitemap: boolean;
+    /** Mark the page `noindex`. */
+    noindex: boolean;
+    /** Why the page's `canonicalUrl` was ignored, for the build's warnings. */
+    warning?: string;
+}
+export declare function decideCanonical(q: CanonicalQuery): CanonicalDecision;
+/** Check every version's settings, and that the default version is not `noindex` (older pages would point at noindex pages). */
+export declare function checkVersionsSeo(versions: Array<{
+    id: string;
+} & Record<string, unknown>>, defaultVersion: string | undefined): string | undefined;
+/**
+ * Check one version's settings; returns an error message or undefined.
+ * `noindex` with `sitemap: true` lists pages search engines are told to skip.
+ */
+export declare function checkVersionSeo(id: string, v: Record<string, unknown>): string | undefined;

package/dist/canonical.js

@@ -0,0 +1,82 @@
+/**
+ * Which URL a page of a versioned site names as its canonical, and whether
+ * it goes in the sitemap (dogsbay-ssg plans/canonical-versions.md, step 2).
+ * Both pipelines call this per page and turn the result into their own
+ * URLs: a page of an older version points at the same page in the default
+ * version, so search engines index the current docs.
+ *
+ * | Page | Canonical | Sitemap |
+ * |---|---|---|
+ * | in the default version | itself | yes |
+ * | older, and the default version has the page | that page | no |
+ * | older, and a redirect in the default version covers its path | the redirect's target | no |
+ * | older, only in its version | itself | yes |
+ * | in a `noindex: true` version | itself (robots noindex) | no |
+ * | in a `canonical: self` version | itself | yes |
+ *
+ * `sitemap: true | false` on a version overrides the last column (with
+ * `noindex`, true is refused at config load). A page's own front matter
+ * `canonicalUrl` (an absolute URL) wins over all of it; a redirect is
+ * followed only when it ends on a page of the default version or on
+ * another site.
+ */
+const URL_RE = /^[a-z][a-z0-9+.-]*:/i;
+const ABSOLUTE = /^https?:\/\//i;
+const same = (a, b) => a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
+export function decideCanonical(q) {
+    const v = q.version ?? {};
+    const self = (warning) => (v.noindex ? { target: { kind: "self" }, sitemap: false, noindex: true } : { target: { kind: "self" }, sitemap: v.sitemap ?? true, noindex: false, ...(warning ? { warning } : {}) });
+    const override = q.frontmatter?.trim();
+    let warning;
+    if (override) {
+        if (!ABSOLUTE.test(override)) {
+            warning = `canonicalUrl "${override}" is not an absolute URL (https://…); ignored`;
+        }
+        else if (q.selfUrl && same(override, q.selfUrl)) {
+            return self();
+        }
+        else {
+            // A page that names another page as canonical is not listed, unless its version says so.
+            return { target: { kind: "url", url: override }, sitemap: v.sitemap ?? false, noindex: !!v.noindex };
+        }
+    }
+    if (v.noindex || q.isDefault || v.canonical === "self")
+        return self(warning);
+    const moved = (target) => ({ target, sitemap: v.sitemap ?? false, noindex: false, ...(warning ? { warning } : {}) });
+    if (q.defaultHas(q.path))
+        return moved({ kind: "default", path: q.path });
+    const r = q.defaultRedirect?.(q.path);
+    // Followed only to a page of the default version, or to another site: a redirect out of the
+    // version (to an archived copy) leaves the page on itself, and in the sitemap.
+    if (r !== undefined && URL_RE.test(r))
+        return moved({ kind: "url", url: r });
+    if (r !== undefined && !r.startsWith("/") && r !== q.path && q.defaultHas(r))
+        return moved({ kind: "default", path: r });
+    return self(warning);
+}
+/** Check every version's settings, and that the default version is not `noindex` (older pages would point at noindex pages). */
+export function checkVersionsSeo(versions, defaultVersion) {
+    for (const v of versions) {
+        const bad = checkVersionSeo(v.id, v);
+        if (bad)
+            return bad;
+        if (v.id === defaultVersion && v.noindex === true)
+            return `versions: "${v.id}" is the defaultVersion and has noindex: true; older versions' pages name it as their canonical`;
+    }
+    return undefined;
+}
+/**
+ * Check one version's settings; returns an error message or undefined.
+ * `noindex` with `sitemap: true` lists pages search engines are told to skip.
+ */
+export function checkVersionSeo(id, v) {
+    if (v.canonical !== undefined && v.canonical !== "self")
+        return `versions: "${id}".canonical must be "self" (or left out for the canonical-to-latest rule); got ${JSON.stringify(v.canonical)}`;
+    if (v.noindex !== undefined && typeof v.noindex !== "boolean")
+        return `versions: "${id}".noindex must be true or false`;
+    if (v.sitemap !== undefined && typeof v.sitemap !== "boolean")
+        return `versions: "${id}".sitemap must be true or false`;
+    if (v.noindex === true && v.sitemap === true)
+        return `versions: "${id}" has noindex: true and sitemap: true; a sitemap should not list pages search engines are told to skip`;
+    return undefined;
+}

package/dist/hreflang.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `hreflang` alternates for a page that exists in several languages: every
+ * copy lists all of them (itself included) and `x-default`, the default
+ * language's copy. Built the same way by dogsbay-ssg and the Astro pipeline;
+ * each renders `<link rel="alternate" hreflang=… href=…>`.
+ */
+export interface HreflangLink {
+    hreflang: string;
+    href: string;
+}
+/**
+ * The links for one page, from its copies by language (absolute URLs).
+ * Fewer than two languages: none. Sorted by language, `x-default` last, when
+ * the default language has the page.
+ */
+export declare function buildHreflangLinks(alternates: {
+    lang: string;
+    url: string;
+}[], defaultLang?: string): HreflangLink[];

package/dist/hreflang.js

@@ -0,0 +1,18 @@
+/**
+ * The links for one page, from its copies by language (absolute URLs).
+ * Fewer than two languages: none. Sorted by language, `x-default` last, when
+ * the default language has the page.
+ */
+export function buildHreflangLinks(alternates, defaultLang) {
+    const byLang = new Map();
+    for (const a of alternates)
+        if (a.lang && a.url && !byLang.has(a.lang))
+            byLang.set(a.lang, a.url);
+    if (byLang.size < 2)
+        return [];
+    const links = [...byLang].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([hreflang, href]) => ({ hreflang, href }));
+    const def = defaultLang !== undefined ? byLang.get(defaultLang) : undefined;
+    if (def)
+        links.push({ hreflang: "x-default", href: def });
+    return links;
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @dogsbay/site-files — the files a docs site ships beside its pages, built
+ * the same way by the Astro pipeline (format-astro) and dogsbay-ssg. Pure and
+ * Worker-safe: strings in, strings out. See plans/site-files-package.md.
+ */
+export * from "./json-ld.js";
+export * from "./text.js";
+export * from "./robots.js";
+export * from "./sitemap.js";
+export * from "./llms.js";
+export * from "./redirects.js";
+export * from "./canonical.js";
+export * from "./hreflang.js";
+export * from "./translations.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @dogsbay/site-files — the files a docs site ships beside its pages, built
+ * the same way by the Astro pipeline (format-astro) and dogsbay-ssg. Pure and
+ * Worker-safe: strings in, strings out. See plans/site-files-package.md.
+ */
+export * from "./json-ld.js";
+export * from "./text.js";
+export * from "./robots.js";
+export * from "./sitemap.js";
+export * from "./llms.js";
+export * from "./redirects.js";
+export * from "./canonical.js";
+export * from "./hreflang.js";
+export * from "./translations.js";

package/dist/json-ld.d.ts

@@ -0,0 +1,105 @@
+/**
+ * JSON-LD helpers — pure functions consumed by DocsLayout and dogsbay-ssg to
+ * decide which Schema.org `@type` to emit and to normalize the
+ * `customJsonLd` prop shape.
+ *
+ * The 100daysofdocs SEO audit flagged that DocsLayout was emitting
+ * `Article` for every page regardless of intent — tutorials and
+ * how-to pages should render as `HowTo` for SERP rich results.
+ * This module owns the type selection so it's testable without
+ * spinning up an Astro renderer.
+ */
+/**
+ * Map a `meta.type` value (the open-string `pageType` prop on
+ * DocsLayout) to a Schema.org `@type`.
+ *
+ * The mapping intentionally accepts a few common spelling
+ * variants (`"how-to"` / `"howto"`, `"reference"` / `"ref"` /
+ * `"api"`) so writers don't have to learn one canonical spelling
+ * to get the right structured data. Anything else falls back to
+ * `Article`, which is Google's "general docs page" assumption.
+ */
+export declare function jsonLdTypeFor(pageType: string | undefined): string;
+/**
+ * Normalize the `customJsonLd` prop into an array. DocsLayout
+ * accepts either a single object (most common case — one extra
+ * Course / Organization block) or an array (sites that layer
+ * several blocks per page).
+ *
+ * Returns an empty array for `undefined` so the template can
+ * iterate uniformly without conditional rendering.
+ */
+export declare function normalizeCustomJsonLd(raw: Record<string, unknown> | Record<string, unknown>[] | undefined): Record<string, unknown>[];
+export interface BuildArticleJsonLdOptions {
+    /** Already-resolved Schema.org `@type` (output of jsonLdTypeFor). */
+    type: string;
+    title: string;
+    /** Site name — used as the `provider` Organization for Course. */
+    siteName: string;
+    keywords: string[];
+    description?: string;
+    image?: string;
+    url?: string;
+    /**
+     * Page headings — used to synthesize `step[]` for HowTo. Each
+     * H2 (or H3 if no H2s exist) becomes a HowToStep with a deep
+     * link to the heading id.
+     */
+    headings?: ReadonlyArray<{
+        depth: number;
+        slug: string;
+        text: string;
+    }>;
+}
+/**
+ * Build the JSON-LD payload for the page's primary structured-data
+ * block, shaped per `@type`. The earlier implementation emitted
+ * Article-shaped fields (`headline`) regardless of @type, which
+ * meant HowTo / Course pages failed Google's Rich Results
+ * requirements (HowTo needs `name` + `step`, Course needs `name` +
+ * `description` + `provider`). See
+ * `packages/site-check/src/rules/seo/json-ld-required-fields.ts`
+ * for the validator that catches this.
+ *
+ * Schema.org's `name` is a Thing-level field accepted by every
+ * @type, so we always emit it. `headline` is added on top for
+ * Article-family types (Article, TechArticle) because Google's
+ * Rich Results validator specifically requires it there. HowTo
+ * gets a synthesized `step[]` from the page's H2 headings (each
+ * H2 = one procedure step); Course gets a `provider` Organization
+ * built from `siteName`.
+ */
+export declare function buildArticleJsonLd(opts: BuildArticleJsonLdOptions): Record<string, unknown>;
+/**
+ * Identity structured data for a page that is not an article — a
+ * homepage, a landing page, a section index.
+ *
+ * Exists because the article block is gated on `ogType === "article"`,
+ * so those pages emitted NO structured data at all. An external agent
+ * audit reported "No JSON-LD structured data found on homepage", which
+ * was accurate: the one page most likely to be an agent's entry point
+ * was the one describing itself the least.
+ *
+ * `WebSite` rather than `Organization` or `SoftwareApplication` on
+ * purpose. Those are claims about what the site's OWNER is, and
+ * guessing wrong is worse than saying less — a docs site for a product
+ * is not itself the product. Owners wanting a stronger identity type
+ * add it through `customJsonLd`, which layers on top of this.
+ */
+export declare function buildWebSiteJsonLd(opts: {
+    siteName: string;
+    title: string;
+    description?: string;
+    url?: string;
+}): Record<string, unknown>;
+/**
+ * JSON-LD `BreadcrumbList` for a page: the nav trail from the top level down
+ * to the page, with absolute URLs. An entry without a URL (a section with no
+ * page of its own) is left out, since search engines require `item` on every
+ * entry but the last; positions count the entries kept. Fewer than two
+ * entries say nothing a breadcrumb adds: undefined.
+ */
+export declare function buildBreadcrumbJsonLd(items: {
+    name: string;
+    url?: string;
+}[]): Record<string, unknown> | undefined;

package/dist/json-ld.js

@@ -0,0 +1,161 @@
+/**
+ * JSON-LD helpers — pure functions consumed by DocsLayout and dogsbay-ssg to
+ * decide which Schema.org `@type` to emit and to normalize the
+ * `customJsonLd` prop shape.
+ *
+ * The 100daysofdocs SEO audit flagged that DocsLayout was emitting
+ * `Article` for every page regardless of intent — tutorials and
+ * how-to pages should render as `HowTo` for SERP rich results.
+ * This module owns the type selection so it's testable without
+ * spinning up an Astro renderer.
+ */
+/**
+ * Map a `meta.type` value (the open-string `pageType` prop on
+ * DocsLayout) to a Schema.org `@type`.
+ *
+ * The mapping intentionally accepts a few common spelling
+ * variants (`"how-to"` / `"howto"`, `"reference"` / `"ref"` /
+ * `"api"`) so writers don't have to learn one canonical spelling
+ * to get the right structured data. Anything else falls back to
+ * `Article`, which is Google's "general docs page" assumption.
+ */
+export function jsonLdTypeFor(pageType) {
+    switch (pageType) {
+        case "tutorial":
+        case "how-to":
+        case "howto":
+            return "HowTo";
+        case "reference":
+        case "ref":
+        case "api":
+            return "TechArticle";
+        case "course":
+            return "Course";
+        default:
+            return "Article";
+    }
+}
+/**
+ * Normalize the `customJsonLd` prop into an array. DocsLayout
+ * accepts either a single object (most common case — one extra
+ * Course / Organization block) or an array (sites that layer
+ * several blocks per page).
+ *
+ * Returns an empty array for `undefined` so the template can
+ * iterate uniformly without conditional rendering.
+ */
+export function normalizeCustomJsonLd(raw) {
+    if (!raw)
+        return [];
+    if (Array.isArray(raw))
+        return raw;
+    return [raw];
+}
+/**
+ * Build the JSON-LD payload for the page's primary structured-data
+ * block, shaped per `@type`. The earlier implementation emitted
+ * Article-shaped fields (`headline`) regardless of @type, which
+ * meant HowTo / Course pages failed Google's Rich Results
+ * requirements (HowTo needs `name` + `step`, Course needs `name` +
+ * `description` + `provider`). See
+ * `packages/site-check/src/rules/seo/json-ld-required-fields.ts`
+ * for the validator that catches this.
+ *
+ * Schema.org's `name` is a Thing-level field accepted by every
+ * @type, so we always emit it. `headline` is added on top for
+ * Article-family types (Article, TechArticle) because Google's
+ * Rich Results validator specifically requires it there. HowTo
+ * gets a synthesized `step[]` from the page's H2 headings (each
+ * H2 = one procedure step); Course gets a `provider` Organization
+ * built from `siteName`.
+ */
+export function buildArticleJsonLd(opts) {
+    const { type, title, siteName, keywords, description, image, url, headings } = opts;
+    const block = {
+        "@context": "https://schema.org",
+        "@type": type,
+        name: title,
+    };
+    // Only when there are any. An empty `keywords: ""` asserts the page
+    // has no topics, which is a different claim from staying silent.
+    if (keywords.length > 0)
+        block.keywords = keywords.join(", ");
+    if (type === "Article" || type === "TechArticle") {
+        block.headline = title;
+    }
+    if (description)
+        block.description = description;
+    if (image)
+        block.image = image;
+    if (url)
+        block.url = url;
+    if (type === "HowTo") {
+        let stepHeadings = (headings ?? []).filter((h) => h.depth === 2);
+        if (stepHeadings.length === 0) {
+            stepHeadings = (headings ?? []).filter((h) => h.depth === 3);
+        }
+        block.step = stepHeadings.map((h) => ({
+            "@type": "HowToStep",
+            name: h.text,
+            url: url ? `${url}#${h.slug}` : `#${h.slug}`,
+        }));
+    }
+    if (type === "Course") {
+        block.provider = { "@type": "Organization", name: siteName };
+        if (!block.description)
+            block.description = title;
+    }
+    return block;
+}
+/**
+ * Identity structured data for a page that is not an article — a
+ * homepage, a landing page, a section index.
+ *
+ * Exists because the article block is gated on `ogType === "article"`,
+ * so those pages emitted NO structured data at all. An external agent
+ * audit reported "No JSON-LD structured data found on homepage", which
+ * was accurate: the one page most likely to be an agent's entry point
+ * was the one describing itself the least.
+ *
+ * `WebSite` rather than `Organization` or `SoftwareApplication` on
+ * purpose. Those are claims about what the site's OWNER is, and
+ * guessing wrong is worse than saying less — a docs site for a product
+ * is not itself the product. Owners wanting a stronger identity type
+ * add it through `customJsonLd`, which layers on top of this.
+ */
+export function buildWebSiteJsonLd(opts) {
+    const block = {
+        "@context": "https://schema.org",
+        "@type": "WebSite",
+        name: opts.siteName,
+    };
+    if (opts.title && opts.title !== opts.siteName)
+        block.headline = opts.title;
+    if (opts.description)
+        block.description = opts.description;
+    if (opts.url)
+        block.url = opts.url;
+    return block;
+}
+/**
+ * JSON-LD `BreadcrumbList` for a page: the nav trail from the top level down
+ * to the page, with absolute URLs. An entry without a URL (a section with no
+ * page of its own) is left out, since search engines require `item` on every
+ * entry but the last; positions count the entries kept. Fewer than two
+ * entries say nothing a breadcrumb adds: undefined.
+ */
+export function buildBreadcrumbJsonLd(items) {
+    const kept = items.filter((it, i) => it.url || i === items.length - 1);
+    if (kept.length < 2)
+        return undefined;
+    return {
+        "@context": "https://schema.org",
+        "@type": "BreadcrumbList",
+        itemListElement: kept.map((it, i) => ({
+            "@type": "ListItem",
+            position: i + 1,
+            name: it.name,
+            ...(it.url ? { item: it.url } : {}),
+        })),
+    };
+}

package/dist/llms.d.ts

@@ -0,0 +1,72 @@
+/**
+ * llms.txt, the per-section llms.txt files and llms-full.txt (llmstxt.org).
+ *
+ * The pipelines pass small records, not their page models: each page's key
+ * (its slug), title and description (already cut with `truncate`), and the
+ * nav as keys. They also pass `url(key)`, the link an entry gets: Astro's
+ * `/docs/x.md` (absolute from the origin with `site.url`), dogsbay-ssg's
+ * `x.md` relative to the file or absolute. Page bodies are never held here:
+ * llms-full.txt reads each through `load(key)` and streams.
+ */
+export interface LlmsSite {
+    name: string;
+    description?: string;
+    /** "When to use this": what the site is good for. Omitted when unset. */
+    whenToUse?: string;
+    /** Other sites on this host, linked at the end of llms.txt (`site.aggregates`). */
+    aggregates?: LlmsAggregate[];
+}
+export interface LlmsAggregate {
+    name: string;
+    description?: string;
+    url?: string;
+    llmsTxt?: string;
+}
+export interface LlmsPage {
+    title: string;
+    /** Shown after the link, as given (cut it with `truncate`). */
+    description?: string;
+}
+export interface LlmsNav {
+    label: string;
+    /** The page's key; absent for a label-only group. */
+    key?: string;
+    /** Appended to the entry's URL (`#section`). */
+    fragment?: string;
+    children: LlmsNav[];
+}
+export interface LlmsOptions {
+    /** The URL of a page's entry. */
+    url(key: string): string;
+    /** A nav entry whose key has no page: `"skip"` it (dogsbay-ssg) or `"link"` it by its label (Astro). Default `"skip"`. */
+    missing?: "skip" | "link";
+    /** Escape `[` and `]` in labels, which would end the link text early (dogsbay-ssg). Default false. */
+    escapeLabels?: boolean;
+    /** Heading for top-level pages outside a group. Default "Documentation". */
+    topLevelLabel?: string;
+    /** Heading for pages not in the nav, or false to leave them out. Default "Other pages". */
+    otherPagesLabel?: string | false;
+    /** Heading for `site.aggregates`. Default "Other sites". */
+    aggregatesLabel?: string;
+}
+type Pages = ReadonlyMap<string, LlmsPage>;
+/**
+ * The site's llms.txt: the title, description and "When to use this", then
+ * top-level pages under "Documentation", one section per top-level nav group,
+ * pages outside the nav under "Other pages" (sorted by key), and other sites.
+ */
+export declare function buildLlmsTxt(site: LlmsSite, nav: LlmsNav[], pages: Pages, o: LlmsOptions): string;
+/** One top-level nav group's own llms.txt. */
+export declare function buildSectionLlmsTxt(site: Pick<LlmsSite, "name">, group: LlmsNav, pages: Pages, o: LlmsOptions): string;
+/** Page keys in nav order, then pages outside the nav sorted by key: the llms-full.txt order. */
+export declare function llmsFullOrder(nav: LlmsNav[], pages: Pages): string[];
+/**
+ * llms-full.txt, one chunk per page so the file is never held whole: the
+ * header, then for each page `# Title`, `URL:` and its Markdown (from
+ * `load`), separated by `---`. Joined, the chunks equal `buildLlmsFullTxt`.
+ * `site.whenToUse` is written when given (neither pipeline passes it).
+ */
+export declare function llmsFullChunks(site: LlmsSite, order: string[], pages: Pages, url: (key: string) => string, load: (key: string) => string | Promise<string>): AsyncGenerator<string>;
+/** llms-full.txt as one string, for a caller that has every page at hand. */
+export declare function buildLlmsFullTxt(site: LlmsSite, order: string[], pages: Pages, url: (key: string) => string, load: (key: string) => string): string;
+export {};