svelte-docsmith 0.9.0 → 0.11.0

package/dist/buildtime/vite/collect.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { listPageFiles } from './pages.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { extractLlmsContent, extractSearchText, extractToc, readingMinutes } from './extract.js';
-import { lastCommitDate } from './git.js';
+import { lastCommitDate } from '../git.js';
 /**
  * Read a page's `section` frontmatter: a string is one level, an array is a
  * nested group path. Non-string array members are dropped; anything else is
@@ -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,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { DEFAULT_THEMES, lazyHighlighter } from '../highlight.js';
+import { checkVersions, resolveVersions } from '../../core/version.js';
+import { ARCHIVE_MARKER, discoverArchives } from '../archives.js';
+import { docsBaseFrom } from '../paths.js';
 import { isPageFile, listPageFiles } from './pages.js';
 import { collectDocs, collectLlmsDocs, collectSearchDocs } from './collect.js';
 import { collectReleases } from './releases.js';
@@ -47,6 +50,8 @@ 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;
+    const docsBase = docsBaseFrom(routesDir, contentDir);
     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,26 @@ 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`;
+                // Before anything is collected: a config that disagrees with the docs
+                // root produces an index that is wrong rather than empty, so it has to
+                // fail here rather than render. Re-runs on invalidation, so archiving
+                // during `dev` reports immediately.
+                checkVersions(versions, discoverArchives(contentDir), ARCHIVE_MARKER);
+                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) {

package/dist/buildtime/vite/releases.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { marked } from 'marked';
 import { parseChangelog } from '../changelog.js';
-import { changelogDates } from './git.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

package/dist/components/changelog/changelog-entry.svelte

@@ -3,12 +3,17 @@
 
 	const { release }: { release: ChangelogRelease } = $props();
 
+	// `timeZone: 'UTC'` is not cosmetic. `release.date` is a calendar day, which
+	// parses to UTC midnight, so formatting in the ambient zone shifts it a day
+	// west of UTC — and shifts it on the client but not on the server, so the
+	// rendered date changes under hydration.
 	const formatted = $derived(
 		release.date
 			? new Date(release.date).toLocaleDateString('en-US', {
 					year: 'numeric',
 					month: 'long',
-					day: 'numeric'
+					day: 'numeric',
+					timeZone: 'UTC'
 				})
 			: undefined
 	);

package/dist/components/chrome/copy-button.svelte

@@ -16,7 +16,7 @@
 	} = $props();
 </script>
 
-<Button {onclick} variant="ghost" size="icon" class="size-8 {className ?? ''}">
+<Button {onclick} variant="ghost" size="icon" aria-label="Copy" class="size-8 {className ?? ''}">
 	{#if copied}
 		<div in:fade={{ duration: 80 }}>
 			<Check class="text-emerald-500" />
@@ -26,5 +26,6 @@
 			<Copy />
 		</div>
 	{/if}
-	<span class="sr-only">Copy</span>
+	<!-- Announce success to screen readers without altering the button's name. -->
+	<span class="sr-only" aria-live="polite">{copied ? 'Copied to clipboard' : ''}</span>
 </Button>

package/dist/components/chrome/search.svelte

@@ -2,6 +2,7 @@
 	import { goto } from '$app/navigation';
 	import * as Command from '../shadcn/command/index.js';
 	import { useSearch } from '../../search/context.svelte.js';
+	import { useDocsPage } from '../docs-page-context.js';
 	import type { SearchDoc } from '../../core/index.js';
 	import type { SearchEngine } from '../../search/create-search.js';
 	import CornerDownLeft from '@lucide/svelte/icons/corner-down-left';
@@ -17,30 +18,44 @@
 		 * Lazily provide the generated search records. Wired by the consumer so the
 		 * index is code-split and only fetched when the palette first opens, e.g.
 		 * `() => import('svelte-docsmith/search').then((m) => m.docs)`.
+		 *
+		 * Receives the active version id on a versioned site, so a loader may
+		 * return just that version's records; results are scoped either way.
 		 */
-		load: () => Promise<SearchDoc[]>;
+		load: (versionId?: string) => Promise<SearchDoc[]>;
 		placeholder?: string;
 	} = $props();
 
 	const search = useSearch();
+	// The version being read, straight off the shell's resolved page view, so
+	// results and the cached engine follow the reader across a version switch.
+	const docsPage = useDocsPage();
+	const activeVersion = $derived(docsPage.view.activeVersionId);
 
 	let query = $state('');
 	let engine = $state<SearchEngine | null>(null);
 	let status = $state<'idle' | 'loading' | 'error'>('idle');
+	// The version the cached engine was built for, so a loader that returns only
+	// one version's records is rebuilt when the reader switches versions. Stays
+	// constant (and the engine cached) on unversioned and single-version sites.
+	let engineVersion: string | undefined;
 
 	const trimmed = $derived(query.trim());
-	const results = $derived(engine && trimmed ? engine.search(query) : []);
+	// Scope to the active version on a versioned site; `undefined` otherwise.
+	const results = $derived(engine && trimmed ? engine.search(query, undefined, activeVersion) : []);
 
 	// Build the index the first time the palette opens; keep it for later opens.
 	async function ensureEngine() {
-		if (engine || status === 'loading') return;
+		const version = activeVersion;
+		if ((engine && engineVersion === version) || status === 'loading') return;
 		status = 'loading';
 		try {
 			const [{ createSearchEngine }, docs] = await Promise.all([
 				import('../../search/create-search.js'),
-				load()
+				load(version)
 			]);
 			engine = createSearchEngine(docs);
+			engineVersion = version;
 			status = 'idle';
 		} catch (error) {
 			console.error('[svelte-docsmith] failed to load the search index', error);

package/dist/components/chrome/search.svelte.d.ts

@@ -4,8 +4,11 @@ type $$ComponentProps = {
      * Lazily provide the generated search records. Wired by the consumer so the
      * index is code-split and only fetched when the palette first opens, e.g.
      * `() => import('svelte-docsmith/search').then((m) => m.docs)`.
+     *
+     * Receives the active version id on a versioned site, so a loader may
+     * return just that version's records; results are scoped either way.
      */
-    load: () => Promise<SearchDoc[]>;
+    load: (versionId?: string) => Promise<SearchDoc[]>;
     placeholder?: string;
 };
 declare const Search: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/chrome/version-banner.svelte

@@ -0,0 +1,67 @@
+<script lang="ts">
+	import TriangleAlert from '@lucide/svelte/icons/triangle-alert';
+	import ArrowRight from '@lucide/svelte/icons/arrow-right';
+	import type { ResolvedVersion } from '../../core/index.js';
+
+	// Rendered by DocsShell only on an archived version, to warn a reader who
+	// landed there (usually from a search engine) and give them a one-click path
+	// to the current equivalent. A real <a> (not client nav) so it works without
+	// JS and stays crawlable.
+	const {
+		active,
+		current,
+		href
+	}: {
+		active: ResolvedVersion;
+		current: ResolvedVersion;
+		/** This page under the current version, from the resolved page view. */
+		href: string;
+	} = $props();
+</script>
+
+<div class="docsmith-version-banner" role="note">
+	<TriangleAlert class="banner-icon" size={18} aria-hidden="true" />
+	<p>
+		You're reading the <strong>{active.label}</strong> docs. The current version is
+		<strong>{current.label}</strong>.
+		<a {href}>View this page in {current.label} <ArrowRight size={14} /></a>
+	</p>
+</div>
+
+<style>
+	.docsmith-version-banner {
+		display: flex;
+		gap: 0.6rem;
+		align-items: flex-start;
+		margin-bottom: 1.75rem;
+		padding: 0.75rem 1rem;
+		border: 1px solid;
+		border-radius: var(--radius);
+		font-size: 0.9rem;
+		line-height: 1.5;
+		color: var(--foreground);
+		border-color: oklch(0.62 0.14 75 / 0.3);
+		background: oklch(0.62 0.14 75 / 0.1);
+	}
+	:global(.docsmith-version-banner .banner-icon) {
+		margin-top: 0.1rem;
+		flex-shrink: 0;
+		color: oklch(0.62 0.14 75);
+	}
+	:global(.dark) .docsmith-version-banner :global(.banner-icon) {
+		color: oklch(0.82 0.13 80);
+	}
+	.docsmith-version-banner p {
+		margin: 0;
+	}
+	.docsmith-version-banner a {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.2rem;
+		font-weight: 600;
+		color: var(--primary);
+		white-space: nowrap;
+		text-decoration: underline;
+		text-underline-offset: 2px;
+	}
+</style>

package/dist/components/chrome/version-banner.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedVersion } from '../../core/index.js';
+type $$ComponentProps = {
+    active: ResolvedVersion;
+    current: ResolvedVersion;
+    /** This page under the current version, from the resolved page view. */
+    href: string;
+};
+declare const VersionBanner: import("svelte").Component<$$ComponentProps, {}, "">;
+type VersionBanner = ReturnType<typeof VersionBanner>;
+export default VersionBanner;

package/dist/components/chrome/version-switcher.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+	import { goto } from '$app/navigation';
+	import { Button } from '../shadcn/button/index.js';
+	import * as DropdownMenu from '../shadcn/dropdown-menu/index.js';
+	import Check from '@lucide/svelte/icons/check';
+	import ChevronsUpDown from '@lucide/svelte/icons/chevrons-up-down';
+	import type { VersionLink } from '../../core/index.js';
+
+	// Purely presentational: where each version leads is resolved once, with the
+	// rest of the page view, in `core/docs-page.ts`.
+	const {
+		links
+	}: {
+		/** Every declared version and its destination, in switcher order. */
+		links: VersionLink[];
+	} = $props();
+
+	const active = $derived(links.find((link) => link.active));
+
+	function select(link: VersionLink) {
+		if (link.active) return;
+		goto(link.href);
+	}
+</script>
+
+<!-- Nothing to switch from without an active version, which only happens on an
+     unversioned site, where the header doesn't render this at all. -->
+{#if active}
+	<DropdownMenu.Root>
+		<DropdownMenu.Trigger>
+			{#snippet child({ props })}
+				<Button
+					variant="outline"
+					size="sm"
+					class="h-8 gap-1.5 px-2.5 font-medium"
+					aria-label={`Documentation version: ${active.label}. Change version`}
+					{...props}
+				>
+					<span class="truncate">{active.label}</span>
+					<ChevronsUpDown class="size-3.5 shrink-0 opacity-60" aria-hidden="true" />
+				</Button>
+			{/snippet}
+		</DropdownMenu.Trigger>
+		<DropdownMenu.Content align="start" class="w-44">
+			{#each links as link (link.id)}
+				<DropdownMenu.Item onSelect={() => select(link)} class="gap-2">
+					<Check class="size-4 {link.active ? 'opacity-100' : 'opacity-0'}" aria-hidden="true" />
+					<span class="flex-1 truncate">{link.label}</span>
+				</DropdownMenu.Item>
+			{/each}
+		</DropdownMenu.Content>
+	</DropdownMenu.Root>
+{/if}

package/dist/components/chrome/version-switcher.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { VersionLink } from '../../core/index.js';
+type $$ComponentProps = {
+    /** Every declared version and its destination, in switcher order. */
+    links: VersionLink[];
+};
+declare const VersionSwitcher: import("svelte").Component<$$ComponentProps, {}, "">;
+type VersionSwitcher = ReturnType<typeof VersionSwitcher>;
+export default VersionSwitcher;

package/dist/components/docs-page-context.d.ts

@@ -0,0 +1,20 @@
+import type { DocsPageView } from '../core/index.js';
+/** A live read of the page view: `view` re-reads the shell's `$derived`. */
+export type DocsPageContext = {
+    readonly view: DocsPageView;
+};
+/**
+ * Publish the page view. `DocsShell` calls this once, with a getter rather than
+ * a value, so readers see the current `$derived` rather than the one that
+ * existed at init.
+ */
+export declare function setDocsPage(view: () => DocsPageView): void;
+/**
+ * Read the page view. `getContext` only works during init, so this hands back
+ * an accessor rather than a snapshot: hold it at init, read `.view` where the
+ * value is used, and the read stays reactive.
+ *
+ * Throws outside `DocsShell`. Every caller is internal chrome the shell renders
+ * itself, so an absent context is a wiring bug, not a supported mode.
+ */
+export declare function useDocsPage(): DocsPageContext;

package/dist/components/docs-page-context.js

@@ -0,0 +1,41 @@
+/**
+ * The resolved page view, on context.
+ *
+ * `core/docs-page.ts` decides what the page is; this is the single route that
+ * decision travels to the chrome. Publishing it once is what keeps the headers
+ * from taking props described in terms of their grandchildren, and the search
+ * scope from being pushed into shared mutable state by an effect.
+ *
+ * Sits at the root of `components/` rather than in a concern folder of its own:
+ * `core/` stays free of any Svelte import, and both `layouts/` and `chrome/`
+ * read this, so it can't live in either without one importing the other.
+ */
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('docsmith-page');
+/**
+ * Publish the page view. `DocsShell` calls this once, with a getter rather than
+ * a value, so readers see the current `$derived` rather than the one that
+ * existed at init.
+ */
+export function setDocsPage(view) {
+    setContext(KEY, view);
+}
+/**
+ * Read the page view. `getContext` only works during init, so this hands back
+ * an accessor rather than a snapshot: hold it at init, read `.view` where the
+ * value is used, and the read stays reactive.
+ *
+ * Throws outside `DocsShell`. Every caller is internal chrome the shell renders
+ * itself, so an absent context is a wiring bug, not a supported mode.
+ */
+export function useDocsPage() {
+    const get = getContext(KEY);
+    if (!get) {
+        throw new Error('[svelte-docsmith] this component must be rendered inside <DocsShell>.');
+    }
+    return {
+        get view() {
+            return get();
+        }
+    };
+}

package/dist/components/layouts/docs-header.svelte

@@ -6,12 +6,13 @@
 	import SearchTrigger from '../chrome/search-trigger.svelte';
 	import { useSearch } from '../../search/context.svelte.js';
 	import ThemeToggle from '../chrome/theme-toggle.svelte';
+	import VersionSwitcher from '../chrome/version-switcher.svelte';
 	import type { DocsmithConfig, DocsmithLink } from '../../core/index.js';
 	import BookOpenText from '@lucide/svelte/icons/book-open-text';
 	import type { Snippet } from 'svelte';
-	import { page } from '$app/state';
 	import { cn } from '../../utils/cn.js';
 	import { normalizePath } from '../../utils/normalize-path.js';
+	import { useDocsPage } from '../docs-page-context.js';
 
 	const {
 		config,
@@ -28,7 +29,10 @@
 	// Present only when the consumer passed a `search` loader to DocsShell.
 	const search = useSearch();
 
-	const current = $derived(normalizePath(page.url.pathname));
+	// Everything about the page being read comes off the shell's one resolved
+	// view, including the normalized path the nav highlights against.
+	const docsPage = useDocsPage();
+	const current = $derived(docsPage.view.pathname);
 
 	/**
 	 * A header link is usually the entry point to a whole section rather than a
@@ -91,7 +95,11 @@
 				</nav>
 			{/if}
 
-			{#if config.version}
+			{#if docsPage.view.versionLinks.length > 1}
+				<div class="px-1">
+					<VersionSwitcher links={docsPage.view.versionLinks} />
+				</div>
+			{:else if config.version}
 				<div class="px-2">
 					<Badge
 						variant="outline"
@@ -121,6 +129,7 @@
 						size="icon"
 						variant="ghost"
 						target="_blank"
+						rel="noopener noreferrer"
 						href={config.github}
 						class="text-muted-foreground hover:text-foreground size-8"
 					>