svelte-docsmith 0.15.0 → 0.16.0

package/README.md

@@ -24,8 +24,11 @@ live table of contents. No per-page wiring, no content collection to configure.
 > 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.
+> archive marker, and the `archive-version` command. Generated props tables:
+> `?props` imports and `PropsTable`'s `of`. The MCP server: `mcpHandler` and the
+> `mcp` config field. Agent markdown: the props tables and example code written
+> into `llms-full.txt` and `.md` pages. They may still change in a minor until
+> authors have used them for real.
 
 ## Install
 
@@ -170,6 +173,35 @@ plugin you already added:
 </LiveExample>
 ```
 
+To type the `?source` import, reference the package's client types once in
+`src/app.d.ts`:
+
+```ts
+/// <reference types="svelte-docsmith/client" />
+```
+
+## Props tables from your types
+
+`PropsTable` can read a component's API straight from its typed `$props()`, so
+the reference can't drift from the code either. Import the component with
+`?props` and pass it to `of`:
+
+```svelte
+<script>
+	import { PropsTable } from 'svelte-docsmith';
+	import buttonProps from '#lib/button.svelte?props';
+</script>
+
+<PropsTable of={buttonProps} />
+```
+
+Types come from the TypeScript checker (an imported `ButtonVariant` alias shows
+its values), descriptions from JSDoc, defaults from the destructuring. Snippets,
+callbacks and `$bindable()` props all get rows, and inherited HTML attributes
+collapse to one line. It needs the optional peers `typescript` and `svelte2tsx`
+(`npm i -D typescript svelte2tsx`). Generated props tables are **experimental**:
+outside the 1.0 promise for now.
+
 ## Batteries included
 
 - **Search.** A ⌘K / Ctrl-K command palette over a build-time full-text index, no
@@ -214,18 +246,19 @@ override the tokens yourself.
 
 ## What's exported
 
-| 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                                                                                                                                                                                                                 |
+| Entry point                    | What it is                                                                                                                                                                                                                                             |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `svelte-docsmith`              | Components (`DocsShell`, `Changelog`, landing sections, `LiveExample`, `Callout`, …), `defineConfig`, `createSearchEngine`, `generateSitemap` / `generateLlmsTxt` / `generateLlmsFullTxt` / `generateFeed`, `mcpHandler`, `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` / `?props` transforms (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 agent markdown 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/client`       | ambient types for `?source` and `?props` imports (reference it from `src/app.d.ts`)                                                                                                                                                                    |
+| `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.

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

@@ -27,6 +27,17 @@ export declare function splitFrontmatter(source: string): MarkdownSource;
 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;
+/**
+ * Apply `transform` to each run of consecutive prose lines, leaving fenced code
+ * and its markers untouched. For rewrites that span lines, such as a component
+ * tag with children, which {@link outsideCodeFences} would see a line at a time.
+ *
+ * With `setupBlocks`, each top-level `<script>`/`<style>` block stays whole
+ * inside one run, even when its code has a fence-like line.
+ */
+export declare function outsideCodeFenceRuns(text: string, transform: (prose: string) => string, options?: {
+    setupBlocks?: boolean;
+}): 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

@@ -23,6 +23,8 @@
 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,})/;
+/** The open tag of a `<script>` or `<style>` block, starting a line as HTML may. */
+const SETUP_BLOCK_OPEN = /^ {0,3}<(script|style)(?=[\s>]|$)/i;
 /** Split a page into its frontmatter and its body. */
 export function splitFrontmatter(source) {
     const match = FRONTMATTER.exec(source);
@@ -51,10 +53,20 @@ export function withFrontmatter(source, transform) {
  *
  * Returns a predicate that consumes the page's lines in order and answers
  * whether each one is prose. Fence markers themselves are not.
+ *
+ * With `setupBlocks`, a `<script>` or `<style>` block starting a prose line is
+ * prose through its closing tag, as CommonMark reads such an HTML block, so a
+ * fence-like line in its code (a ``` in a template literal) opens nothing.
  */
-function fenceScanner() {
+function fenceScanner({ setupBlocks = false } = {}) {
     let open;
+    let setupClose;
     return (line) => {
+        if (setupClose) {
+            if (setupClose.test(line))
+                setupClose = undefined;
+            return true;
+        }
         const match = FENCE.exec(line);
         if (open) {
             const closes = match &&
@@ -69,6 +81,12 @@ function fenceScanner() {
             open = match[1];
             return false;
         }
+        const setup = setupBlocks ? SETUP_BLOCK_OPEN.exec(line) : null;
+        if (setup) {
+            const close = new RegExp(`</${setup[1]}>`, 'i');
+            if (!close.test(line.slice(setup[0].length)))
+                setupClose = close;
+        }
         return true;
     };
 }
@@ -80,6 +98,35 @@ export function outsideCodeFences(text, transform) {
         .map((line) => (isProse(line) ? transform(line) : line))
         .join('\n');
 }
+/**
+ * Apply `transform` to each run of consecutive prose lines, leaving fenced code
+ * and its markers untouched. For rewrites that span lines, such as a component
+ * tag with children, which {@link outsideCodeFences} would see a line at a time.
+ *
+ * With `setupBlocks`, each top-level `<script>`/`<style>` block stays whole
+ * inside one run, even when its code has a fence-like line.
+ */
+export function outsideCodeFenceRuns(text, transform, options = {}) {
+    const isProse = fenceScanner(options);
+    const out = [];
+    let run = [];
+    const flush = () => {
+        if (run.length)
+            out.push(transform(run.join('\n')));
+        run = [];
+    };
+    for (const line of text.split('\n')) {
+        if (isProse(line)) {
+            run.push(line);
+        }
+        else {
+            flush();
+            out.push(line);
+        }
+    }
+    flush();
+    return out.join('\n');
+}
 /** A page's prose lines, in order, with fenced code and its markers dropped. */
 export function* proseLines(text) {
     const isProse = fenceScanner();

package/dist/buildtime/props/extract.d.ts

@@ -1,6 +1,12 @@
 import type { ExtractedProps } from '../../core/extracted-props.js';
 export interface ExtractResult {
+    /** What `<PropsTable of={…}>` renders: descriptions as inline HTML. */
     props: ExtractedProps;
+    /**
+     * The same props with descriptions and deprecation notes as the JSDoc's own
+     * markdown, for agent markdown.
+     */
+    markdown: ExtractedProps;
     warnings: string[];
     /** Files whose changes should re-extract this component. */
     watchFiles: string[];

package/dist/buildtime/props/extract.js

@@ -78,18 +78,33 @@ export function createPropsExtractor(options) {
             warn('reading a published package file. Published components usually have their ' +
                 'types stripped, so point the props import at the source instead.');
         }
+        // Rows are built once, with JSDoc as markdown; the rendered table's copy
+        // differs only in turning that markdown into HTML.
+        const done = (watchFiles) => ({
+            props: {
+                ...extracted,
+                props: extracted.props.map((prop) => clean({
+                    ...prop,
+                    deprecated: prop.deprecated === undefined ? undefined : renderMarkdown(prop.deprecated),
+                    description: prop.description ? renderMarkdown(prop.description) : undefined
+                }))
+            },
+            markdown: extracted,
+            warnings,
+            watchFiles
+        });
         let parsed;
         try {
             parsed = parseComponent(fs.readFileSync(file, 'utf-8'), file);
         }
         catch (error) {
             warn(`could not parse the component (${message(error)}).`);
-            return { props: extracted, warnings, watchFiles: [file] };
+            return done([file]);
         }
         extracted.typeParameters = parsed.typeParameters;
         if (!parsed.hasProps) {
             warn('no `$props()` found, so the props table is empty.');
-            return { props: extracted, warnings, watchFiles: [file] };
+            return done([file]);
         }
         let typed;
         if (parsed.typed) {
@@ -118,8 +133,8 @@ export function createPropsExtractor(options) {
                     default: fallback,
                     required: !prop.optional && fallback === undefined,
                     bindable: destructured?.bindable ?? false,
-                    deprecated: prop.deprecated === undefined ? undefined : renderMarkdown(prop.deprecated),
-                    description: prop.description ? renderMarkdown(prop.description) : undefined
+                    deprecated: prop.deprecated,
+                    description: prop.description
                 }));
             }
             extracted.inherited = typed.inherited;
@@ -129,11 +144,7 @@ export function createPropsExtractor(options) {
                 extracted.props.push(clean({ name: d.name, default: d.default, required: false, bindable: d.bindable }));
             }
         }
-        return {
-            props: extracted,
-            warnings,
-            watchFiles: [...new Set([file, ...(typed?.files ?? [])])]
-        };
+        return done([...new Set([file, ...(typed?.files ?? [])])]);
     }
 }
 /** `file-tree-item.svelte` → `FileTreeItem`. */

package/dist/buildtime/vite/agent-markdown.d.ts

@@ -0,0 +1,43 @@
+import { type ExtractedProps } from '../../core/extracted-props.js';
+import type { SourcePage } from './pages.js';
+/** Which build-time transform a page import goes through. */
+export type DocImportKind = 'source' | 'props';
+/** One `*.svelte?source` or `*.svelte?props` import in a page's `<script>`. */
+export type DocImport = {
+    kind: DocImportKind;
+    /** The specifier as written, query included, for messages. */
+    specifier: string;
+    /** The component file it resolves to, or `undefined` when it did not resolve. */
+    file: string | undefined;
+};
+/**
+ * Resolve a specifier (query stripped) from a page, the way Vite resolves the
+ * page's own imports: the app's aliases (`$lib`, `#lib`) included. Returns the
+ * resolved file, or `undefined` when nothing resolves it.
+ */
+export type ResolveImport = (specifier: string, importer: string) => Promise<string | undefined>;
+/** What building agent markdown needs from the plugin. */
+export type AgentMarkdownHost = {
+    resolve: ResolveImport;
+    /** Record a file the agent markdown was read from, so editing it rebuilds the index. */
+    watch(file: string): void;
+    warn(message: string): void;
+    /**
+     * A component's props as the `?props` transform extracts them, with
+     * descriptions as markdown. The host watches the files they were read from
+     * and passes on extraction warnings.
+     */
+    props(file: string): Promise<ExtractedProps>;
+};
+/**
+ * A page's `?source` and `?props` imports, keyed by the local name each binds,
+ * with every specifier resolved from the page. Imports inside fenced code
+ * samples are not the page's, and are skipped.
+ */
+export declare function docImports(page: Pick<SourcePage, 'file' | 'source'>, resolve: ResolveImport): Promise<Map<string, DocImport>>;
+/**
+ * Build the agent markdown rewrite for one page: a function from the page's
+ * markdown, setup blocks stripped, to its agent markdown. `undefined` when the page imports nothing
+ * agent markdown expands, so most pages cost one scan of their script.
+ */
+export declare function agentMarkdownFor(page: SourcePage, host: AgentMarkdownHost): Promise<((content: string) => string) | undefined>;

package/dist/buildtime/vite/agent-markdown.js

@@ -0,0 +1,204 @@
+/**
+ * Agent markdown: a page's markdown as an agent reads it (llms-full.txt, the
+ * `.md` twins, the MCP server). The page as written keeps `<LiveExample
+ * source={…}>` and `<PropsTable of={…}>` as bare tags and their imports are
+ * stripped with the `<script>` block, so an agent would never see the example
+ * code or the component's props. Here each `LiveExample` whose source is a
+ * `?source` import becomes a fenced `svelte` block of the example file's raw
+ * source, and each `PropsTable` whose `of` is a props import becomes a heading
+ * and a markdown table of the same rows the page renders.
+ *
+ * Unlike `./collect.js` this reads the filesystem and resolves imports, so it
+ * runs in the plugin, which hands it Vite's resolver and the props extractor.
+ */
+import fs from 'node:fs';
+import { propsCaption } from '../../core/extracted-props.js';
+import { outsideCodeFenceRuns, scriptBlocks } from '../markdown-source.js';
+import { relativeToCwd } from '../paths.js';
+/** A default import of a `.svelte` file through `?source` or `?props`. */
+const DOC_IMPORT = /\bimport\s+([A-Za-z_$][\w$]*)\s+from\s*(['"])([^'"\n]+?\.svelte)\?(source|props)\2/g;
+/**
+ * A page's `?source` and `?props` imports, keyed by the local name each binds,
+ * with every specifier resolved from the page. Imports inside fenced code
+ * samples are not the page's, and are skipped.
+ */
+export async function docImports(page, resolve) {
+    const imports = new Map();
+    for (const block of scriptBlocks(page.source)) {
+        for (const [, local, , base, kind] of block.matchAll(DOC_IMPORT)) {
+            const file = await resolve(base, page.file);
+            imports.set(local, { kind: kind, specifier: `${base}?${kind}`, file });
+        }
+    }
+    return imports;
+}
+/**
+ * A `<LiveExample …>…</LiveExample>` (or self-closing) tag starting a line.
+ * Group 1 is its indentation, group 2 its attributes; an attribute value in
+ * braces may contain `>`.
+ */
+const LIVE_EXAMPLE = /^([ \t]*)<LiveExample\b((?:[^>{}]|\{[^{}]*\})*?)(?:\/>|>[\s\S]*?<\/LiveExample\s*>)/gm;
+/** `source={name}`, or the `{source}` shorthand. */
+const SOURCE_ATTRIBUTE = /(?:\bsource\s*=\s*\{\s*([A-Za-z_$][\w$]*)\s*\}|\{\s*(source)\s*\})/;
+/** A backtick fence one longer than the longest backtick run in `text`, and at least `min`. */
+function fenceFor(text, min) {
+    const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map(([run]) => run.length));
+    return '`'.repeat(Math.max(min, longest + 1));
+}
+/** `text` with `indent` before each non-empty line. */
+function indented(text, indent) {
+    return text
+        .split('\n')
+        .map((line) => (line ? indent + line : line))
+        .join('\n');
+}
+/** A fenced block of `code`, fenced longer than any backtick run inside it. */
+function fenced(code, lang, indent) {
+    const fence = fenceFor(code, 3);
+    return indented([fence + lang, code, fence].join('\n'), indent);
+}
+/**
+ * Build the agent markdown rewrite for one page: a function from the page's
+ * markdown, setup blocks stripped, to its agent markdown. `undefined` when the page imports nothing
+ * agent markdown expands, so most pages cost one scan of their script.
+ */
+export async function agentMarkdownFor(page, host) {
+    const imports = await docImports(page, host.resolve);
+    if (imports.size === 0)
+        return undefined;
+    // Read up front, so the rewrite itself is synchronous. Props extractions all
+    // start together, so the extractor batches them into one TypeScript update.
+    const sources = new Map();
+    const tables = new Map();
+    await Promise.all([...imports].map(async ([local, entry]) => {
+        // Watched even when it can't be read, so creating or fixing it rebuilds.
+        if (entry.file !== undefined)
+            host.watch(entry.file);
+        if (entry.kind === 'source') {
+            sources.set(local, entry.file === undefined ? undefined : readExample(entry.file));
+        }
+        else {
+            tables.set(local, entry.file === undefined ? undefined : await host.props(entry.file));
+        }
+    }));
+    const keepTag = (tag, local, attribute) => {
+        host.warn(`${relativeToCwd(page.file)}: could not read \`${imports.get(local)?.specifier}\` ` +
+            `for <${tag} ${attribute}={${local}}>, so agent markdown keeps the tag.`);
+    };
+    return (content) => {
+        // The level of the heading a table sits under, carried across code fences.
+        let level = 1;
+        return outsideCodeFenceRuns(content, (prose) => {
+            const levelAt = (offset) => lastHeadingLevel(prose.slice(0, offset)) ?? level;
+            const withTables = prose.replace(PROPS_TABLE, (tag, indent, attributes, offset) => {
+                const match = OF_ATTRIBUTE.exec(attributes);
+                const local = match?.[1] ?? match?.[2];
+                if (local === undefined || !tables.has(local))
+                    return tag;
+                const props = tables.get(local);
+                if (props === undefined) {
+                    keepTag('PropsTable', local, 'of');
+                    return tag;
+                }
+                const title = TITLE_ATTRIBUTE.exec(attributes);
+                const caption = title ? title.slice(1).find((value) => value !== undefined) : undefined;
+                return propsTable(props, caption, Math.min(6, levelAt(offset) + 1), indent);
+            });
+            level = levelAt(prose.length);
+            return withTables.replace(LIVE_EXAMPLE, (tag, indent, attributes) => {
+                const match = SOURCE_ATTRIBUTE.exec(attributes);
+                const local = match?.[1] ?? match?.[2];
+                if (local === undefined || !sources.has(local))
+                    return tag;
+                const code = sources.get(local);
+                if (code === undefined) {
+                    keepTag('LiveExample', local, 'source');
+                    return tag;
+                }
+                return fenced(code, 'svelte', indent);
+            });
+        });
+    };
+}
+/**
+ * A `<PropsTable …/>` or `<PropsTable …>…</PropsTable>` tag starting a line,
+ * grouped like {@link LIVE_EXAMPLE}.
+ */
+const PROPS_TABLE = /^([ \t]*)<PropsTable\b((?:[^>{}]|\{[^{}]*\})*?)(?:\/>|>[\s\S]*?<\/PropsTable\s*>)/gm;
+/** `of={name}`, or the `{of}` shorthand. */
+const OF_ATTRIBUTE = /(?:(?:^|\s)of\s*=\s*\{\s*([A-Za-z_$][\w$]*)\s*\}|\{\s*(of)\s*\})/;
+/** A `title` given as a string literal, quoted or in braces. */
+const TITLE_ATTRIBUTE = /(?:^|\s)title\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*(?:"([^"]*)"|'([^']*)')\s*\})/;
+/** An ATX heading's marker. */
+const HEADING = /^ {0,3}(#{1,6})(?:[ \t]|$)/gm;
+/** The level of the last heading in `prose`, if it has one. */
+function lastHeadingLevel(prose) {
+    return [...prose.matchAll(HEADING)].at(-1)?.[1].length;
+}
+/**
+ * A generated props table as agent markdown: the caption as a heading, then a
+ * `Prop | Type | Default | Description` table with the rows the page renders,
+ * then the inherited attributes summary.
+ */
+function propsTable(props, title, level, indent) {
+    const blocks = [`${'#'.repeat(level)} ${code(title ?? propsCaption(props))}`];
+    if (props.props.length) {
+        blocks.push([
+            '| Prop | Type | Default | Description |',
+            '| --- | --- | --- | --- |',
+            ...props.props.map((prop) => `| ${propCells(prop).join(' | ')} |`)
+        ].join('\n'));
+    }
+    for (const group of props.inherited) {
+        blocks.push(group.kind === 'element'
+            ? `Also accepts every ${code(`<${group.label}>`)} attribute.`
+            : `Also accepts every prop of ${code(group.label)}.`);
+    }
+    if (props.props.length === 0 && props.inherited.length === 0)
+        blocks.push('No props.');
+    return indented(blocks.join('\n\n'), indent);
+}
+/** One row's cells, marked as the rendered row is and escaped for a table. */
+function propCells(prop) {
+    let name = code(prop.required ? prop.name : `${prop.name}?`);
+    if (prop.deprecated !== undefined)
+        name = `~~${name}~~`;
+    const marks = [
+        prop.bindable && '*(bindable)*',
+        prop.deprecated !== undefined && '*(deprecated)*'
+    ];
+    const description = [prop.deprecated && `Deprecated: ${prop.deprecated}`, prop.description]
+        .filter(Boolean)
+        .map((text) => inline(text))
+        .join('<br>');
+    return [
+        [name, ...marks.filter(Boolean)].join(' '),
+        prop.type === undefined ? '' : code(prop.type),
+        prop.default === undefined ? '' : code(prop.default),
+        description
+    ].map((cell) => cell.replaceAll('|', '\\|'));
+}
+/** `text` as a code span on one line, fenced longer than any backtick run in it. */
+function code(text) {
+    const flat = text.replace(/\s*\n\s*/g, ' ');
+    const fence = fenceFor(flat, 1);
+    const pad = flat.startsWith('`') || flat.endsWith('`') ? ' ' : '';
+    return fence + pad + flat + pad + fence;
+}
+/** Markdown on one line: paragraphs joined with `<br><br>`, soft breaks as spaces. */
+function inline(markdown) {
+    return markdown
+        .trim()
+        .split(/\n[ \t]*\n\s*/)
+        .map((paragraph) => paragraph.replace(/\s*\n\s*/g, ' '))
+        .join('<br><br>');
+}
+/** An example file's raw source, as the `?source` transform reads it. */
+function readExample(file) {
+    try {
+        return fs.readFileSync(file, 'utf-8').trimEnd();
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -29,5 +29,8 @@ export declare function searchIndex(pages: SourcePage[], options: IndexOptions):
  * The LLM index: title, section, description, and the full markdown content.
  * Served as the `svelte-docsmith/llms` virtual module and consumed server-side
  * by `llms.txt` / `llms-full.txt` routes, so it never ships to the client.
+ *
+ * `rewrite` turns a page's markdown into agent markdown (see
+ * `./agent-markdown.js`); without it, the content is the page as written.
  */
-export declare function llmsIndex(pages: SourcePage[], options: IndexOptions): LlmsDoc[];
+export declare function llmsIndex(pages: SourcePage[], options: IndexOptions, rewrite?: (content: string, page: SourcePage) => string): LlmsDoc[];

package/dist/buildtime/vite/collect.js

@@ -108,15 +108,18 @@ export function searchIndex(pages, options) {
  * The LLM index: title, section, description, and the full markdown content.
  * Served as the `svelte-docsmith/llms` virtual module and consumed server-side
  * by `llms.txt` / `llms-full.txt` routes, so it never ships to the client.
+ *
+ * `rewrite` turns a page's markdown into agent markdown (see
+ * `./agent-markdown.js`); without it, the content is the page as written.
  */
-export function llmsIndex(pages, options) {
+export function llmsIndex(pages, options, rewrite = (content) => content) {
     return indexedPages(pages, options).map((page) => ({
         path: page.url,
         title: page.title,
         section: sectionKey(page.frontmatter),
         order: readField(page.frontmatter, 'order'),
         description: readField(page.frontmatter, 'description'),
-        content: extractLlmsContent(page.source, page.title),
+        content: rewrite(extractLlmsContent(page.source, page.title), page),
         version: page.version
     }));
 }

package/dist/buildtime/vite/extract.js

@@ -1,8 +1,13 @@
 import GithubSlugger from 'github-slugger';
-import { proseLines, splitFrontmatter } from '../markdown-source.js';
-/** Drop a page's `<script>`/`<style>` blocks: component setup, not content. */
+import { outsideCodeFenceRuns, proseLines, splitFrontmatter } from '../markdown-source.js';
+/**
+ * Drop a page's `<script>`/`<style>` blocks: component setup, not content. One
+ * inside a fenced code sample is part of the sample, and stays. A top-level one
+ * is read whole, so a fence-like line in its code neither splits it nor opens a
+ * fence.
+ */
 function withoutSetupBlocks(body) {
-    return body.replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, '');
+    return outsideCodeFenceRuns(body, (prose) => prose.replace(/<script[\s\S]*?<\/script>/gi, '').replace(/<style[\s\S]*?<\/style>/gi, ''), { setupBlocks: true });
 }
 /** Strip inline markdown so a heading's TOC label is plain text. */
 function stripInlineMarkdown(text) {