Man

@crustjs/man generates manual pages at build time. crust publish only reads and publishes output already staged by a package build.

InstallCopy Anchor Link

npm install -D @crustjs/man

The package has a peer dependency on @crustjs/core.

man(options?)Copy Anchor Link

import { Crust } from "@crustjs/core";
import { man } from "@crustjs/man";

const app = new Crust("my-cli").extend(man());

.crust/artifacts/man/my-cli.1

man() registers a build hook; registering it writes nothing. During crust build, the hook returns man/<name>.<section>, which the build writes, copies into the staged packages, and records as an artifact owned by crust:man.

Pass man({ section: 5 }) to change the section and filename. The page is named after the root command, which crust build requires to match the installed command. The man.id static exposes the Extension identity used for section filtering.

writeManPage(options)Copy Anchor Link

import { writeManPage } from "@crustjs/man";

const root = await app.snapshot();
await writeManPage({ root, outfile: "man/my-cli.1" });
// Writes man/my-cli.1

writeManPage() renders a Command Snapshot, creates parent directories, and writes the page; the build hook does not use it. section defaults to 1; date overrides the .Dd value.

Without date, rendering uses SOURCE_DATE_EPOCH in UTC when set, then the current local date. Generated dates use the English Month D, YYYY form expected by mdoc.

renderManPageMdoc(options)Copy Anchor Link

import { renderManPageMdoc } from "@crustjs/man";

const root = await app.snapshot();
const source = renderManPageMdoc({ root });
console.log(source.startsWith(".Dd ")); // => true

renderManPageMdoc() returns mdoc text without writing a file. It accepts a prepared Command Snapshot, not a live definition.

The renderer lists immediate visible children in the root summary and collects visible subcommand sections under .Sh COMMANDS. Sections targeted to man are audience-filtered, same-title sections merge at their first position, and section titles are uppercased (Files renders as .Sh FILES).

Descriptions, usage lines, and section bodies are plain text: backslashes and leading . or ' are escaped, so C:\tmp or \fB render literally rather than as roff.

new Crust("my-cli", {
  sections: [{ title: "FILES", body: "~/.config/my-cli.json", only: [man] }],
});

Use only: [man] to include a section only in manual pages, or except: [man] to omit it there.

Package scriptCopy Anchor Link

{
  "scripts": { "generate:man": "bun run scripts/generate-man.ts" },
  "files": ["dist", "man"],
  "man": ["./man/my-cli.1"]
}

npm run generate:man
man -l man/my-cli.1
mandoc -T lint -W warning man/my-cli.1

Use writeManPage() for a custom pipeline outside the Extension build lifecycle.