Skip to content
Generate API documentation in markdown from apiDoc data
TypeScript JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

@rigwild/apidoc-markdown

npm badge

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

You can’t perform that action at this time.