Mdat plugin to generate tabular CLI tool documentation in Markdown files.
This is a plugin for the mdat CLI tool, which is a simple Markdown templating system optimized for embedding dynamic content in repository readmes and the like.
This plugin automatically transforms a CLI command's --help output into nicely formatted Markdown tables.
The rule also recursively calls --help on any subcommands found for inclusion in the output.
Currently, the rule can only parse help output in the format provided by Yargs- and Meow-based tools. If parsing fails, the rule will fall back to show the raw help output in a regular code block instead.
We'll assume you have mdat installed either globally or in your local project.
Install the plugin as a development dependency:
pnpm add -D mdat-plugin-cli-helpRegister the plugin in your mdat config file, e.g. mdat.config.ts:
import type { Config } from 'mdat'
import cliHelp from 'mdat-plugin-cli-help'
export default {
rules: {
...cliHelp,
},
} satisfies ConfigAssuming you have an executable with a --help flag on your path or in your project's scope:
<!-- cli-help { cliCommand: "mdat", depth: 1 } -->Then run the mdat CLI command on your Markdown file to expand the rule and embed the tabular help output:
<!-- cli-help { cliCommand: "mdat", depth: 1 } -->
#### Command: `mdat`
Work with MDAT placeholder comments in any Markdown file.
If no command is provided, `mdat expand` is run by default.
Usage:
```txt
mdat [command]
```
| Positional Argument | Description | Type |
| ------------------- | ------------------------------------------------ | -------- |
| `files` | Markdown file(s) with MDAT placeholder comments. | `string` |
| Command | Argument | Description |
| ---------- | ----------------------- | -------------------------------------------------------------- |
| `expand` | `<files..>` `[options]` | Expand MDAT placeholder comments. _(Default command.)_ |
| `check` | `<files..>` `[options]` | Validate a Markdown file containing MDAT placeholder comments. |
| `collapse` | `<files..>` `[options]` | Collapse MDAT placeholder comments. |
| `readme` | `[command]` | Work with MDAT comments in your readme.md. |
| Option | Description | Type | Default |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------- |
| `--config` | Path(s) to files containing MDAT configuration. | `array` | Configuration is loaded if found from the usual places, or defaults are used. |
| `--rules`<br>`-r` | Path(s) to files containing MDAT comment expansion rules. | `array` | |
| `--output`<br>`-o` | Output file directory. | `string` | Same directory as input file. |
| `--name`<br>`-n` | Output file name. | `string` | Same name as input file. Overwrites the input file. |
| `--meta`<br>`-m` | Embed an extra comment at the top of the generated Markdown warning editors that certain sections of the document have been generated dynamically. | `boolean` | |
| `--prefix` | Require a string prefix before all comments to be considered for expansion. Useful if you have a bunch of non-MDAT comments in your Markdown file, or if you're willing to trade some verbosity for safety. | `string` | |
| `--print` | Print the expanded Markdown to stdout instead of saving to a file. Ignores `--output` and `--name` options. | `boolean` | |
| `--verbose` | Enable verbose logging. All verbose logs and prefixed with their log level and are printed to stderr for ease of redirection. | `boolean` | |
| `--help`<br>`-h` | Show help | `boolean` | |
| `--version`<br>`-v` | Show version number | `boolean` | |
<!-- /cli-help -->The command is also aliased under the <!-- cli --> keyword.
This would have equivalent output to the above:
<!-- cli { cliCommand: "mdat", depth: 1 } -->If you embed the rule without any arguments, it will look for the binary file listed in the closest package.json file and run it with --help. This is what you want if you're documenting a package's CLI options in its readme.md file:
<!-- cli-help -->Parsing arbitrary --help output is a bit tricky. The jc project is a heroic collection of output parsers, but does not currently implement help output parsing. It might be interesting to try to contribute mdat's help parsing implementations to jc.
Currently, the parser implementation lives in this repository because I really only use it in the context of my CLI tool readme files. In theory, it really belongs in a separate package.
Issues and pull requests are welcome.
MIT © Eric Mika