Skip to main content

Markdown support

Bump supports common Markdown syntax, language color syntax highlighting, and information call-outs. Markdown can be included inside your contract file or as an external reference using dedicated Markdown files. Here's several options that may help.

Common Markdown syntax support​

FormattingMarkdown SyntaxRendering
bold**bold**bold
italic_italic_italic
link[links](https://bump.sh)links
inline codè inline code ̀inline code
highlight==highlight==highlight
strike-through~~strikethrough~~strikethrough
footnoteFootnote[^1]Footnote1
quotes> quotes> quotes

Titles & headings​

  • Heading 1: # A first-level title
  • Heading 2: ## A second-level title
  • Heading 3: ### A third-level title

Multi-line code blocks with language color syntax highlighting​

E.g.

    ```json
    {
      "hello": "world",
      "number": 1,
      "boolean": true
    }
    ```

will render:

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

Information call-outs​

Bump support 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.

E.g.

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

will render:

info

this is an important information to standout

Markdown files as an external reference​

Markdown files can be included as an external reference within your contract document with the $ref syntax $ref: "./path/to/local-markdown.md". In the same way you can extract part of your contract (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 contract api-contract.yml can thus looks like:

openapi: 3.1.0
info:
  title: Bump API documentation
  version: 1.0.0
  description:
    $ref: "./docs/introduction.md"
x-topics:
  - title: Getting started
    content:
      $ref: "./docs/getting-started.md"
  - title: Use cases
    content:
      $ref: "./docs/use-cases.md"
    example:
      $ref: "./docs/use-cases-examples.md"
servers:
  ...
paths:
  ...

With files docs/introduction.md, docs/getting-started.md, docs/use-cases.md and docs/use-cases-examples.md right next to your contract document, you will be able to generate a comprehensive API documentation with nicely formatted content for your users.

It's a great way to include “Topic” sections with handwritten content before the documentation of endpoints/webhooks (or channels in case of an AsyncAPI contract) in dedicated Markdown files. Thanks to the x-topics top-level property in your contract as explained in the dedicated help page.