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.