@clidoc/docusaurus

Add an always-current CLI reference to your Docusaurus site. Generate pages and sidebar entries from your CLI's OpenCLI document instead of maintaining them by hand. 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:

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, using the docgen command from @clidoc/yargs, @clidoc/commander or @clidoc/oclif.

In docusaurus.config.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:

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.

Why / compared to alternatives

• Hand-written CLI reference pages go stale. These pages are regenerated from your CLI's own definitions (via a framework package), and your hand-written pages stay alongside them.
• Pasting --help output gives one unstructured block per command. Here each command gets its own page, usage synopsis, argument and flag tables, and a sidebar entry.
• oclif readme updates a README for oclif projects only. This publishes into a Docusaurus site from any CLI that can produce an OpenCLI document (Yargs, Commander, oclif).

Related packages

• @clidoc/core: parse, validate and render the OpenCLI document.
• Generate the document from your CLI with @clidoc/yargs, @clidoc/commander, @clidoc/oclif.
• @clidoc/vitepress for VitePress.
• @clidoc/cli: validate the document first with clidoc validate.
• Publishing guide and the demo site.

License

MIT. See LICENSE.

Author

Ben Houston, Sponsored by Land of Assets.