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:

• AsyncAPI YAML document
• Markdown document
• Static HTML documentation

Server, channel, operation and message bindings for all the supported protocols:

• AsyncAPI YAML document
• Markdown document
• Static HTML documentation

Security schemes for all the supported protocols:

• AsyncAPI YAML document
• Markdown document
• Static HTML documentation

Simple and complex schemas:

• AsyncAPI YAML document
• Markdown document
• Static HTML documentation

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"