Bump
Search…
Markdown support
Use of markdown helps create comprehensive and structured API documentation.
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.

Common Markdown syntax support

Formatting
Markdown syntax
Rendering
bold
**bold**
bold
italic
_italic_
italic
link
[links](https://bump.sh)
links
inline code
̀ inline code ̀
inline code
highlight
==highlight==
highlight
strike-through
~~strikethrough~~
strikethrough
footnote
Footnote[^1]
Footnote¹ ¹: Content of the first footnote
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.
1
```json
2
{
3
"hello": "world",
4
"number": 1,
5
"boolean": true
6
}
7
```
Copied!
will render:
1
{
2
"hello": "world",
3
"number": 1,
4
"boolean": true
5
}
Copied!

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.
1
> info
2
> this is an important information to **standout**
Copied!
will render:
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:
1
openapi: 3.1.0
2
info:
3
title: Bump API documentation
4
version: 1.0.0
5
description:
6
$ref: "./docs/introduction.md"
7
x-topics:
8
- title: Getting started
9
content:
10
$ref: "./docs/getting-started.md"
11
- title: Use cases
12
content:
13
$ref: "./docs/use-cases.md"
14
example:
15
$ref: "./docs/use-cases-examples.md"
16
servers:
17
...
18
paths:
19
...
Copied!
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.
Last modified 5mo ago