@clidoc/vitepress 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Houston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @clidoc/vitepress
+
+[![npm version](https://img.shields.io/npm/v/%40clidoc%2Fvitepress)](https://www.npmjs.com/package/@clidoc/vitepress)
+[![npm downloads](https://img.shields.io/npm/dw/%40clidoc%2Fvitepress)](https://www.npmjs.com/package/@clidoc/vitepress)
+[![CI](https://github.com/bhouston/clidoc/actions/workflows/ci.yml/badge.svg)](https://github.com/bhouston/clidoc/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/bhouston/clidoc/graph/badge.svg)](https://codecov.io/gh/bhouston/clidoc)
+[![Documentation](https://img.shields.io/badge/docs-clidoc.dev-blue)](https://clidoc.dev)
+
+Generate VitePress pages and sidebar entries from an OpenCLI document.
+
+Install the publisher, parser, and VitePress:
+
+```sh
+npm install -D @clidoc/vitepress @clidoc/core vitepress
+```
+
+Export an OpenCLI document from your CLI, for example with
+`mycli docgen --format yaml --output cli.ocs.yaml`.
+
+In `docs/.vitepress/config.mts`, with `cli.ocs.yaml` at the project root:
+
+```ts
+import { defineConfig } from 'vitepress';
+import { parse } from '@clidoc/core';
+import { writeVitePress } from '@clidoc/vitepress';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const document = parse(await readFile(new URL('../../cli.ocs.yaml', import.meta.url), 'utf8'));
+const cliSidebar = await writeVitePress(document, {
+  outputDir: fileURLToPath(new URL('..', import.meta.url)),
+  basePath: '/cli',
+});
+export default defineConfig({
+  themeConfig: { sidebar: [{ text: 'CLI', items: cliSidebar }] },
+});
+```
+
+Keep handwritten pages in `docs/`. With `basePath: '/cli'`, add only the
+generated paths to `.gitignore`:
+
+```gitignore
+docs/cli.md
+docs/cli/commands/
+docs/.clidoc-generated.json
+```
+
+Run `npx vitepress dev docs` to preview the site.
+
+The output contains ordinary Markdown. VitePress's `v-pre` custom container
+keeps CLI-authored Vue expressions literal while still rendering headings,
+links, tables, and fenced code. `basePath` determines both routes and file
+locations below `outputDir`. Regeneration removes only files recorded in
+`.clidoc-generated.json`, leaving hand-written pages intact. On the first run
+after upgrading from OpenCLI, it also removes stale pages listed in
+`.opencli-generated.json` and deletes that legacy manifest.
+
+`<` and `>` outside fenced code blocks and inline code spans are escaped to
+entities, since `v-pre` stops Vue mustache interpolation but not its SFC
+parser's tag scanning; as a result, HTML written in a description renders as
+literal text rather than as markup on VitePress.
+
+Command pages use the synopsis generated by `@clidoc/core`. Required values use
+`<value>`, optional elements use `[element]`, and repeatable elements use `...`.
+The synopsis includes visible command flags and inherited global flags, and its
+angle-bracket placeholders remain literal inside the fenced code block.
+
+Generated command page filenames and sidebar links are stable and based on the
+shared command routes. An ordinary binary-prefixed command such as
+`mycli deploy` produces `cli/commands/deploy.md` and links to
+`/cli/commands/deploy` when `basePath` is `/cli`. Names outside the readable
+route form use a normalized prefix plus a deterministic hash suffix. This keeps
+their URLs stable when unrelated commands are added while avoiding collisions.
+
+## License
+
+MIT. See [LICENSE](../../LICENSE).
+
+## Author
+
+[Ben Houston](https://ben3d.ca), Sponsored by [Land of Assets](https://landofassets.com).

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { type OpenCliDocument } from '@clidoc/core';
+export interface VitePressOptions {
+    /** Site source root. Generated pages live below basePath. */
+    outputDir: string;
+    basePath?: string;
+}
+/** Use in an async VitePress config and assign the result to themeConfig.sidebar. */
+export declare function writeVitePress(document: OpenCliDocument, options: VitePressOptions): Promise<{
+    text: string;
+    link: string;
+}[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA4DD,qFAAqF;AACrF,wBAAsB,cAAc,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB;;;KAqBxF"}

package/dist/index.js

@@ -0,0 +1,86 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { generatePages } from '@clidoc/core';
+/**
+ * VitePress's `v-pre` container stops Vue mustache interpolation but not Vue's
+ * SFC template parser, which still tries to parse tag-shaped text like
+ * `use <profile> to override`. Escape `<`/`>` outside fenced code blocks and
+ * inline code spans so the build never sees an unbalanced "tag".
+ */
+function escapeAngleBrackets(content) {
+    const lines = content.split('\n');
+    let fenceCharacter = '';
+    let fenceLength = 0;
+    return lines
+        .map((line) => {
+        if (fenceLength) {
+            const closing = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
+            if (closing?.[1]?.[0] === fenceCharacter && closing[1].length >= fenceLength) {
+                fenceCharacter = '';
+                fenceLength = 0;
+            }
+            return line;
+        }
+        const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+        if (opening?.[1] && (opening[1][0] === '~' || !opening[2]?.includes('`'))) {
+            fenceCharacter = opening[1][0];
+            fenceLength = opening[1].length;
+            return line;
+        }
+        // Split on inline code spans (backtick runs) and only escape outside them.
+        return line
+            .split(/(`+.*?`+)/)
+            .map((part, index) => (index % 2 === 0 ? part.replace(/</g, '&lt;').replace(/>/g, '&gt;') : part))
+            .join('');
+    })
+        .join('\n');
+}
+const manifestName = '.clidoc-generated.json';
+const legacyManifestName = '.opencli-generated.json';
+function ownedPath(outputDir, name) {
+    const full = resolve(outputDir, name);
+    const rel = relative(outputDir, full);
+    if (!rel || rel.startsWith(`..${sep}`) || rel === '..' || rel.startsWith(sep)) {
+        throw new Error(`Generated filename escapes output directory: ${name}`);
+    }
+    return full;
+}
+async function previousFiles(outputDir, name) {
+    try {
+        const value = JSON.parse(await readFile(join(outputDir, name), 'utf8'));
+        if (!Array.isArray(value))
+            throw new Error('Invalid generated file manifest');
+        return value.filter((entry) => typeof entry === 'string' && entry.endsWith('.md') && !entry.includes('..'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/** Use in an async VitePress config and assign the result to themeConfig.sidebar. */
+export async function writeVitePress(document, options) {
+    const pages = generatePages(document, { basePath: options.basePath });
+    const outputDir = resolve(options.outputDir);
+    await mkdir(outputDir, { recursive: true });
+    const previous = await previousFiles(outputDir, manifestName);
+    const legacy = await previousFiles(outputDir, legacyManifestName);
+    const current = pages.map((page) => `${page.path.replace(/^\//, '') || 'index'}.md`);
+    if (new Set(current).size !== current.length)
+        throw new Error('Generated VitePress filenames collide');
+    for (const [index, page] of pages.entries()) {
+        const filename = ownedPath(outputDir, current[index]);
+        await mkdir(dirname(filename), { recursive: true });
+        // VitePress's v-pre container keeps Vue expressions literal while parsing Markdown;
+        // escaping angle brackets keeps Vue's SFC parser from choking on tag-shaped prose.
+        const content = escapeAngleBrackets(page.content.trimEnd());
+        await writeFile(filename, `::: v-pre\n\n${content}\n\n:::\n`);
+    }
+    for (const name of [...previous, ...legacy])
+        if (!current.includes(name))
+            await rm(ownedPath(outputDir, name), { force: true });
+    await writeFile(join(outputDir, manifestName), JSON.stringify(current, null, 2) + '\n');
+    await rm(join(outputDir, legacyManifestName), { force: true });
+    return pages.map((page) => ({ text: page.title, link: page.path }));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAClE,OAAO,EAAE,aAAa,EAAwB,MAAM,cAAc,CAAC;AAQnE;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,OAAe;IAC1C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,cAAc,GAAG,EAAE,CAAC;IACxB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,OAAO,KAAK;SACT,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACZ,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,OAAO,GAAG,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACzD,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,cAAc,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,WAAW,EAAE,CAAC;gBAC7E,cAAc,GAAG,EAAE,CAAC;gBACpB,WAAW,GAAG,CAAC,CAAC;YAClB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,OAAO,GAAG,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvD,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC1E,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC;YAChC,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,2EAA2E;QAC3E,OAAO,IAAI;aACR,KAAK,CAAC,WAAW,CAAC;aAClB,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;aACjG,IAAI,CAAC,EAAE,CAAC,CAAC;IACd,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAC9C,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AACrD,SAAS,SAAS,CAAC,SAAiB,EAAE,IAAY;IAChD,MAAM,IAAI,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,KAAK,CAAC,gDAAgD,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AACD,KAAK,UAAU,aAAa,CAAC,SAAiB,EAAE,IAAY;IAC1D,IAAI,CAAC;QACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;QACjF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAC9E,OAAO,KAAK,CAAC,MAAM,CACjB,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CACxG,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QAClE,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAyB,EAAE,OAAyB;IACvF,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7C,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,MAAM,aAAa,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAC9D,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,OAAO,KAAK,CAAC,CAAC;IACrF,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACvG,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,MAAM,QAAQ,GAAG,SAAS,CAAC,SAAS,EAAE,OAAO,CAAC,KAAK,CAAE,CAAC,CAAC;QACvD,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,oFAAoF;QACpF,mFAAmF;QACnF,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5D,MAAM,SAAS,CAAC,QAAQ,EAAE,gBAAgB,OAAO,WAAW,CAAC,CAAC;IAChE,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC;QACzC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,MAAM,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACrF,MAAM,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACxF,MAAM,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/D,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@clidoc/vitepress",
+  "version": "0.1.0",
+  "description": "Publish OpenCLI Markdown in VitePress",
+  "keywords": [
+    "cli",
+    "docs",
+    "documentation",
+    "markdown",
+    "opencli",
+    "vitepress"
+  ],
+  "homepage": "https://clidoc.dev",
+  "bugs": {
+    "url": "https://github.com/bhouston/clidoc/issues"
+  },
+  "license": "MIT",
+  "author": "Ben Houston <ben@ben3d.ca> (https://ben3d.ca)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bhouston/clidoc.git",
+    "directory": "packages/vitepress"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "tsc": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clidoc/core": "^0.1.0"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,91 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { generatePages, type OpenCliDocument } from '@clidoc/core';
+
+export interface VitePressOptions {
+  /** Site source root. Generated pages live below basePath. */
+  outputDir: string;
+  basePath?: string;
+}
+
+/**
+ * VitePress's `v-pre` container stops Vue mustache interpolation but not Vue's
+ * SFC template parser, which still tries to parse tag-shaped text like
+ * `use <profile> to override`. Escape `<`/`>` outside fenced code blocks and
+ * inline code spans so the build never sees an unbalanced "tag".
+ */
+function escapeAngleBrackets(content: string): string {
+  const lines = content.split('\n');
+  let fenceCharacter = '';
+  let fenceLength = 0;
+  return lines
+    .map((line) => {
+      if (fenceLength) {
+        const closing = /^ {0,3}(`{3,}|~{3,})[ \t]*$/.exec(line);
+        if (closing?.[1]?.[0] === fenceCharacter && closing[1].length >= fenceLength) {
+          fenceCharacter = '';
+          fenceLength = 0;
+        }
+        return line;
+      }
+      const opening = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+      if (opening?.[1] && (opening[1][0] === '~' || !opening[2]?.includes('`'))) {
+        fenceCharacter = opening[1][0]!;
+        fenceLength = opening[1].length;
+        return line;
+      }
+      // Split on inline code spans (backtick runs) and only escape outside them.
+      return line
+        .split(/(`+.*?`+)/)
+        .map((part, index) => (index % 2 === 0 ? part.replace(/</g, '&lt;').replace(/>/g, '&gt;') : part))
+        .join('');
+    })
+    .join('\n');
+}
+
+const manifestName = '.clidoc-generated.json';
+const legacyManifestName = '.opencli-generated.json';
+function ownedPath(outputDir: string, name: string): string {
+  const full = resolve(outputDir, name);
+  const rel = relative(outputDir, full);
+  if (!rel || rel.startsWith(`..${sep}`) || rel === '..' || rel.startsWith(sep)) {
+    throw new Error(`Generated filename escapes output directory: ${name}`);
+  }
+  return full;
+}
+async function previousFiles(outputDir: string, name: string): Promise<string[]> {
+  try {
+    const value: unknown = JSON.parse(await readFile(join(outputDir, name), 'utf8'));
+    if (!Array.isArray(value)) throw new Error('Invalid generated file manifest');
+    return value.filter(
+      (entry): entry is string => typeof entry === 'string' && entry.endsWith('.md') && !entry.includes('..'),
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+/** Use in an async VitePress config and assign the result to themeConfig.sidebar. */
+export async function writeVitePress(document: OpenCliDocument, options: VitePressOptions) {
+  const pages = generatePages(document, { basePath: options.basePath });
+  const outputDir = resolve(options.outputDir);
+  await mkdir(outputDir, { recursive: true });
+  const previous = await previousFiles(outputDir, manifestName);
+  const legacy = await previousFiles(outputDir, legacyManifestName);
+  const current = pages.map((page) => `${page.path.replace(/^\//, '') || 'index'}.md`);
+  if (new Set(current).size !== current.length) throw new Error('Generated VitePress filenames collide');
+  for (const [index, page] of pages.entries()) {
+    const filename = ownedPath(outputDir, current[index]!);
+    await mkdir(dirname(filename), { recursive: true });
+    // VitePress's v-pre container keeps Vue expressions literal while parsing Markdown;
+    // escaping angle brackets keeps Vue's SFC parser from choking on tag-shaped prose.
+    const content = escapeAngleBrackets(page.content.trimEnd());
+    await writeFile(filename, `::: v-pre\n\n${content}\n\n:::\n`);
+  }
+  for (const name of [...previous, ...legacy])
+    if (!current.includes(name)) await rm(ownedPath(outputDir, name), { force: true });
+  await writeFile(join(outputDir, manifestName), JSON.stringify(current, null, 2) + '\n');
+  await rm(join(outputDir, legacyManifestName), { force: true });
+  return pages.map((page) => ({ text: page.title, link: page.path }));
+}