svelte-docsmith 0.9.0 → 0.10.0

package/bin/svelte-docsmith.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// The svelte-docsmith maintenance CLI. Currently one command: `archive-version`,
+// which freezes today's docs into an archived version folder so they stay live
+// after a breaking release.
+//
+// The current version is served unprefixed from the docs root and is the folder
+// you keep editing; archives are copies under their own prefix. See
+// docs/adr/0001-unprefixed-current-docs.md. The text transforms live in
+// `src/lib/buildtime/archive.ts` so they are typechecked and unit-tested; this
+// file is the filesystem wrapper around them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import {
+	rewriteDocsLinks,
+	freezeLastUpdated,
+	isInheritedRouteFile
+} from '../dist/buildtime/archive.js';
+
+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)
+`;
+
+// Written into every archive this command creates, so later runs know which
+// directories are already archives and must not be copied into the new one.
+const MARKER = '.docsmith-archive';
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (command !== 'archive-version') {
+	console.log(HELP);
+	process.exit(command ? 1 : 0);
+}
+
+const opts = { content: 'src/routes/docs', routes: 'src/routes', label: undefined };
+let id;
+for (let i = 0; i < rest.length; i++) {
+	const arg = rest[i];
+	if (arg === '--label') opts.label = rest[++i];
+	else if (arg === '--content') opts.content = rest[++i];
+	else if (arg === '--routes') opts.routes = rest[++i];
+	else if (!arg.startsWith('--') && !id) id = arg;
+}
+
+const fail = (message) => {
+	console.error(`svelte-docsmith archive-version: ${message}`);
+	process.exit(1);
+};
+
+if (!id) fail('missing <id>. e.g. `svelte-docsmith archive-version v1`');
+// Must start alphanumeric: the id is both a directory name and a URL segment, so
+// `.`, `..` and dotfiles would escape the docs root or make a hidden, dead route.
+if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+	fail(`invalid id: ${id}. Start with a letter or digit; it is used as a URL segment.`);
+}
+
+const contentDir = path.resolve(opts.content);
+const routesDir = path.resolve(opts.routes);
+const toDir = path.join(contentDir, id);
+const rel = (p) => path.relative(process.cwd(), p);
+
+if (!fs.existsSync(contentDir)) fail(`content directory not found: ${rel(contentDir)}`);
+if (fs.existsSync(toDir)) fail(`target already exists: ${rel(toDir)}`);
+
+// The docs URL base (e.g. `/docs`), derived exactly as the vite plugin does.
+const docsBase = '/' + path.relative(routesDir, contentDir).split(path.sep).join('/');
+
+/** Directories directly under the docs root that are already archives. */
+const archivedIds = new Set(
+	fs
+		.readdirSync(contentDir, { withFileTypes: true })
+		.filter((e) => e.isDirectory() && fs.existsSync(path.join(contentDir, e.name, MARKER)))
+		.map((e) => e.name)
+);
+
+const isPage = (name) => name.endsWith('+page.md') || name.endsWith('+page.svx');
+
+/** 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)) };
+	}
+}
+
+/** The date a page last really changed, so the archive doesn't claim today. */
+function lastCommitDate(file) {
+	try {
+		const out = execFileSync('git', ['log', '-1', '--format=%cs', '--', file], {
+			cwd: path.dirname(file),
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore']
+		}).trim();
+		return out || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+copyCurrent(contentDir, toDir);
+fs.writeFileSync(
+	path.join(toDir, MARKER),
+	`Archived docs for ${id}, created by \`svelte-docsmith archive-version\`.\n` +
+		`This folder is frozen: edit the docs root instead.\n`
+);
+
+let pages = 0;
+for (const { file, source } of eachCopiedFile()) {
+	if (!isPage(path.basename(file))) continue;
+	pages++;
+	const text = fs.readFileSync(file, 'utf-8');
+	fs.writeFileSync(
+		file,
+		freezeLastUpdated(
+			rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }),
+			lastCommitDate(source)
+		)
+	);
+}
+
+const label = opts.label ?? id;
+console.log(`\n✓ Archived the current docs into ${rel(toDir)} (${pages} pages)\n`);
+console.log('Links were rewritten to stay inside the archive, and each page kept');
+console.log('its real last-updated date. Review the diff, then update');
+console.log('docsmith({ versions }) so the archive is served:\n');
+console.log('  versions: {');
+console.log("    current: { id: '<new release>', label: '<new release>' },");
+console.log(`    archived: [{ id: '${id}', label: '${label}' }${archivedIds.size ? ', …' : ''}]`);
+console.log('  }\n');

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/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/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[];

package/dist/buildtime/vite/collect.js

@@ -38,7 +38,7 @@ function sectionKey(value) {
  * frontmatter, derived URL, and title so every index (nav, search, llms) can be
  * built from a single read of each file.
  */
-function* eachTitledPage(contentDir, routesDir) {
+function* eachTitledPage(contentDir, routesDir, versions) {
     for (const file of listPageFiles(contentDir)) {
         const source = fs.readFileSync(file, 'utf-8');
         const front = parseFrontmatter(source, file);
@@ -46,7 +46,20 @@ function* eachTitledPage(contentDir, routesDir) {
             continue;
         const dir = path.dirname(file);
         const url = '/' + path.relative(routesDir, dir).split(path.sep).join('/');
-        yield { source, front, url, title: front.title, file };
+        yield { source, front, url, title: front.title, file, version: versionOf(dir) };
+    }
+    /**
+     * A page belongs to an archived version when its first directory segment under
+     * the content dir is that archive's id; everything else is the current
+     * version, which lives unprefixed at the docs root. No versions ⇒ undefined,
+     * which keeps an unversioned site's index byte-for-byte what it was.
+     */
+    function versionOf(dir) {
+        if (!versions)
+            return undefined;
+        const firstSegment = path.relative(contentDir, dir).split(path.sep)[0];
+        const archived = versions.archived?.find((v) => v.id === firstSegment);
+        return archived ? archived.id : versions.current.id;
     }
 }
 /**
@@ -55,14 +68,14 @@ function* eachTitledPage(contentDir, routesDir) {
  * 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 function collectDocs(contentDir, routesDir) {
+export function collectDocs(contentDir, routesDir, versions) {
     if (!fs.existsSync(contentDir)) {
         console.warn(`[svelte-docsmith] content directory not found: ${contentDir}\n` +
             `  The sidebar will be empty. Create your doc pages there, or point docsmith() at the right place with \`content\`.`);
         return [];
     }
     const items = [];
-    for (const { source, front, url, title, file } of eachTitledPage(contentDir, routesDir)) {
+    for (const { source, front, url, title, file, version } of eachTitledPage(contentDir, routesDir, versions)) {
         items.push({
             title,
             path: url,
@@ -70,9 +83,13 @@ export function collectDocs(contentDir, routesDir) {
             section: readSection(front.section),
             order: typeof front.order === 'number' ? front.order : undefined,
             sourcePath: path.relative(process.cwd(), file).split(path.sep).join('/'),
-            lastUpdated: lastCommitDate(file),
+            // Frontmatter wins over git so an archived page keeps the date it last
+            // really changed: archiving copies every page in one commit, which would
+            // otherwise stamp the whole archive with the day it was created.
+            lastUpdated: typeof front.lastUpdated === 'string' ? front.lastUpdated : lastCommitDate(file),
             readingTime: readingMinutes(extractSearchText(source)),
-            toc: extractToc(source)
+            toc: extractToc(source),
+            version
         });
     }
     if (items.length === 0) {
@@ -89,18 +106,19 @@ export function collectDocs(contentDir, routesDir) {
  * bloating the eagerly-imported nav index. The missing-directory case is
  * already reported by {@link collectDocs}, so this stays quiet.
  */
-export function collectSearchDocs(contentDir, routesDir) {
+export function collectSearchDocs(contentDir, routesDir, versions) {
     if (!fs.existsSync(contentDir))
         return [];
     const docs = [];
-    for (const { source, front, url, title } of eachTitledPage(contentDir, routesDir)) {
+    for (const { source, front, url, title, version } of eachTitledPage(contentDir, routesDir, versions)) {
         docs.push({
             path: url,
             title,
             section: sectionLabel(front.section),
             description: typeof front.description === 'string' ? front.description : undefined,
             headings: extractToc(source).map((entry) => entry.title),
-            text: extractSearchText(source)
+            text: extractSearchText(source),
+            version
         });
     }
     return docs.sort((a, b) => a.path.localeCompare(b.path));
@@ -111,18 +129,19 @@ export function collectSearchDocs(contentDir, routesDir) {
  * consumed server-side by `llms.txt` / `llms-full.txt` routes, so it never ships
  * to the client.
  */
-export function collectLlmsDocs(contentDir, routesDir) {
+export function collectLlmsDocs(contentDir, routesDir, versions) {
     if (!fs.existsSync(contentDir))
         return [];
     const docs = [];
-    for (const { source, front, url, title } of eachTitledPage(contentDir, routesDir)) {
+    for (const { source, front, url, title, version } of eachTitledPage(contentDir, routesDir, versions)) {
         docs.push({
             path: url,
             title,
             section: sectionKey(front.section),
             order: typeof front.order === 'number' ? front.order : undefined,
             description: typeof front.description === 'string' ? front.description : undefined,
-            content: extractLlmsContent(source, title)
+            content: extractLlmsContent(source, title),
+            version
         });
     }
     return docs.sort((a, b) => a.path.localeCompare(b.path));

package/dist/buildtime/vite/extract.js

@@ -1,4 +1,9 @@
 import GithubSlugger from 'github-slugger';
+import { proseLines, splitFrontmatter } from '../markdown-source.js';
+/** Drop a page's `<script>`/`<style>` blocks: component setup, not content. */
+function withoutSetupBlocks(body) {
+    return body.replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, '');
+}
 /** Strip inline markdown so a heading's TOC label is plain text. */
 export function stripInlineMarkdown(text) {
     return text
@@ -17,23 +22,9 @@ export function stripInlineMarkdown(text) {
  * samples are intentionally dropped to keep the index small and prose-focused.
  */
 export function extractSearchText(source) {
-    let body = source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
-    // Component/setup blocks aren't prose; drop them whole before line scanning.
-    body = body.replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, '');
+    const body = withoutSetupBlocks(splitFrontmatter(source).body);
     const out = [];
-    let fence = null;
-    for (const line of body.split('\n')) {
-        const f = /^\s*(`{3,}|~{3,})/.exec(line);
-        if (f) {
-            const ch = f[1][0];
-            if (fence === null)
-                fence = ch;
-            else if (ch === fence)
-                fence = null;
-            continue;
-        }
-        if (fence !== null)
-            continue;
+    for (const line of proseLines(body)) {
         // Skip table delimiter rows (`| --- | :--: |`) — pure structure, no words.
         if (/^\s*\|?[\s:|-]+\|[\s:|-]*$/.test(line))
             continue;
@@ -63,22 +54,9 @@ export function readingMinutes(text) {
  * heading ids exactly, not just for common cases.
  */
 export function extractToc(source) {
-    const body = source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
     const slugger = new GithubSlugger();
     const toc = [];
-    let fence = null;
-    for (const line of body.split('\n')) {
-        const f = /^\s*(`{3,}|~{3,})/.exec(line);
-        if (f) {
-            const ch = f[1][0];
-            if (fence === null)
-                fence = ch;
-            else if (ch === fence)
-                fence = null;
-            continue;
-        }
-        if (fence !== null)
-            continue;
+    for (const line of proseLines(splitFrontmatter(source).body)) {
         const m = /^(#{2,3})\s+(.+?)\s*#*\s*$/.exec(line);
         if (!m)
             continue;
@@ -95,10 +73,6 @@ export function extractToc(source) {
  * with the frontmatter title prepended as an `h1` (pages start their body at h2).
  */
 export function extractLlmsContent(source, title) {
-    const body = source
-        .replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '')
-        .replace(/<script[\s\S]*?<\/script>/gi, '')
-        .replace(/<style[\s\S]*?<\/style>/gi, '')
-        .trim();
+    const body = withoutSetupBlocks(splitFrontmatter(source).body).trim();
     return `# ${title}\n\n${body}`;
 }

package/dist/buildtime/vite/frontmatter.js

@@ -1,16 +1,17 @@
 import yaml from 'js-yaml';
+import { splitFrontmatter } from '../markdown-source.js';
 /**
  * Parse a page's leading YAML frontmatter block into a plain object. Returns an
  * empty object when there is no frontmatter; throws a located error on invalid
  * YAML so a typo surfaces with its filename instead of a blank page.
  */
 export function parseFrontmatter(source, file) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(source);
-    if (!match)
+    const { frontmatter } = splitFrontmatter(source);
+    if (frontmatter === undefined)
         return {};
     let data;
     try {
-        data = yaml.load(match[1]);
+        data = yaml.load(frontmatter);
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);

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

@@ -1,4 +1,5 @@
 import type { Plugin } from 'vite';
+import { type DocsVersions } from '../../core/version.js';
 export { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
 export { collectReleases } from './releases.js';
 export interface DocsmithViteOptions {
@@ -26,6 +27,14 @@ export interface DocsmithViteOptions {
      * hand-written per-release pages. Default: `'/changelog'`.
      */
     changelogPath?: string;
+    /**
+     * Declare documentation versions to enable versioned docs. `current` is the
+     * docs for the latest release: its pages sit directly under `<content>` and
+     * keep their unprefixed URLs. Each archived version's pages live under
+     * `<content>/<id>/` and are served at `/docs/<id>/…`. Omit for a single,
+     * unversioned docs tree (the default).
+     */
+    versions?: DocsVersions;
 }
 /**
  * The svelte-docsmith Vite plugin. Add it to `plugins` in `vite.config.ts`:

package/dist/buildtime/vite/index.js

@@ -19,6 +19,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { DEFAULT_THEMES, lazyHighlighter } from '../highlight.js';
+import { resolveVersions } from '../../core/version.js';
 import { isPageFile, listPageFiles } from './pages.js';
 import { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
 import { collectReleases } from './releases.js';
@@ -47,6 +48,10 @@ const VIRTUAL_CHANGELOG_ID = '\0svelte-docsmith:changelog';
 function contentIndexPlugin(options) {
     const contentDir = path.resolve(options.content ?? 'src/routes/docs');
     const routesDir = path.resolve(options.routes ?? 'src/routes');
+    const versions = options.versions;
+    // The docs URL base, e.g. `/docs`, derived from the content dir's location
+    // under the routes dir — the same mapping `collect.ts` uses for page URLs.
+    const docsBase = '/' + path.relative(routesDir, contentDir).split(path.sep).join('/');
     const changelogFile = options.changelog === false ? undefined : path.resolve(options.changelog ?? 'CHANGELOG.md');
     const changelogRoute = options.changelogPath ?? '/changelog';
     const changelogOverrides = path.join(routesDir, changelogRoute.replace(/^\//, ''));
@@ -71,19 +76,21 @@ function contentIndexPlugin(options) {
             if (id === VIRTUAL_CONTENT_ID) {
                 for (const file of listPageFiles(contentDir))
                     this.addWatchFile(file);
-                const docs = collectDocs(contentDir, routesDir);
-                return `export const docs = ${JSON.stringify(docs, null, 2)};\n`;
+                const docs = collectDocs(contentDir, routesDir, versions);
+                const resolved = resolveVersions(versions, docsBase, docs);
+                return (`export const docs = ${JSON.stringify(docs, null, 2)};\n` +
+                    `export const versions = ${JSON.stringify(resolved, null, 2)};\n`);
             }
             if (id === VIRTUAL_SEARCH_ID) {
                 for (const file of listPageFiles(contentDir))
                     this.addWatchFile(file);
-                const docs = collectSearchDocs(contentDir, routesDir);
+                const docs = collectSearchDocs(contentDir, routesDir, versions);
                 return `export const docs = ${JSON.stringify(docs)};\n`;
             }
             if (id === VIRTUAL_LLMS_ID) {
                 for (const file of listPageFiles(contentDir))
                     this.addWatchFile(file);
-                const docs = collectLlmsDocs(contentDir, routesDir);
+                const docs = collectLlmsDocs(contentDir, routesDir, versions);
                 return `export const docs = ${JSON.stringify(docs)};\n`;
             }
             if (id === VIRTUAL_CHANGELOG_ID) {