@clidoc/docusaurus 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,97 @@
+# @clidoc/docusaurus
+
+[![npm version](https://img.shields.io/npm/v/%40clidoc%2Fdocusaurus)](https://www.npmjs.com/package/@clidoc/docusaurus)
+[![npm downloads](https://img.shields.io/npm/dw/%40clidoc%2Fdocusaurus)](https://www.npmjs.com/package/@clidoc/docusaurus)
+[![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 Docusaurus documentation and sidebar entries from an OpenCLI document.
+The output is ordinary Markdown with CommonMark front matter, so CLI descriptions
+remain plain Markdown even when they contain JSX-like text.
+
+Install the publisher alongside Docusaurus and its classic preset:
+
+```sh
+npm install @clidoc/docusaurus @docusaurus/core @docusaurus/preset-classic react react-dom
+```
+
+Export an OpenCLI document from your CLI, for example with
+`mycli docgen --format yaml --output cli.ocs.yaml`.
+
+In `docusaurus.config.js`:
+
+```js
+const clidocPlugin = require('@clidoc/docusaurus');
+
+module.exports = {
+  title: 'My CLI',
+  url: 'https://example.com',
+  baseUrl: '/',
+  markdown: { format: 'md' },
+  presets: [['classic', { docs: { routeBasePath: '/', sidebarPath: './sidebars.js' }, blog: false }]],
+  plugins: [
+    [
+      clidocPlugin,
+      {
+        input: 'cli.ocs.yaml',
+        outputDir: 'docs/generated-cli',
+        basePath: '/cli',
+      },
+    ],
+  ],
+};
+```
+
+In `sidebars.js`:
+
+```js
+module.exports = { docs: [{ type: 'autogenerated', dirName: '.' }] };
+```
+
+Keep your handwritten pages in `docs/` (for example, `docs/index.md`). The
+generated CLI pages appear beneath `docs/generated-cli/` and are included by
+the autogenerated sidebar.
+
+Run `npx docusaurus start` to preview the site.
+
+Docusaurus 3 loads site configuration with CommonJS. The package includes a small
+CommonJS entrypoint that imports the ESM generator when the plugin runs.
+`docusaurus.config.js` itself is loaded through jiti, which does not support a
+top-level `await`; load the OpenCLI document from a file path via `input`
+instead of awaiting a parse at the top of the config.
+
+Set `input` to a parsed OpenCLI document or a JSON/YAML path relative to the
+site directory. The plugin writes files during initialization, before the docs plugin
+scans content, so the docs plugin's autogenerated sidebar discovers the pages.
+`title` is used as each page's sidebar label. The
+plugin path relies on that autogenerated sidebar and does not return one of
+its own; for a hand-built sidebar array, call `writeDocusaurus()` directly
+from `sidebars.js` instead of using the plugin.
+
+`writeDocusaurus(document, {outputDir, basePath})` offers direct generation
+for build scripts. Generated files have readable names based on the executable and
+command, such as `mycli.md` for the landing page and `mycli-validate.md` for a
+command page. Names that contain unsafe characters, exceed the length limit, or
+would otherwise collide retain a readable prefix and add a deterministic digest.
+Page IDs and routes are defined separately in front matter and do not change with
+the filenames.
+
+Regeneration removes files listed in `.clidoc-generated.json`. Generation stops
+instead of overwriting a matching filename that is not owned by that manifest.
+On the first run after upgrading from OpenCLI, it also removes old generated
+pages listed in `.opencli-generated.json` and deletes that legacy manifest.
+Other documents in the directory are preserved. Landing-page links to command
+pages point at the generated filenames directly, so routes resolve correctly
+regardless of the docs plugin's `routeBasePath`.
+
+Add `docs/generated-cli/` to `.gitignore` if generated pages should stay out of
+version control.
+
+## 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,24 @@
+import { type OpenCliDocument } from '@clidoc/core';
+export interface DocusaurusOptions {
+    /** An OpenCLI document or a JSON/YAML filename relative to siteDir. */
+    input: OpenCliDocument | string;
+    /** Dedicated generated directory consumed by the Docusaurus docs plugin. */
+    outputDir: string;
+    basePath?: string;
+}
+/** Write CommonMark docs and remove only files recorded as generated by this package. */
+export declare function writeDocusaurus(document: OpenCliDocument, options: {
+    outputDir: string;
+    basePath?: string;
+}): Promise<{
+    type: 'doc';
+    id: string;
+    label: string;
+}[]>;
+/** Generate before content loading, so plugin-content-docs can discover the files. */
+export default function clidocPlugin(context: {
+    siteDir: string;
+}, options: DocusaurusOptions): Promise<{
+    name: 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":"AAGA,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAE1E,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC;IAChC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAmED,yFAAyF;AACzF,wBAAsB,eAAe,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE;UA4C5E,KAAK;;;KAC1C;AAED,sFAAsF;AACtF,wBAA8B,YAAY,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,iBAAiB;;GAUlG"}

package/dist/index.js

@@ -0,0 +1,120 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { generatePages, parse } from '@clidoc/core';
+const manifestName = '.clidoc-generated.json';
+const legacyManifestName = '.opencli-generated.json';
+const legacyFilename = /^(?:clidoc|opencli)-[a-f0-9]{20}\.md$/;
+function filenamePart(value) {
+    if (/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value) && value.length <= 48)
+        return value;
+    const readable = value
+        .toLowerCase()
+        .normalize('NFKD')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 32) || 'page';
+    return `${readable}-${createHash('sha256').update(value).digest('hex').slice(0, 16)}`;
+}
+function filename(binary, id, title) {
+    const prefix = filenamePart(binary);
+    if (id === 'index')
+        return `${prefix}.md`;
+    const command = title.startsWith(`${binary} `) ? title.slice(binary.length + 1) : title;
+    const words = command.trim().split(/\s+/);
+    const syntax = words.findIndex((word) => /^(?:<|\[|\{|--)/.test(word));
+    const staticWords = syntax === -1 ? words : words.slice(0, syntax);
+    const staticCommand = staticWords.length ? staticWords.join('-') : command;
+    return `${prefix}-${filenamePart(staticCommand)}.md`;
+}
+function filenames(binary, pages) {
+    const candidates = pages.map((page) => filename(binary, page.id, page.title));
+    const counts = new Map();
+    for (const candidate of candidates)
+        counts.set(candidate, (counts.get(candidate) ?? 0) + 1);
+    return candidates.map((candidate, position) => {
+        if (counts.get(candidate) === 1)
+            return candidate;
+        const stem = candidate.slice(0, -'.md'.length);
+        const digest = createHash('sha256').update(pages[position].id).digest('hex').slice(0, 16);
+        return `${stem}--${digest}.md`;
+    });
+}
+async function previousFiles(outputDir, name) {
+    try {
+        const value = JSON.parse(await readFile(join(outputDir, name), 'utf8'));
+        // Array manifests were written by older releases. Only accept their opaque generated
+        // names so a malformed old manifest cannot claim an unrelated Markdown document.
+        if (Array.isArray(value))
+            return value.filter((entry) => typeof entry === 'string' && legacyFilename.test(entry));
+        if (typeof value !== 'object' ||
+            value === null ||
+            !('version' in value) ||
+            value.version !== 1 ||
+            !('files' in value) ||
+            !Array.isArray(value.files) ||
+            !value.files.every((entry) => typeof entry === 'string' && /^[a-z0-9][a-z0-9-]*\.md$/.test(entry) && entry.length <= 120))
+            throw new Error('Invalid generated file manifest');
+        return value.files;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/** Write CommonMark docs and remove only files recorded as generated by this package. */
+export async function writeDocusaurus(document, options) {
+    const pages = generatePages(document, { basePath: options.basePath });
+    await mkdir(options.outputDir, { recursive: true });
+    const previous = await previousFiles(options.outputDir, manifestName);
+    const legacy = await previousFiles(options.outputDir, legacyManifestName);
+    const existing = await readdir(options.outputDir);
+    const current = filenames(document.info.binary, pages);
+    if (new Set(current).size !== current.length)
+        throw new Error('Generated Docusaurus filenames collide');
+    const owned = new Set([...previous, ...legacy]);
+    const unownedCollision = current.find((name) => !owned.has(name) && existing.includes(name));
+    if (unownedCollision)
+        throw new Error(`Refusing to overwrite unowned file: ${unownedCollision}`);
+    // Map each page's route to the generated filename holding it, so the landing page can link by
+    // file instead of by route: Docusaurus then resolves the URL itself regardless of routeBasePath.
+    const filenameByPath = new Map(pages.map((page, position) => [page.path, current[position]]));
+    for (const [position, page] of pages.entries()) {
+        const frontmatter = [
+            '---',
+            'mdx:',
+            '  format: md',
+            `id: ${JSON.stringify(page.id)}`,
+            `title: ${JSON.stringify(page.title)}`,
+            `slug: ${JSON.stringify(page.path)}`,
+            `sidebar_position: ${position + 1}`,
+            '---',
+            '',
+        ].join('\n');
+        const content = page.id === 'index'
+            ? pages
+                .slice(1)
+                .reduce((text, target) => text.replaceAll(`](${target.path})`, `](./${filenameByPath.get(target.path)})`), page.content)
+            : page.content;
+        await writeFile(join(options.outputDir, current[position]), frontmatter + content);
+    }
+    for (const name of [...previous, ...legacy])
+        if (!current.includes(name))
+            await rm(join(options.outputDir, name), { force: true });
+    await writeFile(join(options.outputDir, manifestName), JSON.stringify({ version: 1, files: current }, null, 2) + '\n');
+    await rm(join(options.outputDir, legacyManifestName), { force: true });
+    return pages.map((page) => ({ type: 'doc', id: page.id, label: page.title }));
+}
+/** Generate before content loading, so plugin-content-docs can discover the files. */
+export default async function clidocPlugin(context, options) {
+    const document = typeof options.input === 'string'
+        ? parse(await readFile(resolve(context.siteDir, options.input), 'utf8'))
+        : options.input;
+    await writeDocusaurus(document, {
+        outputDir: resolve(context.siteDir, options.outputDir),
+        basePath: options.basePath,
+    });
+    return { name: 'clidoc-docusaurus' };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/index.cjs

@@ -0,0 +1,5 @@
+// Docusaurus 3 loads site configuration through CommonJS jiti.
+module.exports = async function clidocPlugin(context, options) {
+  const { default: plugin } = await import('./dist/index.js');
+  return plugin(context, options);
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@clidoc/docusaurus",
+  "version": "0.1.0",
+  "description": "Publish OpenCLI Markdown in Docusaurus",
+  "keywords": [
+    "cli",
+    "docs",
+    "documentation",
+    "docusaurus",
+    "markdown",
+    "opencli"
+  ],
+  "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/docusaurus"
+  },
+  "files": [
+    "index.cjs",
+    "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",
+      "require": "./index.cjs"
+    }
+  },
+  "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,138 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { generatePages, parse, type OpenCliDocument } from '@clidoc/core';
+
+export interface DocusaurusOptions {
+  /** An OpenCLI document or a JSON/YAML filename relative to siteDir. */
+  input: OpenCliDocument | string;
+  /** Dedicated generated directory consumed by the Docusaurus docs plugin. */
+  outputDir: string;
+  basePath?: string;
+}
+
+const manifestName = '.clidoc-generated.json';
+const legacyManifestName = '.opencli-generated.json';
+const legacyFilename = /^(?:clidoc|opencli)-[a-f0-9]{20}\.md$/;
+
+function filenamePart(value: string): string {
+  if (/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value) && value.length <= 48) return value;
+  const readable =
+    value
+      .toLowerCase()
+      .normalize('NFKD')
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 32) || 'page';
+  return `${readable}-${createHash('sha256').update(value).digest('hex').slice(0, 16)}`;
+}
+
+function filename(binary: string, id: string, title: string): string {
+  const prefix = filenamePart(binary);
+  if (id === 'index') return `${prefix}.md`;
+  const command = title.startsWith(`${binary} `) ? title.slice(binary.length + 1) : title;
+  const words = command.trim().split(/\s+/);
+  const syntax = words.findIndex((word) => /^(?:<|\[|\{|--)/.test(word));
+  const staticWords = syntax === -1 ? words : words.slice(0, syntax);
+  const staticCommand = staticWords.length ? staticWords.join('-') : command;
+  return `${prefix}-${filenamePart(staticCommand)}.md`;
+}
+
+function filenames(binary: string, pages: ReturnType<typeof generatePages>): string[] {
+  const candidates = pages.map((page) => filename(binary, page.id, page.title));
+  const counts = new Map<string, number>();
+  for (const candidate of candidates) counts.set(candidate, (counts.get(candidate) ?? 0) + 1);
+  return candidates.map((candidate, position) => {
+    if (counts.get(candidate) === 1) return candidate;
+    const stem = candidate.slice(0, -'.md'.length);
+    const digest = createHash('sha256').update(pages[position]!.id).digest('hex').slice(0, 16);
+    return `${stem}--${digest}.md`;
+  });
+}
+
+async function previousFiles(outputDir: string, name: string): Promise<string[]> {
+  try {
+    const value: unknown = JSON.parse(await readFile(join(outputDir, name), 'utf8'));
+    // Array manifests were written by older releases. Only accept their opaque generated
+    // names so a malformed old manifest cannot claim an unrelated Markdown document.
+    if (Array.isArray(value))
+      return value.filter((entry): entry is string => typeof entry === 'string' && legacyFilename.test(entry));
+    if (
+      typeof value !== 'object' ||
+      value === null ||
+      !('version' in value) ||
+      value.version !== 1 ||
+      !('files' in value) ||
+      !Array.isArray(value.files) ||
+      !value.files.every(
+        (entry) => typeof entry === 'string' && /^[a-z0-9][a-z0-9-]*\.md$/.test(entry) && entry.length <= 120,
+      )
+    )
+      throw new Error('Invalid generated file manifest');
+    return value.files;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+/** Write CommonMark docs and remove only files recorded as generated by this package. */
+export async function writeDocusaurus(document: OpenCliDocument, options: { outputDir: string; basePath?: string }) {
+  const pages = generatePages(document, { basePath: options.basePath });
+  await mkdir(options.outputDir, { recursive: true });
+  const previous = await previousFiles(options.outputDir, manifestName);
+  const legacy = await previousFiles(options.outputDir, legacyManifestName);
+  const existing = await readdir(options.outputDir);
+  const current = filenames(document.info.binary, pages);
+  if (new Set(current).size !== current.length) throw new Error('Generated Docusaurus filenames collide');
+  const owned = new Set([...previous, ...legacy]);
+  const unownedCollision = current.find((name) => !owned.has(name) && existing.includes(name));
+  if (unownedCollision) throw new Error(`Refusing to overwrite unowned file: ${unownedCollision}`);
+  // Map each page's route to the generated filename holding it, so the landing page can link by
+  // file instead of by route: Docusaurus then resolves the URL itself regardless of routeBasePath.
+  const filenameByPath = new Map(pages.map((page, position) => [page.path, current[position]!]));
+  for (const [position, page] of pages.entries()) {
+    const frontmatter = [
+      '---',
+      'mdx:',
+      '  format: md',
+      `id: ${JSON.stringify(page.id)}`,
+      `title: ${JSON.stringify(page.title)}`,
+      `slug: ${JSON.stringify(page.path)}`,
+      `sidebar_position: ${position + 1}`,
+      '---',
+      '',
+    ].join('\n');
+    const content =
+      page.id === 'index'
+        ? pages
+            .slice(1)
+            .reduce(
+              (text, target) => text.replaceAll(`](${target.path})`, `](./${filenameByPath.get(target.path)})`),
+              page.content,
+            )
+        : page.content;
+    await writeFile(join(options.outputDir, current[position]!), frontmatter + content);
+  }
+  for (const name of [...previous, ...legacy])
+    if (!current.includes(name)) await rm(join(options.outputDir, name), { force: true });
+  await writeFile(
+    join(options.outputDir, manifestName),
+    JSON.stringify({ version: 1, files: current }, null, 2) + '\n',
+  );
+  await rm(join(options.outputDir, legacyManifestName), { force: true });
+  return pages.map((page) => ({ type: 'doc' as const, id: page.id, label: page.title }));
+}
+
+/** Generate before content loading, so plugin-content-docs can discover the files. */
+export default async function clidocPlugin(context: { siteDir: string }, options: DocusaurusOptions) {
+  const document =
+    typeof options.input === 'string'
+      ? parse(await readFile(resolve(context.siteDir, options.input), 'utf8'))
+      : options.input;
+  await writeDocusaurus(document, {
+    outputDir: resolve(context.siteDir, options.outputDir),
+    basePath: options.basePath,
+  });
+  return { name: 'clidoc-docusaurus' };
+}