Markdown command references
This API is available since Optique 1.4.0.
Import formatCommandReference() from @optique/man/markdown to produce one file containing a linked contents list and a section for each command. It accepts existing DocPage data with explicit canonical paths. The renderer is a separate entry point and adds no Markdown dependency to ordinary parser or runner imports.
import { message } from "@optique/core/message";
import { formatCommandReference } from "@optique/man/markdown";
const reference = formatCommandReference([
{
path: [],
page: {
sections: [{
title: "Commands",
entries: [{ term: { type: "command", name: "serve" } }],
}],
},
},
{
path: ["serve"],
aliases: ["s"],
page: {
usage: [
{ type: "command", name: "serve" },
{ type: "optional", terms: [{
type: "option", names: ["--port"], metavar: "PORT",
}] },
],
sections: [{ entries: [{
term: { type: "option", names: ["--port"], metavar: "PORT" },
description: message`Port to listen on.`,
default: message`8080`,
}] }],
},
},
], {
name: "myapp",
showAliases: true,
coverage: {
commands: "all-visible",
help: "excluded",
version: "excluded",
completion: "excluded",
},
});path: [] identifies the root page. Other paths contain canonical command names, excluding the executable name and positional values. A page's usage already includes its command tokens. The renderer adds the executable name once; it does not prepend the path again. If a shared option applies to a descendant command, include it in that command's supplied page.
Supplied entries keep their order. A duplicate path throws TypeError, as does an alias that resolves to two different commands under one parent. Different parents can each have a child named get. Entry-level aliases and visibility are authoritative when a parent page lists that command. hiddenAliases never appear in the output, but participate in collision checks.
Descriptions, grouped inputs, defaults, choices, examples, and declared environment names are rendered where present. A formatted default is documentation text, not an evaluated or machine-readable default value. Environment names do not cause variables to be read.
Declaring coverage
Every artifact prints its author-declared coverage. commands: "all-visible" asserts that all visible commands in the declared scope have pages. The renderer checks supplied prefixes and visible command-list references, but it cannot discover commands omitted from every page. Use "partial" to retain output with a visible report of missing referenced pages.
The three runner fields declare whether all configured forms of help, version, and completion within that scope are documented. "excluded" prints “not documented here (if configured).” The original parser does not include every runner-added input. To declare "included", supply their option entries and pages for configured command forms yourself. Match the application's configured names, aliases, arguments, and visibility; the renderer does not inspect runner configuration.
The runnable reference fixture supplies --help, --version, and completion SHELL [ARG...] for its runner configuration. It also includes the application's docs command. Its maintained argument examples and build/runtime outputs are tested on Deno, Node.js, and Bun.
Collecting supported definitions
For supported built-in definitions, the optional @optique/core/doc-pages entry point constructs pages from core-owned metadata without parsing arguments:
import { or } from "@optique/core/constructs";
import { collectDocPages } from "@optique/core/doc-pages";
import { withDefault } from "@optique/core/modifiers";
import { command, option } from "@optique/core/primitives";
import { integer, string } from "@optique/core/valueparser";
import { formatCommandReference } from "@optique/man/markdown";
const parser = or(
command("serve", withDefault(option("--port", integer()), 8080)),
command("inspect", option("--name", string())),
);
const collected = collectDocPages(parser);
const reference = formatCommandReference(collected.entries, {
name: "myapp",
coverage: {
commands: "all-visible",
help: "excluded",
version: "excluded",
completion: "excluded",
},
});The supported constructor list is command(), or(), object(), seq(), option(), flag(), argument(), optional(), multiple(), and withDefault(). Static value metadata is available for string(), integer(), and choice(). Other wrappers and custom parsers are opaque. Custom value parsers retain only their enclosing primitive's names, description, and metavariable captured during construction; their methods and getters are not consulted during collection.
Collection does not call parse(), complete(), documentation methods, normalization, validation, suggestion providers, or source resolvers. It does not invoke handlers, lifecycle hooks, prompts, keyring access, network clients, or environment/configuration loaders. Definitions may be synchronous or asynchronous without resolving their runtime values.
Function defaults are omitted unless withDefault() supplies a documentation message. This differs from ordinary help, which can evaluate a default thunk. Static defaults use built-in formatting captured at construction. Defaults that require normalization or unsupported formatting are omitted and reported. Supply a documentation message when that omission is unsuitable.
A command after a required positional prefix keeps the prefix in its usage, while its path contains only command tokens. Use seq() for ordered input; tuple() and other unlisted constructors are outside this collector's scope. Usage overrides affect presentation, not traversal. A functional usageLine requires a supplied static page usage; it is never called by collection.
Unsupported scopes and authored pages
Strict collection is the default. DocPageCollectionError.result contains the partial pages and explicit unresolved scopes. Set strict: false to inspect those pages and reports without throwing. A functional usage override leaves that page's synopsis absent in partial output; report that omission when publishing a partial reference rather than calling it complete. Pass the result's unresolved array to the renderer's unresolved option with commands: "partial" to include those omissions in the artifact.
const collected = collectDocPages(parser, {
entries: [
{ path: [], page: rootPage, coverage: "subtree" },
{ path: ["custom"], page: childPage },
],
});A supplied page replaces the automatic page at its exact path. Default coverage: "page" resolves omissions in that page; it does not cover an opaque subtree. "subtree" is the author's assertion that pages for all visible descendants were supplied too. An opaque node's children cannot be enumerated, so this assertion is not independently verified. Known incomplete descendant pages still need authored replacements. Visible child references and supplied prefixes still need matching pages. If several branches have the same canonical path, supply authored pages. Positional values do not become command path segments. A sequence with multiple children that contain commands reports ambiguous-command-path; supply authored pages for that scope.
The collector reports the visible enclosing scope and reason for each unsupported node. Documentation-hidden branches are skipped before these checks. A supplied static usage is still required for each known functional usage override; a broad subtree assertion does not evaluate or replace that function.
See the bounded prototype evidence for the fixed fixture and callback checks. This collector exports pages, not a versioned grammar schema or a custom inspection protocol.
Build and runtime entry points
Keep definitions and authored pages in modules that start no application work. A build script can import those pages and write the artifact:
writeFileSync("REFERENCE.md", formatCommandReference(pages, {
name: "myapp",
coverage: {
commands: "all-visible",
help: "excluded",
version: "excluded",
completion: "excluded",
},
}));Applications choose their own docs command or --docs option. The runnable fixture parses its own docs command, then dynamically imports the renderer and authored pages in that branch. Its ordinary command path prints parsed example data; it starts no server and changes no settings. The fixture's build.ts writes a file, while running cli.ts with docs writes the same bytes to stdout.
mise deps
mise build
mise exec -- node packages/man/test/fixtures/markdown-reference/build.ts REFERENCE.md
mise exec -- node packages/man/test/fixtures/markdown-reference/cli.ts docs > REFERENCE.mdOptique does not sandbox module imports or construction of supplied pages. getDocPageSync()/getDocPageAsync() can parse navigation arguments, evaluate defaults, and call custom documentation/formatting methods. If you use them to construct explicit entries, those effects occur in application code before the renderer receives the pages. Filesystem discovery also imports command modules, whose top-level code may have effects. Export dedicated definitions/pages without executable startup code.
Visibility, formatting, and anchors
The hidden values true, "doc", and "help" hide sections and contents entries, including supplied descendants of hidden parents. "usage" hides synopsis terms only; those commands still have linked sections. A collected command page keeps its selected command tokens in the synopsis, matching contextual help. A "doc"-hidden command may remain in a parent's code-formatted synopsis without a section link. showUsage overrides a page's showUsage; otherwise the page setting applies. Alias display uses a command-list DocEntry.showAliases first, then the target entry's showAliases, then the renderer option. Hidden aliases are always omitted.
Messages are escaped documentation text. Untrusted Markdown, HTML, link syntax, backticks, and fence delimiters cannot add structure. URL message terms render as inert code. A consumer may linkify bare web or email text according to its own Markdown settings. Output has no timestamps or locale-dependent ordering.
Each explicit anchor is optique-command. followed by the lowercase hexadecimal UTF-8 bytes of JSON.stringify(path). Distinct valid paths have distinct IDs, including paths that share a leaf name or contain delimiters. The dot keeps these IDs separate from GitHub/VitePress heading slugs. Generated internal links use owned HTML so VitePress preserves their exact destinations. Consumers must allow raw HTML for these anchors and links; the full canonical headings remain readable in consumers that strip HTML. Code spans and synopsis fences use context-sized delimiters.