svelte-docsmith 0.8.0 → 0.10.0

package/dist/buildtime/preprocess.js

@@ -6,11 +6,13 @@
  * doesn't care where it's registered). It must never import component code.
  */
 import rehypeSectionize from '@hbsnow/rehype-sectionize';
-import { transformerNotationDiff, transformerNotationErrorLevel, transformerNotationFocus, transformerNotationHighlight, transformerNotationWordHighlight } from '@shikijs/transformers';
+import { transformerNotationDiff, transformerNotationErrorLevel, transformerNotationFocus, transformerNotationHighlight, transformerNotationWordHighlight, transformerMetaHighlight } from '@shikijs/transformers';
 import { escapeSvelte, mdsvex } from 'mdsvex';
 import { fileURLToPath } from 'node:url';
 import rehypeSlug from 'rehype-slug';
 import { DEFAULT_LANGS, DEFAULT_THEMES, lazyHighlighter } from './highlight.js';
+import { parseFenceMeta, hasTwoslash } from './fence-meta.js';
+import { twoslashTransformer, twoslashFailure } from './twoslash.js';
 /**
  * Build the svelte-docsmith preprocessor: mdsvex with Shiki highlighting (via
  * the raw-code `highlight` hook, the correct mdsvex integration point), heading
@@ -31,25 +33,75 @@ export function docsmith(options = {}) {
         extensions: options.extensions ?? ['.md'],
         layout,
         highlight: {
-            highlighter: async (code, lang) => {
+            // mdsvex passes the fence's trailing metadata as the third argument,
+            // which is where `title=` and the line-number flags come from.
+            highlighter: async (code, lang, meta) => {
+                const fence = parseFenceMeta(meta);
+                // A ```mermaid fence renders as a diagram, not highlighted code. The
+                // component is dynamic-imported so `mermaid` (an optional peer dep) is
+                // only pulled into pages that actually use it; JSON.stringify safely
+                // carries the multi-line source into the attribute.
+                if (lang === 'mermaid') {
+                    // The pending branch renders server-side, reserving the diagram's
+                    // space at first paint so it doesn't shift the page in on load.
+                    // The client component reuses the same skeleton class until the
+                    // diagram is ready, so the two never disagree on height.
+                    return (`{#await import('svelte-docsmith/mermaid')}` +
+                        `<div class="docsmith-mermaid-skeleton not-prose" aria-hidden="true"></div>` +
+                        `{:then { default: Mermaid }}` +
+                        `<Mermaid code={${JSON.stringify(code)}} />` +
+                        `{/await}`);
+                }
                 const highlighter = await getHighlighter();
                 const language = lang && highlighter.getLoadedLanguages().includes(lang) ? lang : 'text';
-                // Shiki highlights the raw code; escapeSvelte makes the result safe
-                // to embed in a Svelte component.
-                const html = escapeSvelte(highlighter.codeToHtml(code, {
+                // Comment-driven annotations authors write inside the fence:
+                // line highlight, diff (++/--), focus, error/warning, and
+                // word highlight. Each strips its own marker comment.
+                const notation = [
+                    // Line ranges from the fence meta (```svelte {4,7-9}). The only way
+                    // to highlight a line in markup: Shiki's comment markers are not
+                    // recognised inside a Svelte template region, where an HTML comment
+                    // is stripped without applying anything.
+                    transformerMetaHighlight(),
+                    transformerNotationHighlight(),
+                    transformerNotationDiff(),
+                    transformerNotationFocus(),
+                    transformerNotationErrorLevel(),
+                    transformerNotationWordHighlight()
+                ];
+                const render = (extra = []) => highlighter.codeToHtml(code, {
                     lang: language,
                     themes,
-                    // Comment-driven annotations authors write inside the fence:
-                    // line highlight, diff (++/--), focus, error/warning, and
-                    // word highlight. Each strips its own marker comment.
-                    transformers: [
-                        transformerNotationHighlight(),
-                        transformerNotationDiff(),
-                        transformerNotationFocus(),
-                        transformerNotationErrorLevel(),
-                        transformerNotationWordHighlight()
-                    ]
-                }));
+                    // transformerMetaHighlight reads the raw fence meta from here.
+                    meta: { __raw: meta ?? '' },
+                    transformers: [...extra, ...notation]
+                });
+                let rendered;
+                if (options.twoslash && hasTwoslash(meta)) {
+                    const loaded = await twoslashTransformer();
+                    if ('error' in loaded) {
+                        console.warn(`[svelte-docsmith] ${loaded.error}`);
+                        rendered = render();
+                    }
+                    else {
+                        try {
+                            rendered = render([loaded.transformer]);
+                        }
+                        catch (error) {
+                            // One snippet that doesn't typecheck must not take the site
+                            // down; fall back to a plain highlight and say which it was.
+                            console.warn(`[svelte-docsmith] twoslash could not annotate a ${language} block: ` +
+                                twoslashFailure(error));
+                            rendered = render();
+                        }
+                    }
+                }
+                else {
+                    rendered = render();
+                }
+                // escapeSvelte makes the highlighted result safe to embed in a
+                // Svelte component.
+                const html = escapeSvelte(rendered);
                 // Without a layout there is no `Components.pre` to render through —
                 // keep Shiki's own <pre> as-is.
                 if (layout === undefined)
@@ -60,7 +112,15 @@ export function docsmith(options = {}) {
                     .replace(/^<pre[^>]*>/, '')
                     .replace(/<\/pre>\s*$/, '')
                     .trim();
-                return `<Components.pre>{@html \`${inner}\`}</Components.pre>`;
+                const showNumbers = fence.lineNumbers ?? options.lineNumbers ?? false;
+                const attrs = [
+                    fence.title ? `title=${JSON.stringify(fence.title)}` : '',
+                    showNumbers ? 'lineNumbers' : '',
+                    showNumbers && fence.startLine !== undefined ? `startLine={${fence.startLine}}` : ''
+                ]
+                    .filter(Boolean)
+                    .join(' ');
+                return `<Components.pre${attrs ? ' ' + attrs : ''}>{@html \`${inner}\`}</Components.pre>`;
             }
         },
         remarkPlugins: options.remarkPlugins,

package/dist/buildtime/twoslash.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Twoslash support for code fences that opt in with ```ts twoslash.
+ *
+ * Twoslash runs the snippet through the TypeScript compiler and annotates it
+ * with the real inferred types, which is what makes a hover show `string`
+ * rather than a guess. The cost is that it **throws** on anything that does not
+ * typecheck: a missing import, a type error, an incomplete fragment.
+ *
+ * That strictness is the point, but it must not be able to take a whole site
+ * down. {@link highlightWithTwoslash} therefore falls back to an ordinary
+ * highlight and warns, naming the file, rather than failing the build over one
+ * bad snippet.
+ *
+ * The packages are optional peer dependencies, loaded only when a fence asks
+ * for them, so sites that never use Twoslash pay nothing for it.
+ */
+import type { ShikiTransformer } from 'shiki';
+type Loaded = {
+    transformer: ShikiTransformer;
+} | {
+    error: string;
+};
+export declare function twoslashTransformer(): Promise<Loaded>;
+/** One-line reason a snippet could not be annotated, for the build warning. */
+export declare function twoslashFailure(error: unknown): string;
+export {};

package/dist/buildtime/twoslash.js

@@ -0,0 +1,40 @@
+let cached;
+/**
+ * Build the Twoslash transformer once per process. `langs` must include
+ * `svelte`, or Svelte fences are silently passed through unannotated: the
+ * transformer's default allowlist is TypeScript only.
+ */
+async function loadTransformer() {
+    try {
+        const [{ transformerTwoslash }, { createTwoslasher }] = await Promise.all([
+            import('@shikijs/twoslash'),
+            import('twoslash-svelte')
+        ]);
+        return {
+            transformer: transformerTwoslash({
+                // The fence's meta is parsed by docsmith, which decides per block
+                // whether to include this transformer at all.
+                explicitTrigger: false,
+                langs: ['ts', 'tsx', 'js', 'svelte'],
+                twoslasher: createTwoslasher()
+            })
+        };
+    }
+    catch {
+        return {
+            error: "'twoslash' requires its optional peer dependencies. " +
+                'Install them with: npm i -D @shikijs/twoslash twoslash-svelte typescript'
+        };
+    }
+}
+export function twoslashTransformer() {
+    cached ??= loadTransformer();
+    return cached;
+}
+/** One-line reason a snippet could not be annotated, for the build warning. */
+export function twoslashFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Twoslash errors are multi-line with a code frame; the first line carries
+    // the actual diagnostic.
+    return message.split('\n').find((line) => line.trim()) ?? 'unknown error';
+}

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/git.d.ts

@@ -1,2 +1,9 @@
 /** Last git commit date (strict ISO) for a file, 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
+ * `## <version>` heading in a changelog. Changesets does not write dates, and a
+ * tag lookup misses versions released before tagging was set up, so the file's
+ * own history is the most reliable source available.
+ */
+export declare function changelogDates(file: string): Map<string, string>;

package/dist/buildtime/vite/git.js

@@ -9,3 +9,35 @@ export function lastCommitDate(file) {
     const date = res.status === 0 ? res.stdout.trim() : '';
     return date || undefined;
 }
+/**
+ * Release dates keyed by version, read from the commit that introduced each
+ * `## <version>` heading in a changelog. Changesets does not write dates, and a
+ * tag lookup misses versions released before tagging was set up, so the file's
+ * own history is the most reliable source available.
+ */
+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' });
+    if (log.status !== 0)
+        return dates;
+    for (const line of log.stdout.trim().split('\n').filter(Boolean)) {
+        const [hash, date] = line.split(' ');
+        if (!hash || !date)
+            continue;
+        const show = spawnSync('git', ['show', `${hash}:./${path.basename(file)}`], {
+            cwd: path.dirname(file),
+            encoding: 'utf-8'
+        });
+        if (show.status !== 0)
+            continue;
+        for (const match of show.stdout.matchAll(/^##\s+(?!#)(.+?)\s*$/gm)) {
+            const version = match[1].trim();
+            // First commit containing this heading wins, which is its release.
+            if (!dates.has(version))
+                dates.set(version, date);
+        }
+    }
+    return dates;
+}

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

@@ -1,5 +1,7 @@
 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 {
     /** Directory scanned for doc pages. Default: `'src/routes/docs'`. */
     content?: string;
@@ -13,6 +15,26 @@ export interface DocsmithViteOptions {
         light: string;
         dark: string;
     };
+    /**
+     * Path to the `CHANGELOG.md` that feeds the generated
+     * `svelte-docsmith/changelog` index. Default: `'CHANGELOG.md'` in the app
+     * directory; point it at the package whose releases you publish. Set `false`
+     * to skip the changelog entirely.
+     */
+    changelog?: string | false;
+    /**
+     * Route the changelog is served at, used to build feed links and to find
+     * 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,9 +19,12 @@
 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';
 export { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
+export { collectReleases } from './releases.js';
 /**
  * The svelte-docsmith Vite plugin. Add it to `plugins` in `vite.config.ts`:
  *
@@ -40,9 +43,18 @@ const SEARCH_SPECIFIER = 'svelte-docsmith/search';
 const VIRTUAL_SEARCH_ID = '\0svelte-docsmith:search';
 const LLMS_SPECIFIER = 'svelte-docsmith/llms';
 const VIRTUAL_LLMS_ID = '\0svelte-docsmith:llms';
+const CHANGELOG_SPECIFIER = 'svelte-docsmith/changelog';
+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(/^\//, ''));
     return {
         name: 'docsmith-content',
         enforce: 'pre',
@@ -53,6 +65,8 @@ function contentIndexPlugin(options) {
                 return VIRTUAL_SEARCH_ID;
             if (id === LLMS_SPECIFIER)
                 return VIRTUAL_LLMS_ID;
+            if (id === CHANGELOG_SPECIFIER)
+                return VIRTUAL_CHANGELOG_ID;
         },
         load(id) {
             // Watch each page file (not the directory) so editing frontmatter or
@@ -62,21 +76,30 @@ 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) {
+                if (!changelogFile)
+                    return `export const releases = [];\n`;
+                this.addWatchFile(changelogFile);
+                const releases = collectReleases(changelogFile, changelogOverrides, changelogRoute);
+                return `export const releases = ${JSON.stringify(releases)};\n`;
+            }
         },
         configureServer(server) {
             server.watcher.add(contentDir);

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

@@ -0,0 +1,12 @@
+import type { ChangelogRelease } from '../../core/changelog.js';
+/**
+ * Read a Changesets `CHANGELOG.md` into releases, dated from git history, and
+ * linked to a hand-written page where one exists.
+ *
+ * `overridesDir` is scanned for directories named after a version
+ * (`src/routes/changelog/0.9.0/`), so a release worth a proper write-up can
+ * have one while the rest stay generated.
+ */
+export declare function collectReleases(changelogFile: string, overridesDir?: string, routePath?: string): ChangelogRelease[];
+/** Default location of a monorepo package's changelog, relative to the app. */
+export declare function defaultChangelogPath(cwd?: string): string;

package/dist/buildtime/vite/releases.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { marked } from 'marked';
+import { parseChangelog } from '../changelog.js';
+import { changelogDates } from './git.js';
+/**
+ * Render an entry's markdown to HTML at build time. Changesets entries use
+ * inline code, emphasis, links and nested lists, so shipping the raw markdown
+ * would mean every consuming site needed a runtime renderer.
+ */
+function renderItem(markdown) {
+    return marked.parse(markdown, { async: false, gfm: true }).trim();
+}
+/**
+ * Read a Changesets `CHANGELOG.md` into releases, dated from git history, and
+ * linked to a hand-written page where one exists.
+ *
+ * `overridesDir` is scanned for directories named after a version
+ * (`src/routes/changelog/0.9.0/`), so a release worth a proper write-up can
+ * have one while the rest stay generated.
+ */
+export function collectReleases(changelogFile, overridesDir, routePath = '/changelog') {
+    if (!fs.existsSync(changelogFile))
+        return [];
+    const releases = parseChangelog(fs.readFileSync(changelogFile, 'utf-8'));
+    const dates = changelogDates(changelogFile);
+    const overrides = new Set();
+    if (overridesDir && fs.existsSync(overridesDir)) {
+        for (const entry of fs.readdirSync(overridesDir, { withFileTypes: true })) {
+            if (entry.isDirectory())
+                overrides.add(entry.name);
+        }
+    }
+    return releases.map((release) => {
+        // Directory names can't contain the dots a version has on every platform,
+        // so `0.9.0` may be written as `0-9-0`.
+        const slug = release.version.replace(/\./g, '-');
+        const override = overrides.has(release.version)
+            ? release.version
+            : overrides.has(slug)
+                ? slug
+                : undefined;
+        return {
+            ...release,
+            groups: release.groups.map((group) => ({
+                ...group,
+                items: group.items.map(renderItem)
+            })),
+            ...(dates.get(release.version) ? { date: dates.get(release.version) } : {}),
+            ...(override ? { path: `${routePath}/${override}` } : {})
+        };
+    });
+}
+/** Default location of a monorepo package's changelog, relative to the app. */
+export function defaultChangelogPath(cwd = process.cwd()) {
+    return path.resolve(cwd, 'CHANGELOG.md');
+}