Skip to main content

Publish from one CLI document

The publishing integrations turn an OpenCLI document, for example one written by a framework adapter, into pages and sidebar entries for your documentation site.

Every output includes a Usage block for each command derived from the specification. Angle brackets mark values to supply, square brackets mark optional items, and ... marks repetition. For example:

mycli send <file> [<destination>] [--format <format>] [--verbose]

Required flags appear without outer square brackets. Boolean flags have no value placeholder; visible global flags are included alongside command flags. The argument and flag tables provide descriptions and constraints.

Docusaurus​

npm install @clidoc/docusaurus @docusaurus/core @docusaurus/preset-classic react react-dom

GitHub · npm

@clidoc/docusaurus generates Markdown documents and sidebar entries while Docusaurus initializes. Point its input at an OpenCLI JSON or YAML file and set outputDir to a dedicated generated directory beneath docs. 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.json', outputDir: 'docs/generated-cli', basePath: '/cli' }]],
};

An autogenerated sidebar ({ type: 'autogenerated', dirName: '.' } in sidebars.js) picks up the generated pages. Generated files use readable names such as clidoc.md and clidoc-validate.md; names that need disambiguation include a deterministic suffix. Page URLs and sidebar IDs remain stable, and regeneration removes old hash filenames recorded in the generated-file manifest. This site uses this integration for its CLI reference.

More information, including the remaining options, is in the README of the npm module.

VitePress​

npm install -D @clidoc/vitepress @clidoc/core vitepress

GitHub · npm

@clidoc/vitepress generates a reference directory and sidebar from the same document. For a command such as mycli validate and basePath: "/reference", it writes reference/commands/validate.md and links to /reference/commands/validate in both the landing page and sidebar. In docs/.vitepress/config.mts:

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.json', 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 }] },
});

More information, including the generated paths to add to .gitignore, is in the README of the npm module.

Standalone Markdown​

npm install -g @clidoc/cli

GitHub · npm

clidoc markdown cli.json --output reference.md and the Commander, oclif, and yargs docgen --format markdown commands use the same renderer, so their command sections include the same usage syntax. They produce a single Markdown document rather than website routes. See the CLI guide for the remaining commands.