I really like the idea of generating API documentations with simple annotations like apiDoc does.
Unfortunately, apiDoc outputs a big HTML/CSS/JavaScript project which is not ideal when you want to add it to your GIT project.
apidoc-markdown lets you convert data from apiDoc to a nice and portable Markdown documentation! 😊
This project is a full-rewrite fork of @martinj/node-apidoc-markdown, which transfered the npm package name apidoc-markdown to me.
# For the command line utility
yarn global add apidoc-markdown
# npm i -g apidoc-markdown
# For programmatic usage
yarn add apidoc-markdown
# npm i apidoc-markdownThen, generate your documentation using your newly added command apidoc-markdown or programmatically.
Note: Node.js v10+ minimum is required.
Generate Markdown documentation from apiDoc data.
Usage: apidoc-markdown -p <path> -o <output_file> [-t <template_name>] [--multi] [--createPath] [--prepend <file_path>]
Options:
--version Show version number [boolean]
-p, --apiDocPath Path to generated apiDoc output directory. Where `api_data.json` and `api_project.json` resides. [string] [required]
-o, --output Output file or directory to write output to. [string] [required]
-t, --template Name of the template to be used (`default`, `bitbucket`) or path to an EJS template file. If not specified, the default template
is used [string] [default: "default"]
--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 doc.md -t bitbucket Generate from `doc/` apiDoc output to `./doc.md` using the bitbucket template
apidoc-markdown -p doc/ -o doc.md -t ./mytemplate.md Generate from `doc/` apiDoc output to `./doc.md` using a provided template file
apidoc-markdown -p doc -o multi --multi --createPath Generate from `doc/` apiDoc output to `./multi/<group>.md`
apidoc-markdown - https://github.com/rigwild/apidoc-markdown
| Option | Alias | Description |
|---|---|---|
--help |
-h |
Show help message |
--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 |
Name of the template to be used (default, bitbucket) or path to an EJS template file. If not specified, the default template is used (see Examples). |
--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 |
See Examples for usage examples.
Install apiDoc and apidoc-markdown as dev dependencies
yarn add -D apidoc apidoc-markdown
# npm i -D apidoc apidoc-markdownAdd the following script to your package.json file (src is where are stored your source files containing some apiDoc annotations).
{
"scripts": {
"doc": "apidoc -i src -o apidoc-out && apidoc-markdown -p apidoc-out -o DOCUMENTATION.md && rm -rf apidoc-out"
}
}Run the npm script to generate the DOCUMENTATION.md file.
yarn doc
# npm run docGenerate mardown documentation.
generateMarkdown: (config: ConfigurationObject) => Promise<{ name: string, content: string }[]>See ./src/types.
export declare interface ConfigurationObject {
/** apiDoc project JSON data object (`api_project.json` (or legacy `apidoc.json`) file content) */
apiDocProjectData: { [key: string]: any }
/** apiDoc documentation JSON data object (`api_data.json` file content) */
apiDocApiData: { [key: string]: any }[]
/** Name of template to be used (`default`, `bitbucket`)
* or path to EJS template file
* or raw EJS plain text template
* (will use default template if ommitted). */
template?: string
/** Content to add before route groups documentation */
prepend?: string
/** Generate one documentation output per group */
multi?: boolean
}Usage example:
import { generateMarkdown } from 'apidoc-markdown'
const documentation = await generateMarkdown({
apiDocProjectData: { name: 'test', version: '0.13.0', /* ... */ },
apiDocApiData: [{ type: 'get', url: '/define', /* ... */ }],
template: 'my EJS template <%= project.name %> v<%= project.version %>' /* or 'default' | 'bitbucket' or path to template */,
// prepend: 'Prepend this!',
// multi: false
})
// Output
documentation: {
name: string; // Group name
content: string; // Documentation content
}[]
// (if `multi` === false, you get an array with 1 element!)Generate mardown documentation using the file system and creating output file(s).
generateMarkdownFileSystem: (config: ConfigurationObjectCLI) => Promise<{ outputFile: string, content: string }[]>See ./src/types.
export declare interface ConfigurationObjectCLI {
/** Path to generated apiDoc output directory. Where `api_data.json` and `api_project.json` are located */
apiDocPath: string
/** Output file or directory to write output to */
output: string
/** Name of template to be used (`default`, `bitbucket`)
* or path to EJS template file
* or raw EJS plain text template
* (will use default template if ommitted). */
template?: string
/** Path to file content to add before route groups documentation */
prepend?: string
/** Output one file per group to the `output` directory */
multi?: boolean
/** Recursively create directory arborescence to the `output` directory */
createPath?: boolean
}Usage example:
import path from 'path'
import { generateMarkdownFileSystem } from 'apidoc-markdown'
const documentation = await generateMarkdownFileSystem({
apiDocPath: path.resolve(__dirname, 'path', 'to', 'apiDoc', 'output', 'files', 'directory'),
output: path.resolve(__dirname, 'output'),
template: 'default' /* or 'bitbucket' or path to template or raw EJS plain text template */,
// prepend: path.resolve(__dirname, 'path', 'to', 'file', 'to', 'prepend'),
// multi: true,
// createPath: true
})
// Output
documentation: {
outputFile: string; // File path
content: string; // File content
}[]
// (if `multi` === false, you get an array with 1 element!)You can choose the order in which the documentation groups gets generated by adding an order key in api_project.json (or apidoc.json). See example api_project.json and generated example output.
Note: This in only available when generating the documentation to a single output file (the multi mode generates 1 file per group, so there is nothing to sort).
apidoc-markdown requires apiDoc generated data (only api_data.json and api_project.json, you can delete every other files).
apidoc -i src -o apidoc-out
Generate documentation from the included example data (See ./example/basic/example.md).
apidoc-markdown -p test/_apidoc/out -o ./example/basic/example.md
You can select a template by its name by using -t or --template (default, bitbucket)
apidoc-markdown -p test/_apidoc/out -o ./example/basic/example.md -t bitbucket
You can pass the path to your own template by using -t or --template (default, bitbucket)
apidoc-markdown -p test/_apidoc/out -o ./example/basic/example.md -t ./mytemplate.md
You can prepend your documentation with the content of a file using --prepend
apidoc-markdown -p test/_apidoc/out -o ./example/basic/example.md --prepend test/_testFiles/prepended.md
Generate documentation from the included example data, one file per group and creating the parent directory of the output (See ./example/multi).
apidoc-markdown -p test/_apidoc/out -o ./example/multi --multi --createPath
Suggest any feature you would like by creating an issue or a pull request.
When reporting bugs, please fill the issue template correctly with as much info as possible to help me debug and understand what's happening.
⭐ Star the project to help it grow! 😄