svelte-docsmith 0.8.0 → 0.10.0

package/bin/svelte-docsmith.mjs

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

package/dist/buildtime/archive.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The pure text transforms behind `svelte-docsmith archive-version`. Archiving
+ * copies the docs root into a frozen version folder, and a verbatim copy gets
+ * two things wrong: its links keep resolving to the current docs, and every page
+ * looks like it changed on the day the archive was made. These fix both.
+ *
+ * Kept here rather than in `bin/` so they are typechecked and unit-tested; the
+ * CLI is a thin wrapper over them. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
+ */
+/** Route files at the docs root that an archive nested inside it already inherits. */
+export declare function isInheritedRouteFile(name: string): boolean;
+/**
+ * Point a page's docs links at the archive it is being copied into. An absolute
+ * link like `](/docs/theming)` resolves to the *current* docs forever, so
+ * without this an archive silently walks readers into newer content.
+ *
+ * Links already targeting a version folder are left alone, as are links inside
+ * fenced code, which are sample code rather than navigation.
+ */
+export declare function rewriteDocsLinks(text: string, options: {
+    docsBase: string;
+    versionId: string;
+    archivedIds?: Iterable<string>;
+}): string;
+/**
+ * Write a page's real last-updated date into its frontmatter. The collector
+ * prefers frontmatter over the git date, so an archive keeps the date each page
+ * was actually accurate on instead of the day the archive was created. Leaves an
+ * existing `lastUpdated` and any page without frontmatter alone.
+ */
+export declare function freezeLastUpdated(text: string, date: string | undefined): string;

package/dist/buildtime/archive.js

@@ -0,0 +1,50 @@
+/**
+ * The pure text transforms behind `svelte-docsmith archive-version`. Archiving
+ * copies the docs root into a frozen version folder, and a verbatim copy gets
+ * two things wrong: its links keep resolving to the current docs, and every page
+ * looks like it changed on the day the archive was made. These fix both.
+ *
+ * Kept here rather than in `bin/` so they are typechecked and unit-tested; the
+ * CLI is a thin wrapper over them. See `docs/adr/0002-archives-are-rewritten-source-copies.md`.
+ */
+import { outsideCodeFences, withFrontmatter } from './markdown-source.js';
+/** Route files at the docs root that an archive nested inside it already inherits. */
+export function isInheritedRouteFile(name) {
+    return /^\+(layout|error)\./.test(name);
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/**
+ * Point a page's docs links at the archive it is being copied into. An absolute
+ * link like `](/docs/theming)` resolves to the *current* docs forever, so
+ * without this an archive silently walks readers into newer content.
+ *
+ * Links already targeting a version folder are left alone, as are links inside
+ * fenced code, which are sample code rather than navigation.
+ */
+export function rewriteDocsLinks(text, options) {
+    const { docsBase, versionId } = options;
+    // Never double-prefix: skip links into an existing archive, and into the one
+    // being created (a page may already point at the id we're about to write).
+    const skip = new Set([...(options.archivedIds ?? []), versionId]);
+    const pattern = new RegExp(`(\\]\\(|href="|href='|\\]:[ \\t]+)(${escapeRe(docsBase)})([^)"'\\s]*)`, 'g');
+    return outsideCodeFences(text, (chunk) => chunk.replace(pattern, (match, prefix, base, rest) => {
+        // Guard the segment boundary: `/docsmith` must not become `/docs/v1mith`.
+        if (rest && !/^[/#?]/.test(rest))
+            return match;
+        const firstSegment = rest.startsWith('/') ? rest.slice(1).split(/[/#?]/)[0] : '';
+        if (firstSegment && skip.has(firstSegment))
+            return match;
+        return `${prefix}${base}/${versionId}${rest}`;
+    }));
+}
+/**
+ * Write a page's real last-updated date into its frontmatter. The collector
+ * prefers frontmatter over the git date, so an archive keeps the date each page
+ * was actually accurate on instead of the day the archive was created. Leaves an
+ * existing `lastUpdated` and any page without frontmatter alone.
+ */
+export function freezeLastUpdated(text, date) {
+    if (!date)
+        return text;
+    return withFrontmatter(text, (front) => /^lastUpdated:/m.test(front) ? front : `${front}\nlastUpdated: '${date}'`);
+}

package/dist/buildtime/changelog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Parse a Changesets-generated `CHANGELOG.md` into structured releases.
+ *
+ * The shape Changesets writes is stable:
+ *
+ *     # package-name
+ *
+ *     ## 0.8.0
+ *
+ *     ### Minor Changes
+ *
+ *     - 4a1b3d4: Add an announcement bar. …
+ *
+ *       A second paragraph, indented two spaces.
+ *
+ * Parsing that rather than asking authors to write release notes twice means
+ * the changelog can never fall behind what actually shipped.
+ */
+import type { ChangelogRelease } from '../core/changelog.js';
+export declare function parseChangelog(markdown: string): ChangelogRelease[];

package/dist/buildtime/changelog.js

@@ -0,0 +1,74 @@
+/** `- <7-or-more hex chars>: ` prefix that Changesets puts on each entry. */
+const COMMIT_PREFIX = /^([-*])\s+[0-9a-f]{7,40}:\s*/;
+/** Strip the leading `- ` (and any commit hash) from an entry's first line. */
+function stripBullet(line) {
+    const withoutHash = line.replace(COMMIT_PREFIX, '');
+    if (withoutHash !== line)
+        return withoutHash;
+    return line.replace(/^[-*]\s+/, '');
+}
+/**
+ * De-indent an entry's continuation lines. Changesets indents them by two
+ * spaces to keep them inside the list item; leaving that in would render them
+ * as code blocks.
+ */
+function dedent(lines) {
+    return lines
+        .map((line) => (line.startsWith('  ') ? line.slice(2) : line))
+        .join('\n')
+        .trim();
+}
+export function parseChangelog(markdown) {
+    const lines = markdown.split(/\r?\n/);
+    const releases = [];
+    let release;
+    let group;
+    let entry;
+    const flushEntry = () => {
+        if (entry && group) {
+            const text = dedent(entry);
+            if (text)
+                group.items.push(text);
+        }
+        entry = undefined;
+    };
+    const flushGroup = () => {
+        flushEntry();
+        if (group && release && group.items.length > 0)
+            release.groups.push(group);
+        group = undefined;
+    };
+    const flushRelease = () => {
+        flushGroup();
+        if (release)
+            releases.push(release);
+        release = undefined;
+    };
+    for (const line of lines) {
+        const version = /^##\s+(?!#)(.+?)\s*$/.exec(line);
+        if (version) {
+            flushRelease();
+            release = { version: version[1].trim(), groups: [] };
+            continue;
+        }
+        const heading = /^###\s+(.+?)\s*$/.exec(line);
+        if (heading && release) {
+            flushGroup();
+            group = { kind: heading[1].trim(), items: [] };
+            continue;
+        }
+        if (!group)
+            continue;
+        // A new bullet at column zero starts an entry; anything else continues the
+        // current one, which is how multi-paragraph changesets survive intact.
+        if (/^[-*]\s+/.test(line)) {
+            flushEntry();
+            entry = [stripBullet(line)];
+        }
+        else if (entry) {
+            entry.push(line);
+        }
+    }
+    flushRelease();
+    return releases;
+}

package/dist/buildtime/fence-meta.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Parse the metadata that follows a code fence's language:
+ *
+ * ```ts title="vite.config.ts" showLineNumbers startLine=12
+ *
+ * mdsvex hands this string to the highlighter as its third argument, so no
+ * extra plumbing is needed to read it. Unknown entries are ignored rather than
+ * rejected, so a fence never fails a build over an unrecognised flag.
+ */
+export type FenceMeta = {
+    /** Filename or caption shown above the block. */
+    title?: string;
+    /** Whether to number the lines. `undefined` means "use the global default". */
+    lineNumbers?: boolean;
+    /** First line's number, for a snippet lifted out of a larger file. */
+    startLine?: number;
+};
+export declare function parseFenceMeta(meta?: string | null): FenceMeta;
+/** Whether a fence opts into Twoslash: ```ts twoslash */
+export declare function hasTwoslash(meta?: string | null): boolean;

package/dist/buildtime/fence-meta.js

@@ -0,0 +1,48 @@
+/**
+ * Parse the metadata that follows a code fence's language:
+ *
+ * ```ts title="vite.config.ts" showLineNumbers startLine=12
+ *
+ * mdsvex hands this string to the highlighter as its third argument, so no
+ * extra plumbing is needed to read it. Unknown entries are ignored rather than
+ * rejected, so a fence never fails a build over an unrecognised flag.
+ */
+/** `title="a b"`, `title='a b'`, or `title=a` (unquoted values stop at a space). */
+const KEY_VALUE = /(\w+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g;
+export function parseFenceMeta(meta) {
+    const result = {};
+    if (!meta)
+        return result;
+    for (const match of meta.matchAll(KEY_VALUE)) {
+        const key = match[1];
+        const value = match[2] ?? match[3] ?? match[4] ?? '';
+        if (key === 'title')
+            result.title = value;
+        else if (key === 'startLine') {
+            const parsed = Number.parseInt(value, 10);
+            // A non-numeric or nonsensical startLine is ignored: numbering from an
+            // accidental NaN is worse than numbering from 1.
+            if (Number.isFinite(parsed) && parsed > 0)
+                result.startLine = parsed;
+        }
+        else if (key === 'showLineNumbers' || key === 'lineNumbers') {
+            result.lineNumbers = value !== 'false';
+        }
+    }
+    // Bare flags, e.g. ```ts showLineNumbers
+    const bare = meta.replace(KEY_VALUE, ' ').split(/\s+/).filter(Boolean);
+    if (bare.includes('showLineNumbers') || bare.includes('lineNumbers'))
+        result.lineNumbers = true;
+    if (bare.includes('noLineNumbers'))
+        result.lineNumbers = false;
+    // Numbering from a given line is meaningless without a gutter to show it in.
+    if (result.startLine !== undefined && result.lineNumbers === undefined)
+        result.lineNumbers = true;
+    return result;
+}
+/** Whether a fence opts into Twoslash: ```ts twoslash */
+export function hasTwoslash(meta) {
+    if (!meta)
+        return false;
+    return meta.replace(KEY_VALUE, ' ').split(/\s+/).includes('twoslash');
+}

package/dist/buildtime/markdown-layout.svelte.d.ts

@@ -1,4 +1,7 @@
 export declare const pre: import("svelte").Component<{
+    title?: string;
+    lineNumbers?: boolean;
+    startLine?: number;
     children: Snippet;
 }, {}, "">;
 export declare const code: import("svelte").Component<{

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

@@ -0,0 +1,31 @@
+/**
+ * The structure of a markdown page, as every build-time pass over one needs to
+ * see it: where the frontmatter block ends, and which lines are prose rather
+ * than fenced code.
+ *
+ * Both rules used to be respelled in each pass, and the copies drifted. A fence
+ * scanner that toggles on the marker's first character alone closes a ````
+ * block on the ```svelte nested inside it, which pulls sample code into the
+ * search index and sample headings into the table of contents. Keeping the
+ * rules here means the search index, the table of contents, the LLM output and
+ * the archive rewriter all agree on what a page's prose is.
+ */
+/** A page split at its frontmatter delimiters. */
+export type MarkdownSource = {
+    /** The YAML between the `---` lines, or undefined when the page has none. */
+    frontmatter: string | undefined;
+    /** Everything after the frontmatter block: prose, headings, fenced code, tags. */
+    body: string;
+};
+/** Split a page into its frontmatter and its body. */
+export declare function splitFrontmatter(source: string): MarkdownSource;
+/**
+ * Rewrite a page's frontmatter YAML in place, leaving the delimiters and the
+ * body byte-identical — including their line endings, which a split-and-rejoin
+ * would normalise. A page without frontmatter is returned untouched.
+ */
+export declare function withFrontmatter(source: string, transform: (frontmatter: string) => string): string;
+/** Apply `transform` to a page's prose lines, leaving fenced code untouched. */
+export declare function outsideCodeFences(text: string, transform: (line: string) => string): string;
+/** A page's prose lines, in order, with fenced code and its markers dropped. */
+export declare function proseLines(text: string): Generator<string>;

package/dist/buildtime/markdown-source.js

@@ -0,0 +1,90 @@
+/**
+ * The structure of a markdown page, as every build-time pass over one needs to
+ * see it: where the frontmatter block ends, and which lines are prose rather
+ * than fenced code.
+ *
+ * Both rules used to be respelled in each pass, and the copies drifted. A fence
+ * scanner that toggles on the marker's first character alone closes a ````
+ * block on the ```svelte nested inside it, which pulls sample code into the
+ * search index and sample headings into the table of contents. Keeping the
+ * rules here means the search index, the table of contents, the LLM output and
+ * the archive rewriter all agree on what a page's prose is.
+ */
+/**
+ * A page's frontmatter block: `---` on the first line, through the next line
+ * that starts with `---`. Group 1 is the YAML; the whole match spans the block
+ * including the line break that ends it, so the body starts where it stops.
+ *
+ * Deliberately as loose about the closing delimiter as remark-frontmatter,
+ * which is what mdsvex strips at render time. A stricter rule here would read
+ * a page differently from the renderer: a page mdsvex renders body-only would
+ * keep its frontmatter as prose, or lose the title that puts it in the nav.
+ */
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+/** An opening or closing code fence, indented anywhere on its line. */
+const FENCE = /^\s*(`{3,}|~{3,})/;
+/** Split a page into its frontmatter and its body. */
+export function splitFrontmatter(source) {
+    const match = FRONTMATTER.exec(source);
+    if (!match)
+        return { frontmatter: undefined, body: source };
+    return { frontmatter: match[1], body: source.slice(match[0].length) };
+}
+/**
+ * Rewrite a page's frontmatter YAML in place, leaving the delimiters and the
+ * body byte-identical — including their line endings, which a split-and-rejoin
+ * would normalise. A page without frontmatter is returned untouched.
+ */
+export function withFrontmatter(source, transform) {
+    const match = FRONTMATTER.exec(source);
+    if (!match)
+        return source;
+    const start = match[0].indexOf('\n') + 1;
+    return source.slice(0, start) + transform(match[1]) + source.slice(start + match[1].length);
+}
+/**
+ * A line-by-line scanner for fence state, rather than one regex pairing fences
+ * up, so an indented fence (inside a list item or a component) and a `~~~`
+ * fence are both recognised. Per CommonMark a fence closes only on the same
+ * character, at least as long as the opener, with no info string — so the
+ * ```svelte inside a ```` block opens nothing and closes nothing.
+ *
+ * Returns a predicate that consumes the page's lines in order and answers
+ * whether each one is prose. Fence markers themselves are not.
+ */
+function fenceScanner() {
+    let open;
+    return (line) => {
+        const match = FENCE.exec(line);
+        if (open) {
+            const closes = match &&
+                match[1][0] === open[0] &&
+                match[1].length >= open.length &&
+                !line.slice(match[0].length).trim();
+            if (closes)
+                open = undefined;
+            return false;
+        }
+        if (match) {
+            open = match[1];
+            return false;
+        }
+        return true;
+    };
+}
+/** Apply `transform` to a page's prose lines, leaving fenced code untouched. */
+export function outsideCodeFences(text, transform) {
+    const isProse = fenceScanner();
+    return text
+        .split('\n')
+        .map((line) => (isProse(line) ? transform(line) : line))
+        .join('\n');
+}
+/** A page's prose lines, in order, with fenced code and its markers dropped. */
+export function* proseLines(text) {
+    const isProse = fenceScanner();
+    for (const line of text.split('\n')) {
+        if (isProse(line))
+            yield line;
+    }
+}

package/dist/buildtime/preprocess.d.ts

@@ -22,6 +22,19 @@ export interface DocsmithPreprocessOptions {
     remarkPlugins?: MdsvexOptions['remarkPlugins'];
     /** Extra rehype plugins, appended after docsmith's own (slug, sectionize). */
     rehypePlugins?: MdsvexOptions['rehypePlugins'];
+    /**
+     * Number every code block by default. Per-fence `showLineNumbers` /
+     * `noLineNumbers` override it either way. Default: `false`.
+     */
+    lineNumbers?: boolean;
+    /**
+     * Enable Twoslash on fences that ask for it with ```ts twoslash, adding real
+     * hover types from the TypeScript compiler. Requires the optional peer
+     * dependencies `@shikijs/twoslash`, `twoslash-svelte`, and `typescript`.
+     * A snippet that fails to typecheck falls back to a plain highlight with a
+     * build warning rather than failing the build. Default: `false`.
+     */
+    twoslash?: boolean;
 }
 /**
  * Build the svelte-docsmith preprocessor: mdsvex with Shiki highlighting (via