@jcmellado/markdown-template
v0.9.0
Published
Markdown template for the AsyncAPI Generator
Downloads
11
Maintainers
Readme
markdown-template
Markdown template for the AsyncAPI Generator.
The template converts an AsyncAPI document into a Markdown document.
The generated Markdown documents can be used to create static HTML documentation websites with Slate or shins.
Usage
Install the AsyncAPI Generator:
npm install -g @asyncapi/generator
Run the generator on your asyncapi.yml
with the template:
ag ./asyncapi.yml @jcmellado/markdown-template -o ./docs
Check the AsyncAPI Generator Documentation to learn more about the available options.
Examples
AsyncAPI specification of fictional API service:
Server, channel, operation and message bindings for all the supported protocols:
Security schemes for all the supported protocols:
Simple and complex schemas:
Parameters
The AsyncAPI Generator allows to pass additional parameters to the template with the -p name=value
option.
Example:
ag ./asyncapi.yml @jcmellado/markdown-template -o ./docs -p slate.enabled=true -p slate.languages="json: JSON,Rust"
The following sections describe the available parameters.
Markdown
Parameter | Description
----------|------------
output | File name for the output file.Default: asyncapi.md
The -o
parameter of the generator specifies the output directory, the -p output
parameter of the template specifies the output filename.Example: -o ./docs -p output=api-1.0.0.md
Sections
Parameter | Description
----------|------------
sections | Comma-separated list of sections to be included in the Markdown document.Default: servers,channels,messages,security,tags,license,termsOfService,contact
Sections are included in the Markdown document in the same order that they appear in the list. Only the listed sections will be included.Example: -p sections=channels,messages,servers,license
sections.server | Comma-separated list of subsections to be included in the servers section.Default: variables,security,bindings
Example: -p sections.server=variables
sections.channels | Comma-separated list of subsections to be included in the channels section.Default: parameters,bindings,messages,publish,subscribe,operation.bindings,operation.tags
Example: -p sections.channels=parameters,subscribe,publish,messages
sections.messages | Comma-separated list of subsections to be included in the messages section.Default: payload,headers,correlationId,bindings,tags
Example: -p sections.messages=headers,payload
Table of Contents
Parameter | Description
----------|------------
toc.headingLevel | Number of heading levels to show in the table of contents.Default: 0
Allowed values: 0
, 1
, or 2
.Example: -p toc.headingLevel=2
Slate/shins
Parameter | Description
----------|------------
slate.enabled | Enables the output of the Slate header in the Markdown document.Default: false
The header contains some parameters used by Slate to build the HTML documentation.Example: -p slate.enabled=true
slate.theme | Name of the syntax-highlighter theme to use.Default: darkula
Example: -p slate.theme=monokai
slate.searchEnabled | Enables the search option in the table of contents.Default: true
Example: -p slate.searchEnabled=false
slate.headingLevel | Number of heading levels to show in the table of contents.Default: 2
Currently only supported by shins.Example: -p slate.headingLevel=3
slate.languages | Comma-separated list of languages to add as tabs.Default: null
Example: -p slate.languages="json: JSON"
slate.includes | Comma-separated list of files to include at the bottom of the content.Default: null
Example: -p slate.includes=/extra/info
slate.footers | Comma-separated list of texts to add at the bottom of the table of contents.Default: null
Example: -p slate.footers="Copyright (c) 2020 www.example.com"