markdown.bz

Markdown sharing guides / Share Mermaid and math

How to share Mermaid diagrams and math in Markdown

markdown.bz renders Mermaid code blocks as diagrams, and $...$ and $$...$$ as KaTeX math. You can share design documents with diagrams and equations in the browser, even with people who do not have a dedicated editor.

1. Wrap Mermaid in a code fence

```mermaid
flowchart LR
  A[Add Markdown] --> B[Preview]
  B --> C{Looks right?}
  C -- Yes --> D[Create share URL]
  C -- No --> A
```

Make the opening line ```mermaid and the closing line ```. Regular code blocks, and blocks without mermaid, do not become diagrams. For flowcharts, sequence diagrams and the like, check the syntax with a small diagram first, then add more elements.

2. Write inline and block math

Write inline math like $E = mc^2$.

Block math:

$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

Wrap short expressions within a sentence in single $ signs, and put $$ before and after standalone expressions. If you send expressions containing backslashes from JSON or a program, you also need to escape them for that language.

3. Preview before publishing

  1. Add your Markdown on the Upload page.
  2. Click Preview & settings and check that the Mermaid code has turned into a diagram.
  3. Compare the symbols, subscripts, fractions and line breaks in the math with the source.
  4. Check that nothing sticks out too far horizontally at smartphone width.
  5. If everything looks right, create the share URL.

You can see how these actually render in the Markdown rendering examples before publishing.

4. What to check if it does not render

SymptomWhat to check
Mermaid stays as codeCheck that the opening line is exactly ```mermaid
The diagram shows an errorCut down on brackets, arrows and quotes, and build up from a minimal diagram
Syntax error in a labelWrap labels that contain symbols in quotes, or replace them with plain text
Math stays as textCheck that every $ is paired, and check the spaces and line breaks around it
Backslashes disappearEscape \ correctly in your JSON or source code

5. Tips for sharing design documents

  • Do not rely on diagrams alone; explain the purpose and the reasoning in the text as well
  • Split huge diagrams into several smaller ones
  • Remove internal host names, system configuration details and confidential information from documents for outside readers
  • You can fix a published document from "My shares" and keep the same URL; the before-and-after diff is published as change history
  • Keep originals that need long-term storage somewhere else, such as Git

Share Markdown with Mermaid and math

Last reviewed: / Reviewed by the markdown.bz team