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
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
Bump support information call-outs (of type
error) with the quote markdown syntax (lines starting with
> ) if the first line contains one of the call-out types.
> this is an important information to **standout**
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
*.json files), you can extract your markdown content into dedicated files too.
E.g. Your OpenAPI contract
api-contract.yml can thus looks like:
title: Bump API documentation
- title: Getting started
- title: Use cases
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.