Capable Markdown

If your team writes documentation in Markdown, diagrams can live in a fenced code block with the language name, exactly as they do in a repository README.

A saved markdown page titled Database Schema Documentation with an introduction, an ER diagram section and a rendered DBML diagram labelled Database Markup Language showing orders and users tables joi — A fenced block renders as a diagram in the saved document, alongside the prose it belongs with.

The block renders as a real diagram on the page, and it stays editable as text.

#When this matters

Teams whose documentation is written in Markdown.
Content imported from a repository, where diagrams are already fenced.
Pages where the source should stay visible next to the picture.

#The detail

A Capable Markdown editor toolbar with formatting buttons, the diagram button highlighted and a Diagram tooltip below it, above an empty field reading write your markdown here. — The toolbar button drops a fenced block in for you, so you do not have to remember the fence or the language tag.

Thing	What happens
Fenced block	Use the language name as the fence info string, such as mermaid.
Rendering	The block renders as a diagram rather than as code.
Editing	Edit the text; the diagram follows.
Supported languages	The text languages, exactly as elsewhere.

#A few things that catch people out

The fence info string is what selects the language. A bare fence renders as code.
draw.io and Excalidraw are canvas formats and do not belong in a fenced block.
This is the easiest path for importing documentation that already contains Mermaid.

Capable Sites

Diagrams on a published site.

Diagrams in Jira

The same editors, on issues.

Examples

Working diagrams you can copy.

It works better next to the rest of Capable.