{"$schema":"https://doc-kit.nodejs.org/schemas/api-doc/1.0.1.json","id":"generators-man-page","path":"/generators/man-page","type":"module","module":"generators-man-page","title":"Man page","introducedIn":null,"sourceLink":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The `man-page` generator builds a Unix manual page, in mdoc format, from the\npage that documents a command's options and environment variables. Node.js\nuses it to build `node.1` from `doc/api/cli.md`, and it works for any command\ndocumented the same way.\n\n**Target:** `man-page` · **Package:** [`@node-core/doc-kit`](https://doc-kit.nodejs.org/packages/node) · **Reads:** [API entries](https://doc-kit.nodejs.org/generators/metadata) · **Writes:** `node.1`","summary":"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.","examples":[],"children":[{"kind":"section","id":"usage","name":"Usage","title":"Usage","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The defaults fit Node.js's own page. From the root of a Node.js checkout:\n\n```bash\nnpm install --save-dev @doc-kit/cli @node-core/doc-kit\nnpx doc-kit generate -t man-page -i doc/api/cli.md -o out\n```\n\nThis writes `out/node.1`; on Linux, read it with `man -l out/node.1`. Pass only\nthe command-line page as input, since the generator looks for its two sections\nacross everything it reads. For another command, see\n[Using your own template](#using-your-own-template).","summary":"The defaults fit Node.js's own page. From the root of a Node.js checkout:","examples":[{"language":"bash","displayName":null,"code":"npm install --save-dev @doc-kit/cli @node-core/doc-kit\nnpx doc-kit generate -t man-page -i doc/api/cli.md -o out"}],"children":[]},{"kind":"section","id":"configuring","name":"Configuring","title":"Configuring","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Options go in the `man-page` section of the\n[configuration file](https://doc-kit.nodejs.org/configuration):\n\n* `fileName` {string} The name of the file to write. **Default:** `'node.1'`.\n* `templatePath` {string} The mdoc template to fill in, as an absolute path or\n  a path relative to the working directory. **Default:** the Node.js template\n  that ships with the generator (`template.1`).\n* `cliOptionsHeaderSlug` {string} The slug of the heading that starts the\n  options section. **Default:** `'options'`.\n* `envVarsHeaderSlug` {string} The slug of the heading that starts the\n  environment variables section. **Default:** `'environment-variables-1'`, the\n  second \"Environment variables\" heading in Node.js's `cli.md`.\n* `output` {string} The directory to write the man page to. Without one,\n  nothing is written. **Default:** from `global.output` (`--output`).","summary":"Options go in the `man-page` section of the configuration file:","examples":[],"children":[]},{"kind":"section","id":"writing-the-command-line-page","name":"Writing the command-line page","title":"Writing the command-line page","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The generator finds two sections by the slugs of their headings, and turns\nevery `###` heading in them into an entry of the man page:\n\n```md displayName=\"docs/cli.md\"\n# Command-line reference\n\n## Options\n\n### `-o`, `--output=dir`\n\nWrites the result to _dir_ instead of the working directory.\n\n### `--quiet`\n\nPrints nothing but errors.\n\n## Environment variables\n\n### `MYTOOL_HOME=dir`\n\nWhere mytool keeps its cache. **Default:** `~/.mytool`.\n\n## Exit codes\n\n`0` on success, `1` on any error.\n```\n\n* Options are the `###` headings between the options heading and the\n  environment variables heading, so the options section must come first.\n* Environment variables are the `###` headings after their heading, up to the\n  next `#` or `##` heading. Follow the section with another `#` or `##`\n  heading: when it ends the page, its last variable is left out.\n* Text right under a section heading, and `####` headings with their content,\n  are left out.\n\nA slug is the anchor doc-kit gives a heading when it builds the\n[API entries](https://doc-kit.nodejs.org/generators/metadata#heading-kinds):\nGitHub-style, lowercase with hyphens for spaces, and with `-1`, `-2` and so on\nwhen the same heading appears earlier on the page. Node.js's `cli.md` has a\n`#### Environment variables` heading under `--run`, so its section is\n`environment-variables-1`. A page like the one above, with a single\n\"Environment variables\" heading, needs `envVarsHeaderSlug` set to\n`'environment-variables'`.\n\n> \\[!WARNING]\n> When a slug matches no heading, the generator doesn't fail. It still writes\n> the man page, with entries in the wrong section or missing. If the output\n> looks off, check the slugs first.","summary":"The generator finds two sections by the slugs of their headings, and turns every `###` heading in them into an entry of the man page:","examples":[{"language":"md","displayName":"docs/cli.md","code":"# Command-line reference\n\n## Options\n\n### `-o`, `--output=dir`\n\nWrites the result to _dir_ instead of the working directory.\n\n### `--quiet`\n\nPrints nothing but errors.\n\n## Environment variables\n\n### `MYTOOL_HOME=dir`\n\nWhere mytool keeps its cache. **Default:** `~/.mytool`.\n\n## Exit codes\n\n`0` on success, `1` on any error."}],"children":[{"kind":"section","id":"headings","name":"Headings","title":"Headings","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"Write an option heading as its flags, each in a code span, separated by a\ncomma and a space. Put the flag's argument after `=` or a space, and wrap an\noptional argument in brackets. Write an environment variable heading as its\nname, followed by `=` and a value if it takes one.\n\n| Heading                         | In the man page           |\n| ------------------------------- | ------------------------- |\n| `` `-o`, `--output=dir` ``      | `-o, --output=dir`        |\n| `` `-e`, `--eval \"script\"` ``   | `-e, --eval script`       |\n| `` `--inspect[=[host:]port]` `` | `--inspect=[[host:]port]` |\n| `` `MYTOOL_HOME=dir` ``         | `MYTOOL_HOME dir`         |","summary":"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.","examples":[],"children":[]},{"kind":"section","id":"descriptions","name":"Descriptions","title":"Descriptions","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The content under each entry's heading becomes its description. The generator\nkeeps:\n\n* Paragraphs, run together into one block of text, without paragraph breaks.\n* Inline code and bold text, as bold.\n* Type annotations, such as `{string}`, as bold text with their braces.\n* Emphasis, as italic.\n* Lists, as bullet lists.\n* Fenced code blocks, as literal blocks.\n* Links, as their text, without the URL.\n\nEverything else is left out, including tables, blockquotes (stability notes\nand alerts too), images and HTML, so YAML metadata comments don't show up.","summary":"The content under each entry's heading becomes its description. The generator keeps:","examples":[],"children":[]}]},{"kind":"section","id":"using-your-own-template","name":"Using your own template","title":"Using your own template","scope":"module","overloadOf":null,"stability":null,"added":[],"deprecated":[],"removed":[],"napiVersion":[],"changes":[],"description":"The default template describes Node.js: its name, synopsis, description and\nlinks are all about `node`. For another command, write your own.\n\nA template is an mdoc file with two placeholders, `__OPTIONS__` and\n`__ENVIRONMENT__`. The generator replaces the first occurrence of each with the\nentries it builds. Those entries are `.It` items, so put each placeholder\ninside a `.Bl -tag` list:\n\n```text displayName=\"man/template.1\"\n.Dd $Mdocdate$\n.Dt MYTOOL 1\n.Os\n.Sh NAME\n.Nm mytool\n.Nd builds things\n.Sh SYNOPSIS\n.Nm\n.Op Ar options\n.Ar input\n.Sh OPTIONS\n.Bl -tag -width 6n\n__OPTIONS__\n.El\n.Sh ENVIRONMENT\n.Bl -tag -width 6n\n__ENVIRONMENT__\n.El\n```\n\nThen set the template, the file name and the slugs your page needs:\n\n```js displayName=\"doc-kit.config.mjs\"\nimport { join } from 'node:path';\n\nexport default {\n  'man-page': {\n    fileName: 'mytool.1',\n    envVarsHeaderSlug: 'environment-variables',\n    templatePath: join(import.meta.dirname, 'man/template.1'),\n  },\n};\n```\n\nWith the page from\n[Writing the command-line page](#writing-the-command-line-page),\n`npx doc-kit generate -t man-page -i docs/cli.md -o out` writes\n`out/mytool.1`. In `man -l out/mytool.1`, after the name and synopsis from the\ntemplate, its sections read:\n\n```text\nOPTIONS\n     -o, --output=dir\n             Writes the result to dir instead of the working directory.\n\n     --quiet\n             Prints nothing but errors.\n\nENVIRONMENT\n     MYTOOL_HOME dir\n             Where mytool keeps its cache. Default: ~/.mytool.\n```","summary":"The default template describes Node.js: its name, synopsis, description and links are all about `node`. For another command, write your own.","examples":[{"language":"text","displayName":"man/template.1","code":".Dd $Mdocdate$\n.Dt MYTOOL 1\n.Os\n.Sh NAME\n.Nm mytool\n.Nd builds things\n.Sh SYNOPSIS\n.Nm\n.Op Ar options\n.Ar input\n.Sh OPTIONS\n.Bl -tag -width 6n\n__OPTIONS__\n.El\n.Sh ENVIRONMENT\n.Bl -tag -width 6n\n__ENVIRONMENT__\n.El"},{"language":"js","displayName":"doc-kit.config.mjs","code":"import { join } from 'node:path';\n\nexport default {\n  'man-page': {\n    fileName: 'mytool.1',\n    envVarsHeaderSlug: 'environment-variables',\n    templatePath: join(import.meta.dirname, 'man/template.1'),\n  },\n};"},{"language":"text","displayName":null,"code":"OPTIONS\n     -o, --output=dir\n             Writes the result to dir instead of the working directory.\n\n     --quiet\n             Prints nothing but errors.\n\nENVIRONMENT\n     MYTOOL_HOME dir\n             Where mytool keeps its cache. Default: ~/.mytool."}],"children":[]}]}