Markdown support

The generation of your API documentation is based on your API definition, which must adhere to one of the standards we support (OpenAPI/Swagger and AsyncAPI.).

To allow you to enrich your documentation, we support common Markdown syntax, including call-outs and the addition of images, for example.

You can integrate Markdown directly into your API document or as an external reference pointing to Markdown files.

Common Markdown syntax support #

Formatting Markdown Syntax Rendering
bold **bold** bold
italic _italic_ italic
link [links]( links
inline code ̀ inline code ̀ inline code
highlight ==highlight== highlight
strike-through ~~strikethrough~~ strikethrough
footnote Footnote[^1] Footnote[^1]
quotes > quotes > quotes

Titles & headings #

Multi-line code blocks with language color syntax highlighting #


      "hello": "world",
      "number": 1,
      "boolean": true

will render:

  "hello": "world",
  "number": 1,
  "boolean": true

Information call-outs # supports information call-outs (of type info, warn, success or error) with the quote markdown syntax (lines starting with > ) if the first line contains one of the call-out types.


> info
> this is an important information to **standout**.

will render:

this is an important information to standout.

Images #

Use the following syntax to add images in your markdown:

![Alt text](/path/to/image.jpg "Image title")

Please, don’t forget to add an alt-text to your images: this description helps make them accessible to all your readers.

Image sizing #

If you want to manually set the size of your image you can use our custom =dimension parameter just before the closing parenthesis as:

![Alt text](/path/to/image.jpg "Image title" =dimension)

=dimension uses the following syntax:


for instance using =100pxx50px where

At least one height or width parameter is mandatory, everything else being optional.

=100pxx50px   # with everything
=100x50       # without unit
=100          # without height (x separator not needed) and unit
=100px        # without height
=x50          # without width and unit
=x50px        # without width
  • If you don’t specify a unit it will default to pixel.
  • If you don’t specify width or height, the other value will be a ratio calculated from the original size of the image so it doesn’t shrink.

You can use any of the following CSS length units as unit:

Absolute units:

Relative units:

Markdown files as an external reference #

Markdown files can be included as an external reference within your API definition with the $ref syntax $ref: "./path/to/".

In the same way you can extract part of your API definition (usually JSON schema of your models into dedicated *.yaml or *.json files), you can extract your markdown content into dedicated files too.

E.g. Your OpenAPI file api-contract.yml can thus looks like:

openapi: 3.1.0
  title: Bump API documentation
  version: 1.0.0
    $ref: "./docs/"

These files will be rendered within your documentation as if they were part of your API definition.