Mermaid Diagrams & LaTeX Math in Markdown: Copy-Paste Templates (2026)
A tutorial on adding diagrams and equations to Markdown using ready-made libraries — browse and copy Mermaid templates and KaTeX/LaTeX equations, then validate them before you commit.
Diagrams and equations make technical Markdown far clearer — but the syntax is hard to remember and easy to get wrong. Instead of writing Mermaid or LaTeX from scratch every time, start from a working template and edit. This tutorial covers the inventories tool group: the diagram inventory of Mermaid templates and the math inventory of KaTeX/LaTeX equations.
Why start from a template?
| From scratch | From a template |
|---|---|
| Recall exact syntax | Pick a working example |
| Debug silent failures | Edit known-good source |
| Slow | Fast |
Mermaid fails silently (a syntax error renders nothing), and LaTeX is notoriously fiddly. Copy-paste libraries flip the workflow: start with something that already renders, then change the content.
Part 1: The diagram inventory
The diagram inventory is a curated catalog of Mermaid templates — copy any block straight into your Markdown:
- Flowcharts — processes and decisions.
- Sequence diagrams — request/response, interactions over time.
- Class & ER diagrams — data models.
- State diagrams — lifecycles.
- Gantt — project timelines.
- Mindmaps, user journeys, git graphs, and more.
Using a template
```mermaid
sequenceDiagram
participant Client
participant API
Client->>API: POST /render
API-->>Client: 200 { html }
```
- Browse the inventory and copy the closest match.
- Edit the labels and arrows.
- Validate with the Mermaid validator — critical, because errors render as nothing on GitHub.
The Mermaid Markdown guide explains the diagram types and where they render (GitHub, GitLab, Notion, Obsidian).
Part 2: The math inventory
The math inventory is a library of ready-to-use LaTeX equations, rendered with KaTeX, across:
- Algebra — quadratic formula, summations.
- Calculus — derivatives, integrals, limits.
- Linear algebra — matrices, vectors.
- Statistics — distributions, expectation.
- Trigonometry and physics.
Inline vs block math
Inline: the complexity is $O(n \log n)$.
Block:
$$
\int_0^1 x^2 \, dx = \frac{1}{3}
$$
- Find the equation in the inventory.
- Copy the LaTeX and adjust variables.
- Choose inline (
$…$) or block ($$…$$) placement.
Where math renders: GitHub (limited), GitLab (native KaTeX), Obsidian, Notion, and the Markdown editor. Check delimiter usage with the math detection in the editor preview before publishing.
Part 3: Validate before you commit
Both diagrams and equations are silent-failure-prone, so validation is the most important step:
- Mermaid: the validator runs the official parser and reports line-level errors.
- Math: preview in the editor — KaTeX shows a render error inline if a command is wrong.
Committing an unvalidated diagram is the #1 reason "the diagram disappeared on GitHub."
A real workflow: documenting a system
Adding an architecture diagram and a performance equation to a README:
- Diagram: copy a flowchart from the diagram inventory, edit the nodes, validate.
- Equation: copy a complexity formula from the math inventory, set your variables.
- Preview the whole README in the editor.
- Audit the result with the README health score.
- Commit — and if it feeds a docs site, lint in CI.
Platform support at a glance
| Platform | Mermaid | KaTeX math |
|---|---|---|
| GitHub | ✅ | limited |
| GitLab | ✅ | ✅ native |
| Obsidian | ✅ (plugin) | ✅ |
| Notion | ✅ | ✅ |
| Markdown Viewer editor | ✅ | ✅ |
When a target doesn't support live rendering, export the diagram/equation as an image — but keep the source in a comment so it stays editable.
Common mistakes
1. Committing unvalidated Mermaid. It renders as nothing on error — always validate.
2. Wrong math delimiters. $…$ is inline, $$…$$ is block — mixing them breaks rendering.
3. Assuming universal support. GitHub's math support is limited; check the platform.
4. Writing from scratch. Start from a template — faster and fewer errors.
5. No fallback image. For platforms without live rendering, export an image and keep the source.
Related articles
- Mermaid Markdown guide — diagram types and rendering
- Advanced workflows tutorial — diagram validation in context
- GitLab Markdown guide — native KaTeX math
- Author & publish tutorial
- Edit & preview tutorial
Quick reference
| Need | Tool |
|---|---|
| Diagram templates | Diagram inventory |
| Validate diagram | Mermaid validator |
| Equation templates | Math inventory |
| Preview math | Editor |
Don't memorize Mermaid or LaTeX — start from a template that already works, edit it, and validate before you commit. The inventories turn diagrams and equations from a syntax chore into a copy-paste-edit task.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
Write Mermaid flowcharts, sequence diagrams, and Gantt charts in Markdown — GitHub README syntax, supported diagram types, styling, limits, and troubleshooting broken renders.
A tutorial on bridging Markdown to and from other markup formats — Atlassian Confluence/Jira wiki markup, forum BBCode, AsciiDoc, and reStructuredText — with migration tips and gotchas.
A tutorial on Markdown as a data format — convert JSON to tables or lists, sort and transpose tables, extract every code block as a file, and track task-list progress for content pipelines.