How Do You Add and Preview Diagrams in Markdown?

Updated

Add a diagram to Markdown by writing a fenced code block tagged mermaid and putting the diagram definition inside it. In an editor that renders Mermaid — such as Markdown Viewer, which lists Mermaid diagrams among its preview features — the block displays as a drawn diagram in the preview pane instead of as code. The conditions: the editor must support Mermaid rendering, and in Markdown Viewer the diagram rendering is a remote service, so you need a network connection for the diagram to appear.

Write the diagram as a Mermaid code block

The pattern is a standard fenced block whose info string is mermaid:

```mermaid
flowchart LR
  A[Write Markdown] --> B[Preview diagram]
  B --> C{Looks right?}
  C -- Yes --> D[Export]
  C -- No --> A
```

The same block form works for other Mermaid diagram types, for example a sequence diagram:

```mermaid
sequenceDiagram
  participant Author
  participant Editor
  Author->>Editor: Paste Mermaid block
  Editor-->>Author: Render preview
```

Two rules matter more than the diagram syntax itself:

  • The info string must be mermaid. Without it, the editor treats the content as ordinary code and shows it as text.
  • The diagram definition must be valid Mermaid. A syntax error usually produces an error message or blank area in the preview rather than a diagram.

Check the render in the right view

Markdown Viewer offers Edit, Split, and Preview modes in the toolbar. Split is the practical choice while drafting: you type in the editor and watch the diagram update in the preview beside it. Switch to Preview when you want to see the diagram at full width, and back to Edit for changes.

The preview also handles highlighted code and LaTeX math alongside Mermaid, so a document that mixes a diagram, a code sample, and a formula can be checked in one pass.

Export the result

Markdown Viewer exports as Markdown, HTML, PDF, or PNG. Which format to pick depends on what the diagram is for:

Goal Format What to expect
Keep editing later Markdown The Mermaid block stays as source text; it renders again wherever Mermaid is supported
Publish on a web page HTML Check that the diagram appears in the exported page, not just in the editor preview
Share a fixed document PDF The diagram is captured as part of the page
Use the diagram as an image PNG Useful when the diagram needs to sit inside a slide or chat message

If the diagram is the main point of the document, open the exported file and confirm the diagram is present before sending it on.

When the diagram does not render

Work through these in order:

  1. Check the fence tag. A block tagged text, md, or nothing at all will not render as a diagram.
  2. Check the Mermaid syntax. Paste the definition into a minimal test block; if that fails too, the problem is in the definition, not the document.
  3. Check the connection. In Markdown Viewer, remote diagram rendering uses network services, so an offline session can leave the diagram unrendered even though the Markdown is correct.
  4. Check the export. A diagram that displays in preview may not survive every export path; verify the exported file itself rather than assuming.

Keep a backup of the source

Markdown Viewer autosaves ordinary editing on the device, and clearing browser storage can remove locally saved documents. Since a rendered diagram exists only in the preview, keep the Markdown source — with its Mermaid blocks — downloaded as a copy. That way the diagram can be regenerated anywhere Mermaid is supported, regardless of what happens to the browser workspace.