@rigwild/apidoc-markdown

Generate API documentation in markdown from apiDoc data.

This is an up to date and maintained fork of @martinj/node-apidoc-markdown (which is not maintained). The template was updated with recent apiDoc features thanks to this fork.

The documentation template has been updated. The project was fully rewrote to TypeScript and programmatic usage. Tests were added.

Installation

# Command line utility
yarn global add @rigwild/apidoc-markdown
# or
npm i -g @rigwild/apidoc-markdown

# Programmatic usage
yarn add @rigwild/apidoc-markdown
# or
npm i @rigwild/apidoc-markdown

Then, generate your documentation using your newly added command apidoc-markdown.

Usage

Help message

Generate Markdown documentation from apiDoc data.
Usage: apidoc-markdown -p <path> -o <output_file> [-t <template_path>] [--multi] [--createPath] [--prepend <file_path>]

Options:
  --version       Show version number                                                                                                                [boolean]
  --path, -p      Path to generated apiDoc output directory. Where `api_data.json` and `api_project.json` resides.                         [string] [required]
  --output, -o    Output file or directory to write output to.                                                                             [string] [required]
  --template, -t  Path to EJS template file, if not specified default template will be used.                        [string] [default: "templates/default.md"]
  --prepend       Path to file content to add before route groups documentation.                                                                      [string]
  --multi         Output one file per group to the `output` directory.                                                              [boolean] [default: false]
  --createPath    Recursively create directory arborescence to the `output` directory.                                              [boolean] [default: false]
  -h, --help      Show help                                                                                                                          [boolean]

Examples:
  apidoc-markdown -p doc/ -o doc.md                         Generate from `doc/` apiDoc output to `./doc.md`
  apidoc-markdown -p doc -o multi/ --multi --createPath     Generate from `doc/` apiDoc output to `./multi/<group>.md`

@rigwild/apidoc-markdown - https://github.com/rigwild/apidoc-markdown

Command-line arguments

Option	Alias	Description
--apiDocPath <apiDoc_path>	-p	Path to generated apiDoc output directory. Where api_data.json and api_project.json resides.
--output <output_path>	-o	Output file or directory to write output to
--template <template_path>	-t	Path to EJS template file, if not specified default template will be used.
--prepend <file_path>		Path to file content to add before route groups documentation
--multi		Output one file per group to the output directory
--createPath		Recursively create directory arborescence to the output directory
--help	-h	Show help message

Programmatic usage

This project has been fully refactored to support programmatic use. Every functions are available in the ./src/generator.ts directory and are exported.

Example	Description
Basic generation	Generate documentation from the included example data
Basic generation with ordering	Generate documentation from the included example data with order settings
One file per group generation	Generate documentation from the included example data, one file per group

Configuration

Endpoints order

You can choose the order in which the documentation endpoints will be generated by adding an order key in api_project.js. See example.

Example

Generate documentation from the included example data. View generated example.

apidoc-markdown -p examples/basic -o examples/basic/example.md

Generate documentation from the included example data with ordering setting. View generated example.

apidoc-markdown -p examples/ordered -o examples/ordered/example.md

Generate documentation from the included example data, one file per group. View generated example.

apidoc-markdown -p examples/multi -o examples/multi/output --multi --createPath

Contribute

Don't hesitate to suggest any feature you would like by creating an issue or a pull request.

License

The MIT license