Man page

The man-page generator builds a Unix manual page, in mdoc format, from the page that documents a command's options and environment variables. Node.js uses it to build node.1 from doc/api/cli.md, and it works for any command documented the same way.

Target: man-page · Package: @node-core/doc-kit · Reads: API entries · Writes: node.1

The defaults fit Node.js's own page. From the root of a Node.js checkout:

npm install --save-dev @doc-kit/cli @node-core/doc-kit
npx doc-kit generate -t man-page -i doc/api/cli.md -o out

This writes out/node.1; on Linux, read it with man -l out/node.1. Pass only the command-line page as input, since the generator looks for its two sections across everything it reads. For another command, see Using your own template.

Options go in the man-page section of the configuration file:

The generator finds two sections by the slugs of their headings, and turns every ### heading in them into an entry of the man page:

# Command-line reference

## Options

### `-o`, `--output=dir`

Writes the result to _dir_ instead of the working directory.

### `--quiet`

Prints nothing but errors.

## Environment variables

### `MYTOOL_HOME=dir`

Where mytool keeps its cache. **Default:** `~/.mytool`.

## Exit codes

`0` on success, `1` on any error.

• Options are the ### headings between the options heading and the environment variables heading, so the options section must come first.
• Environment variables are the ### headings after their heading, up to the next # or ## heading. Follow the section with another # or ## heading: when it ends the page, its last variable is left out.
• Text right under a section heading, and #### headings with their content, are left out.

A slug is the anchor doc-kit gives a heading when it builds the API entries: GitHub-style, lowercase with hyphens for spaces, and with -1, -2 and so on when the same heading appears earlier on the page. Node.js's cli.md has a #### Environment variables heading under --run, so its section is environment-variables-1. A page like the one above, with a single "Environment variables" heading, needs envVarsHeaderSlug set to 'environment-variables'.

Write an option heading as its flags, each in a code span, separated by a comma and a space. Put the flag's argument after = or a space, and wrap an optional argument in brackets. Write an environment variable heading as its name, followed by = and a value if it takes one.

The content under each entry's heading becomes its description. The generator keeps:

• Paragraphs, run together into one block of text, without paragraph breaks.
• Inline code and bold text, as bold.
• Type annotations, such as {string}, as bold text with their braces.
• Emphasis, as italic.
• Lists, as bullet lists.
• Fenced code blocks, as literal blocks.
• Links, as their text, without the URL.

Everything else is left out, including tables, blockquotes (stability notes and alerts too), images and HTML, so YAML metadata comments don't show up.

The default template describes Node.js: its name, synopsis, description and links are all about node. For another command, write your own.

A template is an mdoc file with two placeholders, __OPTIONS__ and __ENVIRONMENT__. The generator replaces the first occurrence of each with the entries it builds. Those entries are .It items, so put each placeholder inside a .Bl -tag list:

.Dd $Mdocdate$
.Dt MYTOOL 1
.Os
.Sh NAME
.Nm mytool
.Nd builds things
.Sh SYNOPSIS
.Nm
.Op Ar options
.Ar input
.Sh OPTIONS
.Bl -tag -width 6n
__OPTIONS__
.El
.Sh ENVIRONMENT
.Bl -tag -width 6n
__ENVIRONMENT__
.El

Then set the template, the file name and the slugs your page needs:

import { join } from 'node:path';

export default {
  'man-page': {
    fileName: 'mytool.1',
    envVarsHeaderSlug: 'environment-variables',
    templatePath: join(import.meta.dirname, 'man/template.1'),
  },
};

With the page from Writing the command-line page, npx doc-kit generate -t man-page -i docs/cli.md -o out writes out/mytool.1. In man -l out/mytool.1, after the name and synopsis from the template, its sections read:

OPTIONS
     -o, --output=dir
             Writes the result to dir instead of the working directory.

     --quiet
             Prints nothing but errors.

ENVIRONMENT
     MYTOOL_HOME dir
             Where mytool keeps its cache. Default: ~/.mytool.