Add Mermaid diagrams to a GitHub README and keep them portable
Write a Mermaid diagram in a GitHub README, decide when to export an image, and keep the source understandable across documentation and presentations.
GitHub can render Mermaid inside a Markdown code fence. That makes a README a useful home for a small diagram whose source should change in the same review as the code it describes.
Choose a question the README should answer. A new contributor usually needs the main request path before a detailed deployment map.
Add a Mermaid fence
Place this in your README:
## Request path
The browser calls the application API. The API reads and writes the database.
```mermaid
flowchart LR
Browser --> API
API --> Database[(Database)]
```
The text before the diagram is useful even when the reader cannot see the rendering. It also forces you to explain what the arrows mean. Here, they represent request or data access direction rather than a chronological sequence of every operation.
GitHub's diagram documentation describes supported Markdown surfaces and how to inspect its Mermaid version. Test in the actual destination because Mermaid versions and integrations can differ.
Keep a portable source version
Basic nodes, arrows, and labels are a good default for a README. If the source uses a renderer-specific extension, confirm what another renderer will do with it.
Flowgraph rich-node labels and custom styling are useful for polished exports, but another host may not interpret those extensions the same way. A preview in one editor is not proof of identical output in GitHub, a wiki, or a slide tool.
There are two reasonable approaches: keep a portable diagram for the README and a presentation variant, or keep one styled source and embed a rendered image where consistent appearance matters. If you maintain variants, name their shared owner so they do not quietly diverge.
Use an image when appearance must stay fixed
An exported SVG or PNG can preserve a chosen theme and layout. Store the image with its source and use descriptive alternative text:

An image does not automatically update when the Mermaid changes. Regenerate it in the same pull request or add a documented build step. Check small labels at normal README width instead of judging only a full-screen editor preview.
Review meaning before formatting
For every architecture change, ask whether a node, arrow, or boundary changed. If a cache now sits between the API and database, update the diagram with the implementation. State whether the picture represents current behavior or a proposed design.
Use Flowgraph Studio to edit and export the diagram, and the flowchart cheat sheet for syntax reminders. Keep the diagram small enough that a contributor can understand its purpose while reading the surrounding README.
More guides
- Animate a Mermaid diagram as a short technical explanationTurn a static Mermaid flow into a captioned explanation. Plan the story, select GIF or video output, and check that animation preserves the system's meaning.
- Explain an Azure background-job architecture with MermaidDraw an illustrative Azure job-processing architecture with API, queue, worker, and storage boundaries. Explain acknowledgment, completion, and failure handling.
- Build a consistent technical carousel with a reusable brand kitCreate readable technical carousel slides using a reusable brand kit. Keep colors, typography, diagrams, and export checks consistent across the series.