svelte-docsmith 0.9.0 → 0.10.0

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

@@ -2,16 +2,14 @@
 	import { page } from '$app/state';
 	import { afterNavigate } from '$app/navigation';
 	import {
-		navFromContent,
-		flattenNav,
-		navTrail,
+		resolveDocsPage,
 		type DocsContentItem,
 		type DocsmithConfig,
-		type SearchDoc
+		type SearchDoc,
+		type ResolvedVersion
 	} from '../../core/index.js';
 	import { createToc } from '../../toc/index.js';
 	import { createSearchState } from '../../search/context.svelte.js';
-	import { normalizePath } from '../../utils/normalize-path.js';
 	import Search from '../chrome/search.svelte';
 	import BackgroundPattern from '../chrome/background-pattern.svelte';
 	import ThemeProvider from '../chrome/theme-provider.svelte';
@@ -21,10 +19,11 @@
 	import DocsMobileHeader from './docs-mobile-header.svelte';
 	import DocsSidebar from './docs-sidebar.svelte';
 	import PrevNextNav from './prev-next-nav.svelte';
-	import Breadcrumbs, { type Crumb } from './breadcrumbs.svelte';
+	import Breadcrumbs from './breadcrumbs.svelte';
 	import CopyPageMenu from './copy-page-menu.svelte';
 	import PageFeedback from './page-feedback.svelte';
 	import SeoHead from './seo-head.svelte';
+	import VersionBanner from '../chrome/version-banner.svelte';
 	import SquarePen from '@lucide/svelte/icons/square-pen';
 	import TableOfContents from '../chrome/table-of-contents.svelte';
 	import type { Snippet } from 'svelte';
@@ -32,6 +31,7 @@
 	const {
 		config,
 		content = [],
+		versions = [],
 		children,
 		logo,
 		actions,
@@ -46,6 +46,14 @@
 	}: {
 		config: DocsmithConfig;
 		content?: DocsContentItem[];
+		/**
+		 * The resolved version manifest from `svelte-docsmith/content` (its
+		 * `versions` export). Provide it to enable versioned docs — the sidebar,
+		 * search, prev/next, and breadcrumbs scope to the version being read, and
+		 * once an archived version exists a header switcher and an archived-version
+		 * banner appear. Omit for a single tree.
+		 */
+		versions?: ResolvedVersion[];
 		children: Snippet;
 		/**
 		 * Override the head tags for this page. Doc pages get their `<title>` and
@@ -57,8 +65,9 @@
 		 * Enable the ⌘K search palette by lazily providing the generated index,
 		 * e.g. `search={() => import('svelte-docsmith/search').then((m) => m.docs)}`.
 		 * Omit to hide search. The index is fetched only when search first opens.
+		 * Receives the active version id on a versioned site.
 		 */
-		search?: () => Promise<SearchDoc[]>;
+		search?: (versionId?: string) => Promise<SearchDoc[]>;
 		/** Custom logo mark for the header and mobile menu. */
 		logo?: Snippet;
 		/** Extra header controls (desktop and mobile), before the theme toggle. */
@@ -98,55 +107,43 @@
 	// `search` loader is static for the shell's lifetime, so reading it once at
 	// init is intentional.
 	// svelte-ignore state_referenced_locally
-	if (search) createSearchState();
-
-	const nav = $derived(navFromContent(content));
+	const searchState = search ? createSearchState() : undefined;
 
-	// Match content by a trailing-slash-normalized path, so `/docs/intro/` and
-	// `/docs/intro` resolve to the same page regardless of the app's trailingSlash.
-	const pathname = $derived(normalizePath(page.url.pathname));
+	// Every rule about the page being read is resolved in one pure module
+	// (`core/docs-page.ts`): the active version and the content scoped to it, the
+	// sidebar, the entry, prev/next, breadcrumbs, the server-rendered TOC. Reading
+	// them off one view keeps the parts from disagreeing about which page or
+	// version is active. What stays here is presentation: locale formatting, the
+	// "min read" copy, and the live TOC.
+	const view = $derived(
+		resolveDocsPage({
+			content,
+			versions,
+			pathname: page.url.pathname,
+			editUrl: config.editUrl,
+			siteTitle: config.title
+		})
+	);
 
-	// The content entry for the current route drives the SEO title/description,
-	// the "Edit this page" link, and the "Last updated" stamp.
-	const currentEntry = $derived(content.find((item) => item.path === pathname));
+	// Keep the search palette scoped to the version currently being read.
+	$effect(() => {
+		if (searchState) searchState.version = view.activeVersionId;
+	});
 
-	const editHref = $derived(
-		config.editUrl && currentEntry?.sourcePath
-			? config.editUrl.replace(/\/$/, '') + '/' + currentEntry.sourcePath
+	const lastUpdatedLabel = $derived.by(() =>
+		view.lastUpdated
+			? new Intl.DateTimeFormat('en', { year: 'numeric', month: 'short', day: 'numeric' }).format(
+					view.lastUpdated
+				)
 			: undefined
 	);
-	const lastUpdatedLabel = $derived.by(() => {
-		const iso = currentEntry?.lastUpdated;
-		if (!iso) return undefined;
-		const d = new Date(iso);
-		return Number.isNaN(d.getTime())
-			? undefined
-			: new Intl.DateTimeFormat('en', { year: 'numeric', month: 'short', day: 'numeric' }).format(
-					d
-				);
-	});
-	const showFooterMeta = $derived(Boolean(editHref || lastUpdatedLabel));
+	const showFooterMeta = $derived(Boolean(view.editHref || lastUpdatedLabel));
 
 	const readingTimeLabel = $derived(
-		readingTime && currentEntry?.readingTime ? `${currentEntry.readingTime} min read` : undefined
+		readingTime && view.readingMinutes ? `${view.readingMinutes} min read` : undefined
 	);
 
-	// Ordered flat page list (leaves in sidebar reading order) drives prev/next.
-	const flatNav = $derived(flattenNav(nav));
-	const pageIndex = $derived(flatNav.findIndex((item) => item.url === pathname));
-	const prev = $derived(pageIndex > 0 ? flatNav[pageIndex - 1] : undefined);
-	const next = $derived(
-		pageIndex >= 0 && pageIndex < flatNav.length - 1 ? flatNav[pageIndex + 1] : undefined
-	);
-	const currentTitle = $derived(pageIndex >= 0 ? flatNav[pageIndex].title : config.title);
-
-	// Breadcrumb trail: the current page's sidebar group path, then the page
-	// itself (so a nested page reads e.g. Guides > Advanced > Middleware).
-	const breadcrumbs = $derived.by(() => {
-		const crumbs: Crumb[] = (navTrail(nav, pathname) ?? []).map((title) => ({ title }));
-		if (pageIndex >= 0) crumbs.push({ title: currentTitle });
-		return crumbs;
-	});
+	const breadcrumbs = $derived(view.breadcrumbs.map((title) => ({ title })));
 
 	// In-page TOC, scanned from the rendered content and re-scanned after every
 	// navigation (client-side included) so it never goes stale.
@@ -156,17 +153,17 @@
 		toc.refresh();
 	});
 
-	// Server-rendered TOC (headings extracted at build time into the content
-	// index) so the list is present on first paint. Once the client engine has
-	// scanned the DOM, its items take over (scroll-spy + edge-case accuracy).
-	const pageToc = $derived(content.find((item) => item.path === pathname)?.toc ?? []);
-	const tocItems = $derived(toc.items.length ? toc.items : pageToc);
+	// The build-time TOC from the content index is present on first paint; once
+	// the client engine has scanned the DOM, its items take over (scroll-spy +
+	// edge-case accuracy).
+	const tocItems = $derived(toc.items.length ? toc.items : view.toc);
 </script>
 
 <SeoHead
 	{config}
-	title={seo?.title ?? currentEntry?.title}
-	description={seo?.description ?? currentEntry?.description}
+	title={seo?.title ?? view.entry?.title}
+	description={seo?.description ?? view.entry?.description}
+	noindex={view.activeVersion?.noindex}
 />
 
 <div class="relative isolate flex min-h-screen flex-col">
@@ -197,7 +194,15 @@
 
 	<!-- One header system everywhere: DocsHeader on desktop, DocsMobileHeader
 	     below lg. The `page` layout just omits the sidebar nav and in-page TOC. -->
-	<DocsHeader {config} {logo} {actions} />
+	<DocsHeader
+		{config}
+		{logo}
+		{actions}
+		{versions}
+		active={view.activeVersion}
+		{content}
+		pathname={view.pathname}
+	/>
 
 	{#if layout === 'page'}
 		<DocsMobileHeader {config} {logo} {actions} />
@@ -208,16 +213,20 @@
 	{:else}
 		<DocsMobileHeader
 			{config}
-			{nav}
-			title={currentTitle}
+			nav={view.nav}
+			title={view.title}
 			{tocItems}
 			tocActiveId={toc.activeId}
 			{logo}
 			{actions}
+			{versions}
+			active={view.activeVersion}
+			{content}
+			pathname={view.pathname}
 		/>
 
 		<div class="mx-auto flex w-full max-w-7xl flex-1 gap-12 px-4 md:px-6 lg:px-8 lg:pt-10">
-			<DocsSidebar {nav} />
+			<DocsSidebar nav={view.nav} />
 
 			<main
 				bind:this={contentEl}
@@ -225,6 +234,15 @@
 				tabindex="-1"
 				class="min-w-0 flex-1 py-6 lg:py-0"
 			>
+				{#if view.isArchived && view.activeVersion && view.currentVersion}
+					<VersionBanner
+						active={view.activeVersion}
+						current={view.currentVersion}
+						pathname={view.pathname}
+						{content}
+					/>
+				{/if}
+
 				<div class="flex items-start justify-between gap-4">
 					<Breadcrumbs items={breadcrumbs} />
 					<div class="flex shrink-0 items-center gap-3">
@@ -233,8 +251,8 @@
 								{readingTimeLabel}
 							</span>
 						{/if}
-						{#if copyPage && currentEntry}
-							<CopyPageMenu path={pathname} origin={config.url ?? ''} />
+						{#if copyPage && view.entry}
+							<CopyPageMenu path={view.pathname} origin={config.url ?? ''} />
 						{/if}
 					</div>
 				</div>
@@ -244,9 +262,9 @@
 					<div
 						class="text-muted-foreground border-border mt-10 flex flex-wrap items-center gap-3 border-t pt-6 text-sm"
 					>
-						{#if editHref}
+						{#if view.editHref}
 							<a
-								href={editHref}
+								href={view.editHref}
 								target="_blank"
 								rel="noopener noreferrer"
 								class="hover:text-foreground inline-flex items-center gap-1.5 transition-colors"
@@ -261,18 +279,18 @@
 					</div>
 				{/if}
 
-				{#if feedback && currentEntry}
-					{#key pathname}
+				{#if feedback && view.entry}
+					{#key view.pathname}
 						<div class="mt-8">
 							<PageFeedback
-								path={pathname}
+								path={view.pathname}
 								onfeedback={typeof feedback === 'function' ? feedback : undefined}
 							/>
 						</div>
 					{/key}
 				{/if}
 
-				<PrevNextNav {prev} {next} bordered={!showFooterMeta} />
+				<PrevNextNav prev={view.prev} next={view.next} bordered={!showFooterMeta} />
 			</main>
 
 			<!-- Reserve the TOC column so its content filling in after hydration

package/dist/components/layouts/docs-shell.svelte.d.ts

@@ -1,8 +1,16 @@
-import { type DocsContentItem, type DocsmithConfig, type SearchDoc } from '../../core/index.js';
+import { type DocsContentItem, type DocsmithConfig, type SearchDoc, type ResolvedVersion } from '../../core/index.js';
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     config: DocsmithConfig;
     content?: DocsContentItem[];
+    /**
+     * The resolved version manifest from `svelte-docsmith/content` (its
+     * `versions` export). Provide it to enable versioned docs — the sidebar,
+     * search, prev/next, and breadcrumbs scope to the version being read, and
+     * once an archived version exists a header switcher and an archived-version
+     * banner appear. Omit for a single tree.
+     */
+    versions?: ResolvedVersion[];
     children: Snippet;
     /**
      * Override the head tags for this page. Doc pages get their `<title>` and
@@ -17,8 +25,9 @@ type $$ComponentProps = {
      * Enable the ⌘K search palette by lazily providing the generated index,
      * e.g. `search={() => import('svelte-docsmith/search').then((m) => m.docs)}`.
      * Omit to hide search. The index is fetched only when search first opens.
+     * Receives the active version id on a versioned site.
      */
-    search?: () => Promise<SearchDoc[]>;
+    search?: (versionId?: string) => Promise<SearchDoc[]>;
     /** Custom logo mark for the header and mobile menu. */
     logo?: Snippet;
     /** Extra header controls (desktop and mobile), before the theme toggle. */

package/dist/components/layouts/error-page.svelte

@@ -1,6 +1,11 @@
 <script lang="ts">
 	import { page } from '$app/state';
-	import type { DocsContentItem, DocsmithConfig, SearchDoc } from '../../core/index.js';
+	import type {
+		DocsContentItem,
+		DocsmithConfig,
+		ResolvedVersion,
+		SearchDoc
+	} from '../../core/index.js';
 	import DocsShell from './docs-shell.svelte';
 	import ArrowLeft from '@lucide/svelte/icons/arrow-left';
 	import type { Snippet } from 'svelte';
@@ -8,6 +13,7 @@
 	const {
 		config,
 		content = [],
+		versions = [],
 		search,
 		status,
 		title,
@@ -20,8 +26,14 @@
 		config: DocsmithConfig;
 		/** Content index, so the error page keeps the same header/footer as the site. */
 		content?: DocsContentItem[];
+		/**
+		 * The resolved version manifest (same as `DocsShell`). Pass it on a
+		 * versioned site so an error under an archived prefix keeps that version's
+		 * search scope, switcher, and `noindex`.
+		 */
+		versions?: ResolvedVersion[];
 		/** Enable the ⌘K search palette on the error page (same loader as DocsShell). */
-		search?: () => Promise<SearchDoc[]>;
+		search?: (versionId?: string) => Promise<SearchDoc[]>;
 		/** HTTP status; defaults to the current `page.status`. */
 		status?: number;
 		/** Heading; defaults to a message keyed off the status. */
@@ -49,7 +61,15 @@
 	);
 </script>
 
-<DocsShell {config} {content} {search} {pattern} layout="page" seo={{ title: resolvedTitle }}>
+<DocsShell
+	{config}
+	{content}
+	{versions}
+	{search}
+	{pattern}
+	layout="page"
+	seo={{ title: resolvedTitle }}
+>
 	<section
 		class="mx-auto flex min-h-[60vh] max-w-2xl flex-col items-center justify-center px-4 py-20 text-center md:px-6"
 	>

package/dist/components/layouts/error-page.svelte.d.ts

@@ -1,11 +1,17 @@
-import type { DocsContentItem, DocsmithConfig, SearchDoc } from '../../core/index.js';
+import type { DocsContentItem, DocsmithConfig, ResolvedVersion, SearchDoc } from '../../core/index.js';
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     config: DocsmithConfig;
     /** Content index, so the error page keeps the same header/footer as the site. */
     content?: DocsContentItem[];
+    /**
+     * The resolved version manifest (same as `DocsShell`). Pass it on a
+     * versioned site so an error under an archived prefix keeps that version's
+     * search scope, switcher, and `noindex`.
+     */
+    versions?: ResolvedVersion[];
     /** Enable the ⌘K search palette on the error page (same loader as DocsShell). */
-    search?: () => Promise<SearchDoc[]>;
+    search?: (versionId?: string) => Promise<SearchDoc[]>;
     /** HTTP status; defaults to the current `page.status`. */
     status?: number;
     /** Heading; defaults to a message keyed off the status. */

package/dist/components/layouts/seo-head.svelte

@@ -6,13 +6,16 @@
 	const {
 		config,
 		title,
-		description
+		description,
+		noindex = false
 	}: {
 		config: DocsmithConfig;
 		/** The page's own title (frontmatter or override); omit for the site root. */
 		title?: string;
 		/** The page's own description; falls back to `config.description`. */
 		description?: string;
+		/** Emit `robots: noindex`, for a doc version explicitly marked hidden. */
+		noindex?: boolean;
 	} = $props();
 
 	// "Page · Site", or just the site title when they would duplicate (the home page).
@@ -35,6 +38,10 @@
 
 <svelte:head>
 	<title>{fullTitle}</title>
+	{#if noindex}
+		<!-- Keep this version out of search results; still follow its links. -->
+		<meta name="robots" content="noindex, follow" />
+	{/if}
 	{#if metaDescription}
 		<meta name="description" content={metaDescription} />
 	{/if}

package/dist/components/layouts/seo-head.svelte.d.ts

@@ -5,6 +5,8 @@ type $$ComponentProps = {
     title?: string;
     /** The page's own description; falls back to `config.description`. */
     description?: string;
+    /** Emit `robots: noindex`, for a doc version explicitly marked hidden. */
+    noindex?: boolean;
 };
 declare const SeoHead: import("svelte").Component<$$ComponentProps, {}, "">;
 type SeoHead = ReturnType<typeof SeoHead>;

package/dist/core/content.d.ts

@@ -37,6 +37,11 @@ export type DocsContentItem = {
         title: string;
         depth: 2 | 3;
     }[];
+    /**
+     * The id of the version this page belongs to, when the site declares
+     * versions (`docsmith({ versions })`). `undefined` on unversioned sites.
+     */
+    version?: string;
 };
 /**
  * One page's searchable record, emitted at build time by the `docsmith()` vite
@@ -54,6 +59,8 @@ export type SearchDoc = {
     headings: string[];
     /** Plain-text body: prose and headings, code and markup removed. */
     text: string;
+    /** The page's version id when the site declares versions; else `undefined`. */
+    version?: string;
 };
 /**
  * One page's record for LLM-facing output, emitted at build time by the
@@ -70,4 +77,6 @@ export type LlmsDoc = {
     /** The page's markdown body (frontmatter and `<script>`/`<style>` removed,
      *  headings and code kept), with the title prepended as an `h1`. */
     content: string;
+    /** The page's version id when the site declares versions; else `undefined`. */
+    version?: string;
 };

package/dist/core/docs-page.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Docs page resolution: everything `DocsShell` needs to know about the page
+ * being read, derived in one place from the content index, the version manifest
+ * and the URL.
+ *
+ * Pure and framework-agnostic, so each rule is a field with a test rather than
+ * a derivation whose only test surface is a rendered tree. The view returns
+ * data, never formatted strings: locale formatting and copy stay in the
+ * component that renders them.
+ */
+import type { DocsContentItem } from './content.js';
+import { type NavGroup, type NavItem } from './nav.js';
+import { type ResolvedVersion } from './version.js';
+/** The page's build-time headings, as extracted into the content index. */
+type PageToc = NonNullable<DocsContentItem['toc']>;
+/** Everything `DocsShell` renders about the current page. */
+export type DocsPageView = {
+    /** The current path, trailing slash stripped. Match content against this. */
+    pathname: string;
+    /**
+     * The version owning the page, falling back to the current version off the
+     * docs tree (e.g. a `page` layout). `undefined` on an unversioned site.
+     */
+    activeVersion: ResolvedVersion | undefined;
+    /** {@link activeVersion}'s id, for scoping search. */
+    activeVersionId: string | undefined;
+    /** The current version, for the archived-version banner's "latest" link. */
+    currentVersion: ResolvedVersion | undefined;
+    /** Whether the page belongs to an archived (frozen) version. */
+    isArchived: boolean;
+    /** The content index scoped to {@link activeVersion}. */
+    scopedContent: DocsContentItem[];
+    /** Sidebar nav built from {@link scopedContent}. */
+    nav: NavGroup[];
+    /** The scoped content entry for this route, if the page is a doc page. */
+    entry: DocsContentItem | undefined;
+    /** "Edit this page" target. Absent without an edit base, or when archived. */
+    editHref: string | undefined;
+    /** The page's last commit date, unformatted. Absent if missing or unparseable. */
+    lastUpdated?: Date;
+    /** Estimated reading time in whole minutes, uncopied. */
+    readingMinutes?: number;
+    /** Previous page in sidebar reading order. */
+    prev: NavItem | undefined;
+    /** Next page in sidebar reading order. */
+    next: NavItem | undefined;
+    /** The page's nav title, falling back to the site title off the nav tree. */
+    title: string;
+    /**
+     * Breadcrumb titles: the page's group trail, then the page itself. Titles
+     * only, so this layer never depends on a component's `Crumb` type.
+     */
+    breadcrumbs: string[];
+    /** The page's server-rendered TOC, from {@link entry}. */
+    toc: PageToc;
+};
+/**
+ * Resolve the page being read. `pathname` is taken raw (normalized here, so the
+ * caller has one fewer place to remember) and every field is derived from the
+ * same normalized path and the same scoped content, so the sidebar, prev/next,
+ * breadcrumbs and TOC can never disagree about which page or version is active.
+ */
+export declare function resolveDocsPage(input: {
+    content: DocsContentItem[];
+    versions: ResolvedVersion[];
+    pathname: string;
+    editUrl?: string;
+    siteTitle: string;
+}): DocsPageView;
+export {};

package/dist/core/docs-page.js

@@ -0,0 +1,55 @@
+import { navFromContent, flattenNav, navTrail } from './nav.js';
+import { activeVersion, currentVersion, scopeContent } from './version.js';
+import { normalizePath } from '../utils/normalize-path.js';
+/**
+ * Resolve the page being read. `pathname` is taken raw (normalized here, so the
+ * caller has one fewer place to remember) and every field is derived from the
+ * same normalized path and the same scoped content, so the sidebar, prev/next,
+ * breadcrumbs and TOC can never disagree about which page or version is active.
+ */
+export function resolveDocsPage(input) {
+    const { content, versions, editUrl, siteTitle } = input;
+    const pathname = normalizePath(input.pathname);
+    // Off the docs tree there is no owning version, so fall back to the current
+    // one: a `page` layout still gets the current sidebar and search scope.
+    const active = activeVersion(versions, pathname) ?? (versions.length ? currentVersion(versions) : undefined);
+    const current = currentVersion(versions);
+    // An archived version is frozen, so don't invite edits to it.
+    const isArchived = Boolean(active && !active.current);
+    const scopedContent = scopeContent(content, active?.id);
+    const nav = navFromContent(scopedContent);
+    const entry = scopedContent.find((item) => item.path === pathname);
+    const flatNav = flattenNav(nav);
+    const pageIndex = flatNav.findIndex((item) => item.url === pathname);
+    const title = pageIndex >= 0 ? flatNav[pageIndex].title : siteTitle;
+    const breadcrumbs = navTrail(nav, pathname) ?? [];
+    if (pageIndex >= 0)
+        breadcrumbs.push(title);
+    return {
+        pathname,
+        activeVersion: active,
+        activeVersionId: active?.id,
+        currentVersion: current,
+        isArchived,
+        scopedContent,
+        nav,
+        entry,
+        editHref: editUrl && entry?.sourcePath && !isArchived
+            ? editUrl.replace(/\/$/, '') + '/' + entry.sourcePath
+            : undefined,
+        lastUpdated: parseDate(entry?.lastUpdated),
+        readingMinutes: entry?.readingTime,
+        prev: pageIndex > 0 ? flatNav[pageIndex - 1] : undefined,
+        next: pageIndex >= 0 && pageIndex < flatNav.length - 1 ? flatNav[pageIndex + 1] : undefined,
+        title,
+        breadcrumbs,
+        toc: entry?.toc ?? []
+    };
+}
+/** An ISO stamp as a Date, or `undefined` when absent or unparseable. */
+function parseDate(iso) {
+    if (!iso)
+        return undefined;
+    const date = new Date(iso);
+    return Number.isNaN(date.getTime()) ? undefined : date;
+}

package/dist/core/index.d.ts

@@ -1,3 +1,5 @@
 export { defineConfig, type DocsmithConfig, type DocsmithLink, type DocsmithFooterColumn, type DocsmithAnnouncement } from './config.js';
 export type { DocsContentItem, SearchDoc, LlmsDoc } from './content.js';
+export { resolveVersions, activeVersion, currentVersion, currentOnly, scopeContent, mapPathToVersion, type DocsVersion, type DocsVersions, type ResolvedVersion } from './version.js';
 export { navFromContent, flattenNav, navTrail, isNavGroup, type NavItem, type NavGroup, type NavNode } from './nav.js';
+export { resolveDocsPage, type DocsPageView } from './docs-page.js';

package/dist/core/index.js

@@ -3,4 +3,6 @@
 // several of these (e.g. the shell) import from here; the public surface is
 // re-exported through `src/lib/index.ts`.
 export { defineConfig } from './config.js';
+export { resolveVersions, activeVersion, currentVersion, currentOnly, scopeContent, mapPathToVersion } from './version.js';
 export { navFromContent, flattenNav, navTrail, isNavGroup } from './nav.js';
+export { resolveDocsPage } from './docs-page.js';

package/dist/core/version.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Versioned-docs domain logic. Pure and framework-agnostic: the vite plugin
+ * resolves the author's versions against the docs URL base at build time and
+ * emits the manifest; `DocsShell` and the switcher read it at runtime.
+ *
+ * The current version is served unprefixed at the docs root and is the only one
+ * anyone edits; superseded releases are frozen copies under their own prefix.
+ * See `docs/adr/0001-unprefixed-current-docs.md`. All of it is a no-op when a
+ * site declares no versions.
+ */
+import type { DocsContentItem } from './content.js';
+/** One documentation version, declared in the `docsmith()` vite plugin. */
+export type DocsVersion = {
+    /** Stable id. Also the URL/directory segment for an archived version. */
+    id: string;
+    /** Label shown in the switcher and banner, e.g. `'v2'`. */
+    label: string;
+    /** Keep this version out of search engines. Defaults to `false`. */
+    noindex?: boolean;
+};
+/**
+ * A site's versions. `current` is the docs for the latest release: it lives at
+ * the docs root, is served unprefixed, and is the folder you edit. `archived`
+ * holds frozen copies of superseded releases, each in `<docs root>/<id>/`, in
+ * the order they should appear in the switcher (newest first).
+ */
+export type DocsVersions = {
+    current: DocsVersion;
+    archived?: DocsVersion[];
+};
+/** A {@link DocsVersion} with the URL fields the runtime needs, computed at build time. */
+export type ResolvedVersion = DocsVersion & {
+    /** Absolute URL base: the docs root for `current`, `/docs/<id>` for an archive. */
+    basePath: string;
+    /** The version's first page in sidebar order, for the switcher's fallback. */
+    landing: string;
+    /** Whether this is the current version (as opposed to an archived one). */
+    current: boolean;
+    /** Whether search engines should skip this version. */
+    noindex: boolean;
+};
+/**
+ * Resolve author versions against the docs URL base (e.g. `/docs`) and the
+ * collected content: compute each version's `basePath` and its `landing` (first
+ * page in sidebar reading order). Emitted as the `versions` manifest in
+ * `svelte-docsmith/content`, current first, then archives in declared order.
+ *
+ * Returns an empty manifest for an unversioned site, which makes every
+ * downstream scoping, switcher and banner step a no-op.
+ */
+export declare function resolveVersions(versions: DocsVersions | undefined, docsBase: string, content: DocsContentItem[]): ResolvedVersion[];
+/**
+ * The resolved version owning `pathname`, by longest matching `basePath`. An
+ * archive's base is longer than the current version's, so `/docs/v1/x` picks
+ * `v1` while `/docs/x` falls to the current version. `undefined` off the docs
+ * tree entirely, or on an unversioned site.
+ */
+export declare function activeVersion(versions: ResolvedVersion[], pathname: string): ResolvedVersion | undefined;
+/** The current version: the docs for the latest release. */
+export declare function currentVersion(versions: ResolvedVersion[]): ResolvedVersion | undefined;
+/**
+ * Keep only the current version's pages, for `sitemap.xml` and `llms.txt`, so
+ * search engines and LLMs index one canonical set. A no-op when the site
+ * declares no versions. Works over any record carrying `version`.
+ */
+export declare function currentOnly<T extends {
+    version?: string;
+}>(items: T[], versions: ResolvedVersion[]): T[];
+/**
+ * Content scoped to one version. With no version id (unversioned site) the
+ * content passes through unchanged, so every caller stays a no-op off the
+ * versioned path.
+ */
+export declare function scopeContent(content: DocsContentItem[], versionId: string | undefined): DocsContentItem[];
+/**
+ * Map the current page to its equivalent under `to`: swap the version base, and
+ * fall back to the target's landing page when that doc doesn't exist there.
+ * `targetPaths` is the set of the target version's page URLs.
+ */
+export declare function mapPathToVersion(pathname: string, from: ResolvedVersion, to: ResolvedVersion, targetPaths: Iterable<string>): string;