svelte-docsmith 0.12.1 → 0.13.0

package/README.md

@@ -15,8 +15,17 @@ Write a markdown file under `src/routes/docs/` and you get a styled page with
 syntax highlighting, heading anchors, a sidebar derived from your content, and a
 live table of contents. No per-page wiring, no content collection to configure.
 
-> **Status: pre-1.0.** Published to npm and usable today. The public API is still
-> stabilising, so minor releases may include breaking changes until v1.0.
+> **Status: pre-1.0.** Published to npm and usable today. Minor releases may still
+> include breaking changes until v1.0.
+>
+> **What 1.0 will lock.** Authoring components, `DocsShell`, `ErrorPage`,
+> `defineConfig`, the preprocessor, the Vite plugin, the sitemap / llms / feed
+> generators, the search engine, and the theming contract — ordinary semver,
+> breaking changes ride a major.
+>
+> **What stays experimental.** Versioning: `DocsVersions`, `currentOnly`, the
+> archive marker, and the `archive-version` command. They may still change in a
+> minor until authors have used them for real.
 
 ## Install
 
@@ -166,6 +175,20 @@ plugin you already added:
   Graph / Twitter tags for every page from its frontmatter, no per-page wiring.
 - **Error pages.** `ErrorPage` gives a styled 404 that keeps the site chrome;
   drop it into a SvelteKit `+error.svelte`.
+- **Versioned docs.** Declare `versions` on the Vite plugin, freeze a release
+  with `npx svelte-docsmith archive-version <id>`, and pass the generated
+  manifest to `DocsShell`. Scope sitemap / llms endpoints to the current
+  version with `currentOnly`.
+- **Changelog.** Point the plugin at your `CHANGELOG.md`; import the parsed
+  releases from `svelte-docsmith/changelog`, render them with `Changelog`, and
+  wire `generateFeed` into an Atom endpoint.
+- **Mermaid.** A mermaid code fence is rendered client-side (optional `mermaid`
+  peer dependency, loaded only on pages that need it).
+- **Landing sections.** `Hero`, `FeatureGrid`, `Feature`, `CTA`, and `Action`
+  for the marketing page in front of your docs.
+- **Generators.** Framework-agnostic helpers for `sitemap.xml`, `llms.txt` /
+  `llms-full.txt`, and the changelog Atom feed — drop them into `+server.ts`
+  routes over the generated indexes.
 - **Components.** `Callout`, `Tabs`, `Steps`, `Card`, `Accordion`, `Badge`,
   `Kbd`, `FileTree`, `PropsTable`, and more, authored right inside markdown.
 - Heading anchors, a scroll-spy table of contents, and one-click copy on every
@@ -187,15 +210,21 @@ override the tokens yourself.
 
 ## What's exported
 
-| Entry point                    | What it is                                                                                                                               |
-| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `svelte-docsmith`              | All components (`DocsShell`, `ErrorPage`, `LiveExample`, `Callout`, `Tabs`, …), plus `defineConfig`, `createSearchEngine`, and the types |
-| `svelte-docsmith/preprocess`   | `docsmith()`, the mdsvex/Shiki pipeline (Node, config time)                                                                              |
-| `svelte-docsmith/vite`         | `docsmith()`, the content index, search index, and `?source` transform (Node, build)                                                     |
-| `svelte-docsmith/content`      | `docs`, the generated sidebar content index                                                                                              |
-| `svelte-docsmith/search`       | `docs`, the generated full-text search index (lazy-load it)                                                                              |
-| `svelte-docsmith/theme.css`    | the base style contract                                                                                                                  |
-| `svelte-docsmith/themes/*.css` | the eleven theme presets                                                                                                                 |
+| Entry point                    | What it is                                                                                                                                                                                                                               |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `svelte-docsmith`              | Components (`DocsShell`, `Changelog`, landing sections, `LiveExample`, `Callout`, …), `defineConfig`, `createSearchEngine`, `generateSitemap` / `generateLlmsTxt` / `generateLlmsFullTxt` / `generateFeed`, `currentOnly`, and the types |
+| `svelte-docsmith/preprocess`   | `docsmith()`, the mdsvex/Shiki pipeline (Node, config time)                                                                                                                                                                              |
+| `svelte-docsmith/vite`         | `docsmith()`, the content / search / llms / changelog indexes and `?source` transform (Node, build)                                                                                                                                      |
+| `svelte-docsmith/content`      | `docs` and `versions`, the generated sidebar content index and version manifest                                                                                                                                                          |
+| `svelte-docsmith/search`       | `docs`, the generated full-text search index (lazy-load it)                                                                                                                                                                              |
+| `svelte-docsmith/llms`         | `docs`, the generated LLM content index (for `llms.txt` / `llms-full.txt` routes)                                                                                                                                                        |
+| `svelte-docsmith/changelog`    | `releases`, the generated changelog index (parsed from `CHANGELOG.md`)                                                                                                                                                                   |
+| `svelte-docsmith/mermaid`      | the Mermaid diagram component (lazy-loaded by the preprocessor when a mermaid fence is present)                                                                                                                                          |
+| `svelte-docsmith/theme.css`    | the base style contract                                                                                                                                                                                                                  |
+| `svelte-docsmith/themes/*.css` | the eleven theme presets                                                                                                                                                                                                                 |
+
+The package also ships a CLI binary: `npx svelte-docsmith archive-version <id>`
+freezes the current docs into a versioned archive.
 
 The vendored shadcn primitives and internal helpers (the TOC engine, clipboard
 utility, markdown renderer map) are **not** part of the public API; they can

package/dist/buildtime/archive.d.ts

@@ -29,3 +29,21 @@ export declare function rewriteDocsLinks(text: string, options: {
  * existing `lastUpdated` and any page without frontmatter alone.
  */
 export declare function freezeLastUpdated(text: string, date: string | undefined): string;
+/**
+ * The specifiers a page's `<script>` imports from outside the freeze boundary,
+ * deduplicated in source order. `pageDir` is the page's directory relative to
+ * the docs root, which is what its relative imports resolve against.
+ *
+ * Archiving copies the docs root and nothing else, so anything reached from
+ * outside it keeps resolving to current code: a live example on an archived
+ * page demonstrates the current library rather than the version the page
+ * documents, with a green build and nothing said. Hence `$lib`, bare npm
+ * specifiers and relative paths that climb out all count, while a relative
+ * import landing inside the docs root is frozen along with the page.
+ *
+ * `svelte-docsmith` itself is never reported. An archived page importing the
+ * authoring components is the expected shape, and those are covered by the
+ * stability promise rather than by this notice. See
+ * `docs/adr/0005-an-archive-freezes-content-not-dependencies.md`.
+ */
+export declare function boundaryCrossings(source: string, pageDir: string): string[];

package/dist/buildtime/archive.js

@@ -8,7 +8,7 @@
  * CLI is a thin wrapper over them. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
  */
 import { atBoundary, firstSegmentUnder } from '../utils/url.js';
-import { outsideCodeFences, withFrontmatter } from './markdown-source.js';
+import { outsideCodeFences, scriptBlocks, 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);
@@ -50,3 +50,63 @@ export function freezeLastUpdated(text, date) {
         return text;
     return withFrontmatter(text, (front) => /^lastUpdated:/m.test(front) ? front : `${front}\nlastUpdated: '${date}'`);
 }
+/**
+ * An import's specifier, static or dynamic. The clause between `import` and
+ * `from` may not hold a quote or a paren, so the scan cannot run past a
+ * side-effect import to borrow a later `from`, and `import.meta.glob('./x')`
+ * matches nothing.
+ */
+const IMPORT = /\bimport\s*\(?\s*(?:[^'"()]*?\bfrom\s*)?['"]([^'"]+)['"]/g;
+/** The package an archived page is expected to import, and its subpaths. */
+const LIBRARY = 'svelte-docsmith';
+/**
+ * Whether a relative specifier climbs out of the docs root when resolved from a
+ * page `depth` directories inside it. Counting segments rather than resolving
+ * real paths keeps the rule pure, and the docs root is the only boundary that
+ * matters: where under it a surviving import lands is the archive's business.
+ */
+function escapesRoot(specifier, depth) {
+    let level = depth;
+    for (const segment of specifier.split('/')) {
+        if (segment === '..')
+            level--;
+        else if (segment !== '.' && segment !== '')
+            level++;
+        if (level < 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * The specifiers a page's `<script>` imports from outside the freeze boundary,
+ * deduplicated in source order. `pageDir` is the page's directory relative to
+ * the docs root, which is what its relative imports resolve against.
+ *
+ * Archiving copies the docs root and nothing else, so anything reached from
+ * outside it keeps resolving to current code: a live example on an archived
+ * page demonstrates the current library rather than the version the page
+ * documents, with a green build and nothing said. Hence `$lib`, bare npm
+ * specifiers and relative paths that climb out all count, while a relative
+ * import landing inside the docs root is frozen along with the page.
+ *
+ * `svelte-docsmith` itself is never reported. An archived page importing the
+ * authoring components is the expected shape, and those are covered by the
+ * stability promise rather than by this notice. See
+ * `docs/adr/0005-an-archive-freezes-content-not-dependencies.md`.
+ */
+export function boundaryCrossings(source, pageDir) {
+    const depth = pageDir.split('/').filter(Boolean).length;
+    const found = new Set();
+    for (const block of scriptBlocks(source)) {
+        for (const [, specifier] of block.matchAll(IMPORT)) {
+            if (specifier === LIBRARY || specifier.startsWith(`${LIBRARY}/`))
+                continue;
+            // Only a package name can start with something other than a dot, and no
+            // package name starts with one, so this is the whole relative/bare split.
+            if (specifier.startsWith('.') && !escapesRoot(specifier, depth))
+                continue;
+            found.add(specifier);
+        }
+    }
+    return [...found];
+}

package/dist/buildtime/archives.d.ts

@@ -6,6 +6,9 @@ import type { ArchivesOnDisk } from '../core/version.js';
  * are otherwise indistinguishable, since a page is assigned to a version by its
  * first directory segment. See
  * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ *
+ * @experimental Outside the 1.0 stability promise. Name and role may change in
+ * a minor until authors have used versioning for real.
  */
 export declare const ARCHIVE_MARKER = ".docsmith-archive";
 /** The text written into a new archive's marker file. */

package/dist/buildtime/archives.js

@@ -16,6 +16,9 @@ import path from 'node:path';
  * are otherwise indistinguishable, since a page is assigned to a version by its
  * first directory segment. See
  * `docs/adr/0003-the-archive-marker-defines-an-archive.md`.
+ *
+ * @experimental Outside the 1.0 stability promise. Name and role may change in
+ * a minor until authors have used versioning for real.
  */
 export const ARCHIVE_MARKER = '.docsmith-archive';
 /** The text written into a new archive's marker file. */

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

@@ -14,5 +14,8 @@ export type ArchiveVersionOptions = {
  * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
  * each copied page so it stays inside the archive and keeps its real
  * last-updated date. Returns the number of pages archived.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export declare function archiveVersion(options: ArchiveVersionOptions, log: (line: string) => void): number;

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

@@ -3,15 +3,23 @@
  * archived version folder so they keep serving the release they document while
  * the docs root goes on being edited.
  *
+ * Freezes content, not dependencies: the prose, samples and URLs are that
+ * version's, while anything a page imports keeps resolving to whatever the app
+ * currently has installed. See
+ * `docs/adr/0005-an-archive-freezes-content-not-dependencies.md`.
+ *
  * The pure text transforms live in `../archive.js`; this is the filesystem work
  * around them. It takes its working directory and its output sink rather than
  * reading `process.cwd()` and calling `console.log`, so the whole command runs
  * in-process under test. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
+ *
+ * @experimental Outside the 1.0 stability promise. Flags and behaviour may
+ * change in a minor until authors have used versioning for real.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { assertValidVersionId } from '../../core/version.js';
-import { freezeLastUpdated, isInheritedRouteFile, rewriteDocsLinks } from '../archive.js';
+import { boundaryCrossings, freezeLastUpdated, isInheritedRouteFile, rewriteDocsLinks } from '../archive.js';
 import { ARCHIVE_MARKER, discoverArchives, markerContents } from '../archives.js';
 import { commitDates } from '../git.js';
 import { docsBaseFrom } from '../paths.js';
@@ -21,6 +29,9 @@ import { CliError } from './error.js';
  * Copy the docs root into `<content>/<id>/`, mark it as an archive, and rewrite
  * each copied page so it stays inside the archive and keeps its real
  * last-updated date. Returns the number of pages archived.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export function archiveVersion(options, log) {
     const cwd = options.cwd ?? process.cwd();
@@ -84,17 +95,23 @@ export function archiveVersion(options, log) {
     // be read: an archive is written once and never edited again, so a page that
     // misses its date here keeps the wrong one for good.
     const dates = commitDates(contentDir, (reason) => {
-        log(`\n! Could not read commit dates: ${reason}`);
+        log(`\n! Skipping git-derived page dates: ${reason}`);
         log('  Archived pages will keep no last-updated date.\n');
     });
     copyCurrent(contentDir, toDir);
     fs.writeFileSync(path.join(toDir, ARCHIVE_MARKER), markerContents(id));
     let pages = 0;
+    /** One `path: specifiers` line per page that imports across the freeze boundary. */
+    const crossings = [];
     for (const { file, source } of eachCopiedFile()) {
         if (!isPageFile(path.basename(file)))
             continue;
         pages++;
         const text = fs.readFileSync(file, 'utf-8');
+        const pageDir = path.relative(toDir, path.dirname(file)).split(path.sep).join('/');
+        const crossed = boundaryCrossings(text, pageDir);
+        if (crossed.length)
+            crossings.push(`    ${rel(file)}: ${crossed.join(', ')}`);
         fs.writeFileSync(file, freezeLastUpdated(rewriteDocsLinks(text, { docsBase, versionId: id, archivedIds }), dates.get(source)));
     }
     log(`\n✓ Archived the current docs into ${rel(toDir)} (${pages} pages)\n`);
@@ -102,6 +119,17 @@ export function archiveVersion(options, log) {
     // Only claim the dates were kept when the walk actually produced some.
     if (dates.size)
         log('Each page kept its real last-updated date.');
+    // Informational: the archive is correct as content, and there is nothing to
+    // fix here. Said out loud because the alternative is a green build hiding a
+    // v1 page that demos v2, which nothing downstream can notice.
+    if (crossings.length) {
+        const count = crossings.length === 1 ? '1 page' : `${crossings.length} pages`;
+        log(`\n! ${count} import across the freeze boundary:`);
+        crossings.sort().forEach(log);
+        log('  Archiving copies the docs root, not what it imports, so these keep');
+        log('  resolving to current code. Their examples will demonstrate the');
+        log('  current library rather than the version this archive documents.\n');
+    }
     log('Review the diff, then update docsmith({ versions }) so the archive');
     log('is served:\n');
     log('  versions: {');

package/dist/buildtime/cli/run.js

@@ -7,6 +7,9 @@
  * message and an exit code. Keeping the process boundary out here means the
  * command is typechecked, and testable in-process against a temporary directory
  * rather than by spawning node and parsing stdout.
+ *
+ * @experimental `archive-version` sits outside the 1.0 stability promise and
+ * may change in a minor until authors have used versioning for real.
  */
 import { archiveVersion } from './archive-version.js';
 import { CliError } from './error.js';

package/dist/buildtime/git.d.ts

@@ -14,12 +14,19 @@
  * all-or-nothing: a truncated read would date some pages and not others, which
  * looks like real data and is not.
  *
- * Only a truncated read calls `onFail`, because it is the one failure that would
- * otherwise date some pages and not others. A directory outside a repository, a
- * missing directory, or a machine without git all yield no dates, which every
- * caller already handles and which the plugin already reports where it matters.
- * Reporting is the caller's to do, which is why this takes a callback rather
- * than writing to the console itself.
+ * A shallow clone also yields no dates. Its single commit introduces every
+ * tracked file, so a walk would stamp every page with the same day — silent,
+ * plausible, and wrong for both page footers and sitemap `<lastmod>`. Omitting
+ * the date is legitimate; a uniform wrong date is not. Callers that need real
+ * dates should build from a full clone (`fetch-depth: 0` in CI, unshallow on
+ * the host).
+ *
+ * `onFail` fires for a truncated read or a shallow repository: those are the
+ * cases that would otherwise produce dates that look real and are not. A
+ * directory outside a repository, a missing directory, or a machine without git
+ * all yield no dates quietly, which every caller already handles. Reporting is
+ * the caller's to do, which is why this takes a callback rather than writing to
+ * the console itself.
  */
 export declare function commitDates(dir: string, onFail?: (reason: string) => void, 
 /**

package/dist/buildtime/git.js

@@ -28,12 +28,19 @@ import path from 'node:path';
  * all-or-nothing: a truncated read would date some pages and not others, which
  * looks like real data and is not.
  *
- * Only a truncated read calls `onFail`, because it is the one failure that would
- * otherwise date some pages and not others. A directory outside a repository, a
- * missing directory, or a machine without git all yield no dates, which every
- * caller already handles and which the plugin already reports where it matters.
- * Reporting is the caller's to do, which is why this takes a callback rather
- * than writing to the console itself.
+ * A shallow clone also yields no dates. Its single commit introduces every
+ * tracked file, so a walk would stamp every page with the same day — silent,
+ * plausible, and wrong for both page footers and sitemap `<lastmod>`. Omitting
+ * the date is legitimate; a uniform wrong date is not. Callers that need real
+ * dates should build from a full clone (`fetch-depth: 0` in CI, unshallow on
+ * the host).
+ *
+ * `onFail` fires for a truncated read or a shallow repository: those are the
+ * cases that would otherwise produce dates that look real and are not. A
+ * directory outside a repository, a missing directory, or a machine without git
+ * all yield no dates quietly, which every caller already handles. Reporting is
+ * the caller's to do, which is why this takes a callback rather than writing to
+ * the console itself.
  */
 export function commitDates(dir, onFail, 
 /**
@@ -43,6 +50,13 @@ export function commitDates(dir, onFail,
  */
 maxBuffer = 256 * 1024 * 1024) {
     const dates = new Map();
+    // One cheap probe before the walk. On a shallow clone the walk would "work"
+    // and return one day for every file — worse than failing, so refuse first.
+    if (isShallowRepository(dir)) {
+        onFail?.('shallow clone: git history is incomplete, so commit dates would be wrong. ' +
+            'Build from a full clone (e.g. actions/checkout fetch-depth: 0), or set lastUpdated in frontmatter.');
+        return dates;
+    }
     const res = spawnSync('git', ['log', '--format=%cs', '--name-only', '--relative', '--no-renames', '--', '.'], 
     // The 1 MB default would truncate rather than throw on a large history,
     // which is why the cap is raised and the result checked below.
@@ -71,6 +85,17 @@ maxBuffer = 256 * 1024 * 1024) {
     }
     return dates;
 }
+/**
+ * Whether `dir` sits in a shallow clone. Outside a repository, or when git is
+ * missing, returns false so the walk's own failure path still owns that case.
+ */
+function isShallowRepository(dir) {
+    const res = spawnSync('git', ['rev-parse', '--is-shallow-repository'], {
+        cwd: dir,
+        encoding: 'utf-8'
+    });
+    return res.status === 0 && res.stdout.trim() === 'true';
+}
 /**
  * Release dates keyed by version, read from the commit that introduced each
  * `## <version>` heading in a changelog. Changesets does not write dates, and a

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

@@ -29,3 +29,12 @@ export declare function withFrontmatter(source: string, transform: (frontmatter:
 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>;
+/**
+ * The code inside each `<script>` block a page actually runs, in order.
+ *
+ * Fenced blocks are skipped, which is the whole reason this reads the page
+ * through {@link proseLines} rather than scanning the raw text: a docs page
+ * about authoring is mostly ```svelte samples that open with a `<script>`, and
+ * those are code being displayed, not code the page runs.
+ */
+export declare function scriptBlocks(text: string): Generator<string>;

package/dist/buildtime/markdown-source.js

@@ -88,3 +88,25 @@ export function* proseLines(text) {
             yield line;
     }
 }
+/**
+ * A `<script>` element with any attributes, through its closing tag. The open
+ * tag has to start a line, indented no further than CommonMark lets HTML be:
+ * four spaces make an indented code block, and mid-line means a sentence about
+ * a script tag rather than one. Authoring prose writes `` `<script>` `` in
+ * inline code constantly, and a page that only talks about a script block has
+ * no script block.
+ */
+const SCRIPT_BLOCK = /^ {0,3}<script\b[^>]*>([\s\S]*?)<\/script>/gim;
+/**
+ * The code inside each `<script>` block a page actually runs, in order.
+ *
+ * Fenced blocks are skipped, which is the whole reason this reads the page
+ * through {@link proseLines} rather than scanning the raw text: a docs page
+ * about authoring is mostly ```svelte samples that open with a `<script>`, and
+ * those are code being displayed, not code the page runs.
+ */
+export function* scriptBlocks(text) {
+    const prose = [...proseLines(splitFrontmatter(text).body)].join('\n');
+    for (const match of prose.matchAll(SCRIPT_BLOCK))
+        yield match[1];
+}

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

@@ -31,6 +31,10 @@ export interface DocsmithViteOptions {
      * 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).
+     *
+     * @experimental Outside the 1.0 stability promise. May change in a minor
+     * until authors have used versioning for real. An archive freezes content,
+     * not dependencies.
      */
     versions?: DocsVersions;
 }

package/dist/buildtime/vite/index.js

@@ -78,7 +78,10 @@ function contentIndexPlugin(options) {
     // `dev` leaves the dates as they were until the server restarts.
     let dates;
     const trackedDates = () => (dates ??= commitDates(contentDir, (reason) => {
-        console.warn(`[svelte-docsmith] could not read commit dates under ${contentDir}\n` +
+        // Truncation and shallow clones both refuse dates deliberately; the
+        // reason line says which. "Could not read" would misframe a shallow
+        // skip as a hard failure.
+        console.warn(`[svelte-docsmith] skipping git-derived page dates under ${contentDir}\n` +
             `  ${reason}\n` +
             `  Pages will render without a last-updated date, and sitemap entries without \`lastmod\`.`);
     }));

package/dist/components/markdown/pre.svelte

@@ -98,7 +98,7 @@
 		{/if}
 
 		<pre
-			class="not-prose shiki max-h-[32rem] flex shrink"
+			class="docsmith-code not-prose shiki max-h-[32rem] flex shrink"
 			class:docsmith-line-numbers={lineNumbers}
 			style={lineNumbers && startLine !== 1 ? `--docsmith-line-start: ${startLine - 1}` : undefined}
 			use:clipboard.readText>
@@ -113,8 +113,17 @@
 	 * published package, where the consumer's Tailwind theme context isn't
 	 * available to resolve @apply (Tailwind v4 compiles scoped styles in
 	 * isolation).
+	 *
+	 * Shiki's markup arrives through `{@html}`, so Svelte cannot scope these for
+	 * us and they have to be global. Every one is therefore anchored on
+	 * `pre.docsmith-code`, the class this component puts on its own element.
+	 * Anchoring on the bare element instead would restyle every code block on
+	 * the page, including ones this component never rendered — and since a
+	 * route's CSS only arrives when that route loads (SvelteKit preloads on
+	 * link hover), the restyle would land mid-session and shift the layout
+	 * under the pointer.
 	 */
-	:global(pre code) {
+	:global(pre.docsmith-code code) {
 		display: block;
 		flex-grow: 1;
 		height: 100%;
@@ -122,7 +131,7 @@
 		padding-block: 1rem;
 	}
 
-	:global(pre span.line) {
+	:global(pre.docsmith-code span.line) {
 		display: inline-block;
 		width: 100%;
 		padding-inline: 1rem;
@@ -149,15 +158,15 @@
 	   A CSS counter on Shiki's existing per-line spans, so numbering adds no DOM
 	   and stays out of the text the copy button reads. `--docsmith-line-start`
 	   offsets the counter for a snippet lifted out of a larger file. */
-	:global(pre.docsmith-line-numbers code) {
+	:global(pre.docsmith-code.docsmith-line-numbers code) {
 		counter-reset: docsmith-line var(--docsmith-line-start, 0);
 	}
-	:global(pre.docsmith-line-numbers span.line) {
+	:global(pre.docsmith-code.docsmith-line-numbers span.line) {
 		counter-increment: docsmith-line;
 		position: relative;
 		padding-inline-start: 3.2rem;
 	}
-	:global(pre.docsmith-line-numbers span.line::before) {
+	:global(pre.docsmith-code.docsmith-line-numbers span.line::before) {
 		content: counter(docsmith-line);
 		position: absolute;
 		left: 0;
@@ -169,19 +178,19 @@
 		user-select: none;
 	}
 	/* The diff gutter glyph would collide with the number, so shift it over. */
-	:global(pre.docsmith-line-numbers span.line.diff::before) {
+	:global(pre.docsmith-code.docsmith-line-numbers span.line.diff::before) {
 		content: counter(docsmith-line);
 	}
-	:global(pre.docsmith-line-numbers span.line.diff::after) {
+	:global(pre.docsmith-code.docsmith-line-numbers span.line.diff::after) {
 		position: absolute;
 		left: 2.7rem;
 		font-weight: 600;
 	}
-	:global(pre.docsmith-line-numbers span.line.diff.add::after) {
+	:global(pre.docsmith-code.docsmith-line-numbers span.line.diff.add::after) {
 		content: '+';
 		color: oklch(0.6 0.15 150);
 	}
-	:global(pre.docsmith-line-numbers span.line.diff.remove::after) {
+	:global(pre.docsmith-code.docsmith-line-numbers span.line.diff.remove::after) {
 		content: '−';
 		color: oklch(0.58 0.19 25);
 	}
@@ -193,76 +202,76 @@
 	   the code background via color-mix. */
 
 	/* --- Line highlight (// [!code highlight] and {1,3} meta) --- */
-	:global(pre span.line.highlighted) {
+	:global(pre.docsmith-code span.line.highlighted) {
 		background: color-mix(in oklch, var(--primary) 12%, transparent);
 	}
-	:global(.dark pre span.line.highlighted) {
+	:global(.dark pre.docsmith-code span.line.highlighted) {
 		background: color-mix(in oklch, var(--primary) 20%, transparent);
 	}
 
 	/* --- Diff (// [!code ++] / [!code --]) with +/- gutter glyphs --- */
-	:global(pre span.line.diff) {
+	:global(pre.docsmith-code span.line.diff) {
 		position: relative;
 	}
-	:global(pre span.line.diff.add) {
+	:global(pre.docsmith-code span.line.diff.add) {
 		background: color-mix(in oklch, oklch(0.7 0.16 150) 15%, transparent);
 	}
-	:global(pre span.line.diff.remove) {
+	:global(pre.docsmith-code span.line.diff.remove) {
 		background: color-mix(in oklch, oklch(0.62 0.2 25) 14%, transparent);
 	}
-	:global(.dark pre span.line.diff.add) {
+	:global(.dark pre.docsmith-code span.line.diff.add) {
 		background: color-mix(in oklch, oklch(0.7 0.16 150) 22%, transparent);
 	}
-	:global(.dark pre span.line.diff.remove) {
+	:global(.dark pre.docsmith-code span.line.diff.remove) {
 		background: color-mix(in oklch, oklch(0.62 0.2 25) 22%, transparent);
 	}
-	:global(pre span.line.diff::before) {
+	:global(pre.docsmith-code span.line.diff::before) {
 		position: absolute;
 		left: 0.45rem;
 		font-weight: 600;
 	}
-	:global(pre span.line.diff.add::before) {
+	:global(pre.docsmith-code span.line.diff.add::before) {
 		content: '+';
 		color: oklch(0.6 0.15 150);
 	}
-	:global(pre span.line.diff.remove::before) {
+	:global(pre.docsmith-code span.line.diff.remove::before) {
 		content: '−';
 		color: oklch(0.58 0.19 25);
 	}
-	:global(.dark pre span.line.diff.add::before) {
+	:global(.dark pre.docsmith-code span.line.diff.add::before) {
 		color: oklch(0.78 0.17 150);
 	}
-	:global(.dark pre span.line.diff.remove::before) {
+	:global(.dark pre.docsmith-code span.line.diff.remove::before) {
 		color: oklch(0.72 0.18 25);
 	}
 
 	/* --- Error / warning severity (// [!code error] / [!code warning]).
 	   No gutter glyph, so they stay distinct from the +/- diff lines. --- */
-	:global(pre span.line.highlighted.error) {
+	:global(pre.docsmith-code span.line.highlighted.error) {
 		background: color-mix(in oklch, oklch(0.62 0.2 25) 18%, transparent);
 	}
-	:global(pre span.line.highlighted.warning) {
+	:global(pre.docsmith-code span.line.highlighted.warning) {
 		background: color-mix(in oklch, oklch(0.8 0.13 85) 22%, transparent);
 	}
-	:global(.dark pre span.line.highlighted.error) {
+	:global(.dark pre.docsmith-code span.line.highlighted.error) {
 		background: color-mix(in oklch, oklch(0.62 0.2 25) 26%, transparent);
 	}
-	:global(.dark pre span.line.highlighted.warning) {
+	:global(.dark pre.docsmith-code span.line.highlighted.warning) {
 		background: color-mix(in oklch, oklch(0.8 0.13 85) 20%, transparent);
 	}
 
 	/* --- Focus (// [!code focus]): dim the other lines and restore on hover.
 	   A clean opacity fade reads calmer than a muddy blur. `:has` recreates
 	   Shiki's stripped container flag from the line classes alone. --- */
-	:global(pre code:has(span.line.focused) span.line:not(.focused)) {
+	:global(pre.docsmith-code code:has(span.line.focused) span.line:not(.focused)) {
 		opacity: 0.42;
 		transition: opacity 0.25s ease;
 	}
-	:global(pre:hover code:has(span.line.focused) span.line:not(.focused)) {
+	:global(pre.docsmith-code:hover code:has(span.line.focused) span.line:not(.focused)) {
 		opacity: 1;
 	}
 	@media (prefers-reduced-motion: reduce) {
-		:global(pre code:has(span.line.focused) span.line:not(.focused)) {
+		:global(pre.docsmith-code code:has(span.line.focused) span.line:not(.focused)) {
 			transition: none;
 		}
 	}
@@ -273,11 +282,11 @@
 	   inspectable; the popup is a hidden sibling revealed on hover. `unclipPopups`
 	   then promotes it to fixed positioning so the code block's scrolling does not
 	   clip it — see the comment there. */
-	:global(pre .twoslash-hover) {
+	:global(pre.docsmith-code .twoslash-hover) {
 		position: relative;
 		border-bottom: 1px dotted color-mix(in oklch, var(--muted-foreground) 55%, transparent);
 	}
-	:global(pre .twoslash-popup-container) {
+	:global(pre.docsmith-code .twoslash-popup-container) {
 		position: absolute;
 		z-index: 40;
 		display: none;
@@ -298,11 +307,11 @@
 		font-size: 0.85em;
 		line-height: 1.5;
 	}
-	:global(pre .twoslash-hover:hover .twoslash-popup-container) {
+	:global(pre.docsmith-code .twoslash-hover:hover .twoslash-popup-container) {
 		display: block;
 	}
 	/* The signature keeps Shiki's own colours and monospace. */
-	:global(pre .twoslash-popup-code) {
+	:global(pre.docsmith-code .twoslash-popup-code) {
 		display: block;
 		font-family: var(--font-mono, ui-monospace, monospace);
 		white-space: pre-wrap;
@@ -311,7 +320,7 @@
 	/* Prose, by contrast, is prose. Inside a <pre> it would otherwise inherit
 	   monospace and whatever token colour the hovered span happened to carry,
 	   which reads as more code rather than an explanation of it. */
-	:global(pre .twoslash-popup-docs) {
+	:global(pre.docsmith-code .twoslash-popup-docs) {
 		/* The dark-theme swap repaints every span inside `.shiki` with
 		   `--shiki-dark`, which these spans inherit from whichever token was
 		   hovered — so docs took on the colour of the word above them. Redefining
@@ -330,20 +339,20 @@
 
 	/* Each @param is its own line: the tags are inline spans, so without this
 	   they run together into one paragraph. */
-	:global(pre .twoslash-popup-docs-tags) {
+	:global(pre.docsmith-code .twoslash-popup-docs-tags) {
 		display: flex;
 		flex-direction: column;
 		gap: 0.35rem;
 	}
-	:global(pre .twoslash-popup-docs-tag) {
+	:global(pre.docsmith-code .twoslash-popup-docs-tag) {
 		display: block;
 	}
-	:global(pre .twoslash-popup-docs-tag-value) {
+	:global(pre.docsmith-code .twoslash-popup-docs-tag-value) {
 		--shiki-dark: var(--muted-foreground);
 		color: var(--muted-foreground);
 	}
 	/* And the tag name needs a gap, or it reads as "@paramcallbackfn". */
-	:global(pre .twoslash-popup-docs-tag-name) {
+	:global(pre.docsmith-code .twoslash-popup-docs-tag-name) {
 		--shiki-dark: var(--primary);
 		margin-right: 0.4em;
 		font-family: var(--font-mono, ui-monospace, monospace);
@@ -351,18 +360,18 @@
 		color: var(--primary);
 	}
 	/* A snippet that deliberately shows an error (// @errors:) marks the line. */
-	:global(pre .twoslash-error) {
+	:global(pre.docsmith-code .twoslash-error) {
 		background: color-mix(in oklch, oklch(0.62 0.2 25) 14%, transparent);
 	}
 
 	/* --- Word highlight (// [!code word:name]): a primary-tinted inline pill --- */
-	:global(pre .highlighted-word) {
+	:global(pre.docsmith-code .highlighted-word) {
 		border-radius: 0.3rem;
 		padding: 0.1rem 0.3rem;
 		background: color-mix(in oklch, var(--primary) 16%, transparent);
 		box-shadow: 0 0 0 1px color-mix(in oklch, var(--primary) 35%, transparent);
 	}
-	:global(.dark pre .highlighted-word) {
+	:global(.dark pre.docsmith-code .highlighted-word) {
 		background: color-mix(in oklch, var(--primary) 24%, transparent);
 	}
 </style>

package/dist/core/content.d.ts

@@ -25,9 +25,11 @@ export type DocsContentItem = {
     sourcePath?: string;
     /**
      * The day (`YYYY-MM-DD`) the page's source file last changed, from git, or
-     * from the page's own `lastUpdated` frontmatter when it has one. A calendar
-     * day rather than a timestamp: it is rendered as a UTC day, so it reads the
-     * same for every reader and matches on the server and the client.
+     * from the page's own `lastUpdated` frontmatter when it has one. Absent when
+     * neither source supplies a day — including on a shallow clone, where git
+     * dates would be wrong. A calendar day rather than a timestamp: it is
+     * rendered as a UTC day, so it reads the same for every reader and matches
+     * on the server and the client.
      */
     lastUpdated?: string;
     /** Estimated reading time in whole minutes (at ~200 wpm), min 1. */

package/dist/core/version.d.ts

@@ -7,9 +7,18 @@
  * 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.
+ *
+ * **Experimental.** The versioning API sits outside the 1.0 stability promise
+ * and may change in a minor until authors have used it for real. An archive
+ * freezes content, not dependencies — see
+ * `docs/adr/0005-an-archive-freezes-content-not-dependencies.md`.
  */
 import type { DocsContentItem } from './content.js';
-/** One documentation version, declared in the `docsmith()` vite plugin. */
+/**
+ * One documentation version, declared in the `docsmith()` vite plugin.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor.
+ */
 export type DocsVersion = {
     /** Stable id. Also the URL/directory segment for an archived version. */
     id: string;
@@ -23,12 +32,22 @@ export type DocsVersion = {
  * 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).
+ *
+ * Freezes content, not dependencies: prose, samples and URLs stay that
+ * version's, while imports keep resolving to whatever the app has installed.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export type DocsVersions = {
     current: DocsVersion;
     archived?: DocsVersion[];
 };
-/** A {@link DocsVersion} with the URL fields the runtime needs, computed at build time. */
+/**
+ * A {@link DocsVersion} with the URL fields the runtime needs, computed at build time.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor.
+ */
 export type ResolvedVersion = DocsVersion & {
     /** Absolute URL base: the docs root for `current`, `/docs/<id>` for an archive. */
     basePath: string;
@@ -98,6 +117,9 @@ export declare function currentVersion(versions: ResolvedVersion[]): ResolvedVer
  * 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`.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export declare function currentOnly<T extends {
     version?: string;

package/dist/core/version.js

@@ -153,6 +153,9 @@ export function currentVersion(versions) {
  * 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`.
+ *
+ * @experimental Outside the 1.0 stability promise. May change in a minor until
+ * authors have used versioning for real.
  */
 export function currentOnly(items, versions) {
     const current = currentVersion(versions);

package/dist/index.js

@@ -31,10 +31,12 @@ export { default as CTA } from './components/landing/cta.svelte';
 export { default as Action } from './components/landing/action.svelte';
 // Config
 export { defineConfig } from './core/index.js';
-// Versioned docs. Declare `versions` in the `docsmith()` vite plugin; the
-// resolved manifest is exported from `svelte-docsmith/content` and passed to
-// `DocsShell`. `currentOnly` scopes sitemap.xml / llms.txt to the current
-// version, so archived releases don't compete with it in search results.
+// Versioned docs (experimental — outside the 1.0 stability promise). Declare
+// `versions` in the `docsmith()` vite plugin; the resolved manifest is exported
+// from `svelte-docsmith/content` and passed to `DocsShell`. `currentOnly`
+// scopes sitemap.xml / llms.txt to the current version, so archived releases
+// don't compete with it in search results. An archive freezes content, not
+// dependencies.
 export { currentOnly } from './core/index.js';
 // Search engine (framework-agnostic; for building a custom search UI over the
 // generated `svelte-docsmith/search` index)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-docsmith",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "A framework for building beautiful documentation sites with Svelte.",
   "author": {
     "name": "George Daskalakis",
@@ -66,7 +66,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/geodask/svelte-docsmith.git"
+    "url": "git+https://github.com/geodask/svelte-docsmith.git"
   },
   "license": "MIT",
   "peerDependencies": {