Have ideas to improve npm?Join in the discussion! »

    @jcmellado/markdown-template

    0.8.0 • Public • Published

    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"

    Install

    npm i @jcmellado/markdown-template

    DownloadsWeekly Downloads

    1

    Version

    0.8.0

    License

    MIT

    Unpacked Size

    124 kB

    Total Files

    44

    Last publish

    Collaborators

    • avatar