svelte-docsmith 0.9.0 → 0.11.0

package/bin/svelte-docsmith.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Process boundary only. The command itself lives in
+// `src/lib/buildtime/cli/`, where it is typechecked and unit-tested; this file
+// exists so `svelte-docsmith` is a runnable bin entry.
+import { run, CliError } from '../dist/buildtime/cli/run.js';
+
+try {
+	run(process.argv.slice(2));
+} catch (error) {
+	if (error instanceof CliError) {
+		// A mistake the user can fix. The message says how; a stack would not help.
+		console.error(`svelte-docsmith: ${error.message}`);
+		process.exit(1);
+	}
+	throw error;
+}

package/dist/buildtime/archive.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The pure text transforms behind `svelte-docsmith archive-version`. Archiving
+ * copies the docs root into a frozen version folder, and a verbatim copy gets
+ * two things wrong: its links keep resolving to the current docs, and every page
+ * looks like it changed on the day the archive was made. These fix both.
+ *
+ * Kept here rather than in `bin/` so they are typechecked and unit-tested; the
+ * CLI is a thin wrapper over them. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
+ */
+/** Route files at the docs root that an archive nested inside it already inherits. */
+export declare function isInheritedRouteFile(name: string): boolean;
+/**
+ * Point a page's docs links at the archive it is being copied into. An absolute
+ * link like `](/docs/theming)` resolves to the *current* docs forever, so
+ * without this an archive silently walks readers into newer content.
+ *
+ * Links already targeting a version folder are left alone, as are links inside
+ * fenced code, which are sample code rather than navigation.
+ */
+export declare function rewriteDocsLinks(text: string, options: {
+    docsBase: string;
+    versionId: string;
+    archivedIds?: Iterable<string>;
+}): string;
+/**
+ * Write a page's real last-updated date into its frontmatter. The collector
+ * prefers frontmatter over the git date, so an archive keeps the date each page
+ * was actually accurate on instead of the day the archive was created. Leaves an
+ * existing `lastUpdated` and any page without frontmatter alone.
+ */
+export declare function freezeLastUpdated(text: string, date: string | undefined): string;

package/dist/buildtime/archive.js

@@ -0,0 +1,50 @@
+/**
+ * The pure text transforms behind `svelte-docsmith archive-version`. Archiving
+ * copies the docs root into a frozen version folder, and a verbatim copy gets
+ * two things wrong: its links keep resolving to the current docs, and every page
+ * looks like it changed on the day the archive was made. These fix both.
+ *
+ * Kept here rather than in `bin/` so they are typechecked and unit-tested; the
+ * CLI is a thin wrapper over them. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
+ */
+import { outsideCodeFences, withFrontmatter } from './markdown-source.js';
+/** Route files at the docs root that an archive nested inside it already inherits. */
+export function isInheritedRouteFile(name) {
+    return /^\+(layout|error)\./.test(name);
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Point a page's docs links at the archive it is being copied into. An absolute
+ * link like `](/docs/theming)` resolves to the *current* docs forever, so
+ * without this an archive silently walks readers into newer content.
+ *
+ * Links already targeting a version folder are left alone, as are links inside
+ * fenced code, which are sample code rather than navigation.
+ */
+export function rewriteDocsLinks(text, options) {
+    const { docsBase, versionId } = options;
+    // Never double-prefix: skip links into an existing archive, and into the one
+    // being created (a page may already point at the id we're about to write).
+    const skip = new Set([...(options.archivedIds ?? []), versionId]);
+    const pattern = new RegExp(`(\\]\\(|href="|href='|\\]:[ \\t]+)(${escapeRe(docsBase)})([^)"'\\s]*)`, 'g');
+    return outsideCodeFences(text, (chunk) => chunk.replace(pattern, (match, prefix, base, rest) => {
+        // Guard the segment boundary: `/docsmith` must not become `/docs/v1mith`.
+        if (rest && !/^[/#?]/.test(rest))
+            return match;
+        const firstSegment = rest.startsWith('/') ? rest.slice(1).split(/[/#?]/)[0] : '';
+        if (firstSegment && skip.has(firstSegment))
+            return match;
+        return `${prefix}${base}/${versionId}${rest}`;
+    }));
+}
+/**
+ * Write a page's real last-updated date into its frontmatter. The collector
+ * prefers frontmatter over the git date, so an archive keeps the date each page
+ * was actually accurate on instead of the day the archive was created. Leaves an
+ * existing `lastUpdated` and any page without frontmatter alone.
+ */
+export function freezeLastUpdated(text, date) {
+    if (!date)
+        return text;
+    return withFrontmatter(text, (front) => /^lastUpdated:/m.test(front) ? front : `${front}\nlastUpdated: '${date}'`);
+}

package/dist/buildtime/archives.d.ts

@@ -0,0 +1,18 @@
+import type { ArchivesOnDisk } from '../core/version.js';
+/**
+ * Written into every archive `archive-version` creates. Not a convenience for
+ * the command: this file is what makes a directory an archived version rather
+ * than an ordinary section of the current docs, and the build reads it. The two
+ * are otherwise indistinguishable, since a page is assigned to a version by its
+ * first directory segment. See
+ * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ */
+export declare const ARCHIVE_MARKER = ".docsmith-archive";
+/** The text written into a new archive's marker file. */
+export declare function markerContents(id: string): string;
+/**
+ * The directories directly under `contentDir`, and which of them are archives.
+ * An absent docs root reads as empty rather than throwing: the collectors
+ * already report that case, and the command has its own message for it.
+ */
+export declare function discoverArchives(contentDir: string): ArchivesOnDisk;

package/dist/buildtime/archives.js

@@ -0,0 +1,43 @@
+/**
+ * What the docs root says about itself: which directories under it are archived
+ * versions. The scan is deliberately thin, so the reconciliation it feeds
+ * (`checkVersions`) stays pure and testable without a filesystem.
+ *
+ * Both callers cross this seam. The vite plugin scans before resolving versions;
+ * `archive-version` scans so it knows which directories not to copy into the
+ * archive it is writing.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Written into every archive `archive-version` creates. Not a convenience for
+ * the command: this file is what makes a directory an archived version rather
+ * than an ordinary section of the current docs, and the build reads it. The two
+ * are otherwise indistinguishable, since a page is assigned to a version by its
+ * first directory segment. See
+ * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ */
+export const ARCHIVE_MARKER = '.docsmith-archive';
+/** The text written into a new archive's marker file. */
+export function markerContents(id) {
+    return (`Archived docs for ${id}, created by \`svelte-docsmith archive-version\`.\n` +
+        `This folder is frozen: edit the docs root instead.\n` +
+        `Removing this file makes the build treat it as current-version content.\n`);
+}
+/**
+ * The directories directly under `contentDir`, and which of them are archives.
+ * An absent docs root reads as empty rather than throwing: the collectors
+ * already report that case, and the command has its own message for it.
+ */
+export function discoverArchives(contentDir) {
+    if (!fs.existsSync(contentDir))
+        return { marked: [], directories: [] };
+    const directories = fs
+        .readdirSync(contentDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+    return {
+        directories,
+        marked: directories.filter((name) => fs.existsSync(path.join(contentDir, name, ARCHIVE_MARKER)))
+    };
+}

package/dist/buildtime/cli/archive-version.d.ts

@@ -0,0 +1,18 @@
+export type ArchiveVersionOptions = {
+    /** Id of the archive to create. Becomes its directory name and URL segment. */
+    id: string;
+    /** Switcher label for the archive. Defaults to the id. */
+    label?: string;
+    /** Docs content directory, resolved against `cwd`. */
+    content?: string;
+    /** SvelteKit routes directory, resolved against `cwd`. */
+    routes?: string;
+    /** Working directory the relative options resolve against. */
+    cwd?: string;
+};
+/**
+ * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
+ * each copied page so it stays inside the archive and keeps its real
+ * last-updated date. Returns the number of pages archived.
+ */
+export declare function archiveVersion(options: ArchiveVersionOptions, log: (line: string) => void): number;

package/dist/buildtime/cli/archive-version.js

@@ -0,0 +1,104 @@
+/**
+ * `svelte-docsmith archive-version <id>`: freeze the current docs into an
+ * archived version folder so they keep serving the release they document while
+ * the docs root goes on being edited.
+ *
+ * The pure text transforms live in `../archive.js`; this is the filesystem work
+ * around them. It takes its working directory and its output sink rather than
+ * reading `process.cwd()` and calling `console.log`, so the whole command runs
+ * in-process under test. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertValidVersionId } from '../../core/version.js';
+import { freezeLastUpdated, isInheritedRouteFile, rewriteDocsLinks } from '../archive.js';
+import { ARCHIVE_MARKER, discoverArchives, markerContents } from '../archives.js';
+import { lastCommitDate } from '../git.js';
+import { docsBaseFrom } from '../paths.js';
+import { isPageFile } from '../vite/pages.js';
+import { CliError } from './error.js';
+/**
+ * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
+ * each copied page so it stays inside the archive and keeps its real
+ * last-updated date. Returns the number of pages archived.
+ */
+export function archiveVersion(options, log) {
+    const cwd = options.cwd ?? process.cwd();
+    const { id, label = options.id } = options;
+    try {
+        assertValidVersionId(id);
+    }
+    catch (error) {
+        throw new CliError(error.message);
+    }
+    const contentDir = path.resolve(cwd, options.content ?? 'src/routes/docs');
+    const routesDir = path.resolve(cwd, options.routes ?? 'src/routes');
+    const toDir = path.join(contentDir, id);
+    const rel = (p) => path.relative(cwd, p);
+    if (!fs.existsSync(contentDir)) {
+        throw new CliError(`content directory not found: ${rel(contentDir)}`);
+    }
+    if (fs.existsSync(toDir)) {
+        throw new CliError(`target already exists: ${rel(toDir)}`);
+    }
+    const docsBase = docsBaseFrom(routesDir, contentDir);
+    // Archives already on disk, so this run neither copies them into the new
+    // archive nor rewrites links that already point into one of them.
+    const archivedIds = new Set(discoverArchives(contentDir).marked);
+    /** Copy the docs root into the archive, skipping what the archive shouldn't hold. */
+    function copyCurrent(from, to) {
+        fs.mkdirSync(to, { recursive: true });
+        for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+            const src = path.join(from, entry.name);
+            const dest = path.join(to, entry.name);
+            if (entry.isDirectory()) {
+                // Never descend into the archive being written (it lives inside the docs
+                // root) or into an archive written by an earlier run.
+                if (src === toDir)
+                    continue;
+                if (from === contentDir && archivedIds.has(entry.name))
+                    continue;
+                copyCurrent(src, dest);
+            }
+            else {
+                // The root layout and error page already apply to the archive, which is
+                // nested inside them; copying them would nest a second DocsShell.
+                if (from === contentDir && isInheritedRouteFile(entry.name))
+                    continue;
+                fs.copyFileSync(src, dest);
+            }
+        }
+    }
+    /** Every file in the archive, paired with the source file it was copied from. */
+    function* eachCopiedFile(dir = toDir) {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const file = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                yield* eachCopiedFile(file);
+            else
+                yield { file, source: path.join(contentDir, path.relative(toDir, file)) };
+        }
+    }
+    copyCurrent(contentDir, toDir);
+    fs.writeFileSync(path.join(toDir, ARCHIVE_MARKER), markerContents(id));
+    let pages = 0;
+    for (const { file, source } of eachCopiedFile()) {
+        if (!isPageFile(path.basename(file)))
+            continue;
+        pages++;
+        const text = fs.readFileSync(file, 'utf-8');
+        fs.writeFileSync(file, freezeLastUpdated(rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }), lastCommitDate(source)));
+    }
+    log(`\n✓ Archived the current docs into ${rel(toDir)} (${pages} pages)\n`);
+    log('Links were rewritten to stay inside the archive, and each page kept');
+    log('its real last-updated date. Review the diff, then update');
+    log('docsmith({ versions }) so the archive is served:\n');
+    log('  versions: {');
+    log("    current: { id: '<new release>', label: '<new release>' },");
+    log(`    archived: [{ id: '${id}', label: '${label}' }${archivedIds.size ? ', …' : ''}]`);
+    log('  }\n');
+    // Until that paste lands the build fails, by design: the archive is on disk
+    // and undeclared. See docs/adr/0003-the-archive-marker-defines-an-archive.md.
+    log('Until then the build will fail, reporting this archive as undeclared.\n');
+    return pages;
+}

package/dist/buildtime/cli/error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A failure the user caused and can fix: a missing argument, a bad id, a target
+ * that already exists. The `bin/` shim prints its message and exits 1, without
+ * a stack, because a stack is noise for these. Anything else thrown out of the
+ * command is a bug and keeps its stack.
+ */
+export declare class CliError extends Error {
+    readonly name = "CliError";
+}

package/dist/buildtime/cli/error.js

@@ -0,0 +1,9 @@
+/**
+ * A failure the user caused and can fix: a missing argument, a bad id, a target
+ * that already exists. The `bin/` shim prints its message and exits 1, without
+ * a stack, because a stack is noise for these. Anything else thrown out of the
+ * command is a bug and keeps its stack.
+ */
+export class CliError extends Error {
+    name = 'CliError';
+}

package/dist/buildtime/cli/run.d.ts

@@ -0,0 +1,13 @@
+export { CliError } from './error.js';
+export { archiveVersion } from './archive-version.js';
+export declare const HELP = "svelte-docsmith \u2014 docs maintenance CLI\n\nUsage:\n  svelte-docsmith archive-version <id> [options]\n\nFreeze the current docs into an archived version folder. The archive keeps\nserving the release it documents while you go on editing the docs root.\n\nOptions:\n  --label <label>  switcher label for the archive (default: the id)\n  --content <dir>  docs content directory (default: src/routes/docs)\n  --routes <dir>   SvelteKit routes directory (default: src/routes)\n";
+/** Where the command writes, and what it resolves relative paths against. */
+export type CliIo = {
+    cwd?: string;
+    log?: (line: string) => void;
+};
+/**
+ * Run the CLI over `argv` (everything after the node binary and script). Throws
+ * {@link CliError} for anything the user can fix; the caller owns the exit code.
+ */
+export declare function run(argv: string[], io?: CliIo): void;

package/dist/buildtime/cli/run.js

@@ -0,0 +1,62 @@
+/**
+ * The `svelte-docsmith` maintenance CLI. Currently one command:
+ * `archive-version`.
+ *
+ * This is the whole command, not a helper for it: `bin/svelte-docsmith.mjs` is a
+ * shim that hands over `process.argv` and turns a thrown {@link CliError} into a
+ * message and an exit code. Keeping the process boundary out here means the
+ * command is typechecked, and testable in-process against a temporary directory
+ * rather than by spawning node and parsing stdout.
+ */
+import { archiveVersion } from './archive-version.js';
+import { CliError } from './error.js';
+export { CliError } from './error.js';
+export { archiveVersion } from './archive-version.js';
+export const HELP = `svelte-docsmith — docs maintenance CLI
+
+Usage:
+  svelte-docsmith archive-version <id> [options]
+
+Freeze the current docs into an archived version folder. The archive keeps
+serving the release it documents while you go on editing the docs root.
+
+Options:
+  --label <label>  switcher label for the archive (default: the id)
+  --content <dir>  docs content directory (default: src/routes/docs)
+  --routes <dir>   SvelteKit routes directory (default: src/routes)
+`;
+/** Parse `archive-version`'s flags and its one positional id. */
+function parseArchiveArgs(rest) {
+    const options = {};
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '--label')
+            options.label = rest[++i];
+        else if (arg === '--content')
+            options.content = rest[++i];
+        else if (arg === '--routes')
+            options.routes = rest[++i];
+        else if (!arg.startsWith('--') && !options.id)
+            options.id = arg;
+    }
+    if (!options.id) {
+        throw new CliError('missing <id>. e.g. `svelte-docsmith archive-version v1`');
+    }
+    return options;
+}
+/**
+ * Run the CLI over `argv` (everything after the node binary and script). Throws
+ * {@link CliError} for anything the user can fix; the caller owns the exit code.
+ */
+export function run(argv, io = {}) {
+    const log = io.log ?? ((line) => console.log(line));
+    const [command, ...rest] = argv;
+    if (!command) {
+        log(HELP);
+        return;
+    }
+    if (command !== 'archive-version') {
+        throw new CliError(`unknown command: ${command}\n\n${HELP}`);
+    }
+    archiveVersion({ ...parseArchiveArgs(rest), cwd: io.cwd }, log);
+}

package/dist/buildtime/{vite/git.d.ts → git.d.ts}

@@ -1,4 +1,4 @@
-/** Last git commit date (strict ISO) for a file, or undefined outside a repo. */
+/** Commit day (`YYYY-MM-DD`) a file last changed, or undefined outside a repo. */
 export declare function lastCommitDate(file: string): string | undefined;
 /**
  * Release dates keyed by version, read from the commit that introduced each

package/dist/buildtime/{vite/git.js → git.js}

@@ -1,8 +1,20 @@
+/**
+ * The git queries the build makes: when a page last changed, and when each
+ * release landed. Used by both the vite plugin and the `archive-version`
+ * command, which is why it sits here rather than under `vite/`.
+ *
+ * Every date here is `%cs`, the commit's calendar day (`YYYY-MM-DD`), never a
+ * timestamp. Dates from this module are rendered as a day and nothing more, and
+ * a date-only string parses to UTC midnight, so pinning the formatter to UTC
+ * renders the committer's own day identically for every reader and identically
+ * on the server and the client. A full timestamp buys precision no consumer
+ * uses and reintroduces the day-boundary drift.
+ */
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
-/** Last git commit date (strict ISO) for a file, or undefined outside a repo. */
+/** Commit day (`YYYY-MM-DD`) a file last changed, or undefined outside a repo. */
 export function lastCommitDate(file) {
-    const res = spawnSync('git', ['log', '-1', '--format=%cI', '--', file], {
+    const res = spawnSync('git', ['log', '-1', '--format=%cs', '--', file], {
         cwd: path.dirname(file),
         encoding: 'utf-8'
     });
@@ -19,7 +31,7 @@ export function changelogDates(file) {
     const dates = new Map();
     // `-L` would be per-line; instead walk the file's commits newest-first and
     // record the first commit in which each version heading appears.
-    const log = spawnSync('git', ['log', '--format=%H %cI', '--reverse', '--follow', '--', path.basename(file)], { cwd: path.dirname(file), encoding: 'utf-8' });
+    const log = spawnSync('git', ['log', '--format=%H %cs', '--reverse', '--follow', '--', path.basename(file)], { cwd: path.dirname(file), encoding: 'utf-8' });
     if (log.status !== 0)
         return dates;
     for (const line of log.stdout.trim().split('\n').filter(Boolean)) {

package/dist/buildtime/markdown-source.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The structure of a markdown page, as every build-time pass over one needs to
+ * see it: where the frontmatter block ends, and which lines are prose rather
+ * than fenced code.
+ *
+ * Both rules used to be respelled in each pass, and the copies drifted. A fence
+ * scanner that toggles on the marker's first character alone closes a ````
+ * block on the ```svelte nested inside it, which pulls sample code into the
+ * search index and sample headings into the table of contents. Keeping the
+ * rules here means the search index, the table of contents, the LLM output and
+ * the archive rewriter all agree on what a page's prose is.
+ */
+/** A page split at its frontmatter delimiters. */
+export type MarkdownSource = {
+    /** The YAML between the `---` lines, or undefined when the page has none. */
+    frontmatter: string | undefined;
+    /** Everything after the frontmatter block: prose, headings, fenced code, tags. */
+    body: string;
+};
+/** Split a page into its frontmatter and its body. */
+export declare function splitFrontmatter(source: string): MarkdownSource;
+/**
+ * Rewrite a page's frontmatter YAML in place, leaving the delimiters and the
+ * body byte-identical — including their line endings, which a split-and-rejoin
+ * would normalise. A page without frontmatter is returned untouched.
+ */
+export declare function withFrontmatter(source: string, transform: (frontmatter: string) => string): string;
+/** Apply `transform` to a page's prose lines, leaving fenced code untouched. */
+export declare function outsideCodeFences(text: string, transform: (line: string) => string): string;
+/** A page's prose lines, in order, with fenced code and its markers dropped. */
+export declare function proseLines(text: string): Generator<string>;

package/dist/buildtime/markdown-source.js

@@ -0,0 +1,90 @@
+/**
+ * The structure of a markdown page, as every build-time pass over one needs to
+ * see it: where the frontmatter block ends, and which lines are prose rather
+ * than fenced code.
+ *
+ * Both rules used to be respelled in each pass, and the copies drifted. A fence
+ * scanner that toggles on the marker's first character alone closes a ````
+ * block on the ```svelte nested inside it, which pulls sample code into the
+ * search index and sample headings into the table of contents. Keeping the
+ * rules here means the search index, the table of contents, the LLM output and
+ * the archive rewriter all agree on what a page's prose is.
+ */
+/**
+ * A page's frontmatter block: `---` on the first line, through the next line
+ * that starts with `---`. Group 1 is the YAML; the whole match spans the block
+ * including the line break that ends it, so the body starts where it stops.
+ *
+ * Deliberately as loose about the closing delimiter as remark-frontmatter,
+ * which is what mdsvex strips at render time. A stricter rule here would read
+ * a page differently from the renderer: a page mdsvex renders body-only would
+ * keep its frontmatter as prose, or lose the title that puts it in the nav.
+ */
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+/** An opening or closing code fence, indented anywhere on its line. */
+const FENCE = /^\s*(`{3,}|~{3,})/;
+/** Split a page into its frontmatter and its body. */
+export function splitFrontmatter(source) {
+    const match = FRONTMATTER.exec(source);
+    if (!match)
+        return { frontmatter: undefined, body: source };
+    return { frontmatter: match[1], body: source.slice(match[0].length) };
+}
+/**
+ * Rewrite a page's frontmatter YAML in place, leaving the delimiters and the
+ * body byte-identical — including their line endings, which a split-and-rejoin
+ * would normalise. A page without frontmatter is returned untouched.
+ */
+export function withFrontmatter(source, transform) {
+    const match = FRONTMATTER.exec(source);
+    if (!match)
+        return source;
+    const start = match[0].indexOf('\n') + 1;
+    return source.slice(0, start) + transform(match[1]) + source.slice(start + match[1].length);
+}
+/**
+ * A line-by-line scanner for fence state, rather than one regex pairing fences
+ * up, so an indented fence (inside a list item or a component) and a `~~~`
+ * fence are both recognised. Per CommonMark a fence closes only on the same
+ * character, at least as long as the opener, with no info string — so the
+ * ```svelte inside a ```` block opens nothing and closes nothing.
+ *
+ * Returns a predicate that consumes the page's lines in order and answers
+ * whether each one is prose. Fence markers themselves are not.
+ */
+function fenceScanner() {
+    let open;
+    return (line) => {
+        const match = FENCE.exec(line);
+        if (open) {
+            const closes = match &&
+                match[1][0] === open[0] &&
+                match[1].length >= open.length &&
+                !line.slice(match[0].length).trim();
+            if (closes)
+                open = undefined;
+            return false;
+        }
+        if (match) {
+            open = match[1];
+            return false;
+        }
+        return true;
+    };
+}
+/** Apply `transform` to a page's prose lines, leaving fenced code untouched. */
+export function outsideCodeFences(text, transform) {
+    const isProse = fenceScanner();
+    return text
+        .split('\n')
+        .map((line) => (isProse(line) ? transform(line) : line))
+        .join('\n');
+}
+/** A page's prose lines, in order, with fenced code and its markers dropped. */
+export function* proseLines(text) {
+    const isProse = fenceScanner();
+    for (const line of text.split('\n')) {
+        if (isProse(line))
+            yield line;
+    }
+}

package/dist/buildtime/paths.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The docs URL base, e.g. `/docs`, from the content directory's location under
+ * the routes directory. This is the same mapping the collectors use to turn a
+ * page's directory into its URL, so a page at `<routes>/docs/intro/+page.md` is
+ * served at `/docs/intro` under a base of `/docs`.
+ */
+export declare function docsBaseFrom(routesDir: string, contentDir: string): string;

package/dist/buildtime/paths.js

@@ -0,0 +1,15 @@
+/**
+ * Build-time path derivations shared by the vite plugin and the maintenance CLI.
+ * Both have to agree on where the docs live in URL space, and each deriving it
+ * separately is how they drift.
+ */
+import path from 'node:path';
+/**
+ * The docs URL base, e.g. `/docs`, from the content directory's location under
+ * the routes directory. This is the same mapping the collectors use to turn a
+ * page's directory into its URL, so a page at `<routes>/docs/intro/+page.md` is
+ * served at `/docs/intro` under a base of `/docs`.
+ */
+export function docsBaseFrom(routesDir, contentDir) {
+    return '/' + path.relative(routesDir, contentDir).split(path.sep).join('/');
+}

package/dist/buildtime/vite/collect.d.ts

@@ -1,11 +1,12 @@
 import type { DocsContentItem, LlmsDoc, SearchDoc } from '../../core/content.js';
+import type { DocsVersions } from '../../core/version.js';
 /**
  * Scan `contentDir` for `+page.md`/`+page.svx` files and read the frontmatter
  * fields the sidebar needs (plus the heading list for a server-rendered TOC and
  * an estimated reading time), deriving each page's URL from its directory
  * relative to `routesDir`. Pure and synchronous so it can be unit-tested.
  */
-export declare function collectDocs(contentDir: string, routesDir: string): DocsContentItem[];
+export declare function collectDocs(contentDir: string, routesDir: string, versions?: DocsVersions): DocsContentItem[];
 /**
  * Build the search records for every page under `contentDir`: title, section,
  * description, heading list, and plain-text body. Served as the lazy-loaded
@@ -13,11 +14,11 @@ export declare function collectDocs(contentDir: string, routesDir: string): Docs
  * bloating the eagerly-imported nav index. The missing-directory case is
  * already reported by {@link collectDocs}, so this stays quiet.
  */
-export declare function collectSearchDocs(contentDir: string, routesDir: string): SearchDoc[];
+export declare function collectSearchDocs(contentDir: string, routesDir: string, versions?: DocsVersions): SearchDoc[];
 /**
  * Build the LLM records for every page: title, section, description, and the
  * full markdown content. Served as the `svelte-docsmith/llms` virtual module and
  * consumed server-side by `llms.txt` / `llms-full.txt` routes, so it never ships
  * to the client.
  */
-export declare function collectLlmsDocs(contentDir: string, routesDir: string): LlmsDoc[];
+export declare function collectLlmsDocs(contentDir: string, routesDir: string, versions?: DocsVersions): LlmsDoc[];