Skip to content
All posts
4 min read
markdown
tutorial
mermaid
latex
diagrams

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 scratchFrom a template
Recall exact syntaxPick a working example
Debug silent failuresEdit known-good source
SlowFast

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 }
```
  1. Browse the inventory and copy the closest match.
  2. Edit the labels and arrows.
  3. 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}
$$
  1. Find the equation in the inventory.
  2. Copy the LaTeX and adjust variables.
  3. 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:

  1. Diagram: copy a flowchart from the diagram inventory, edit the nodes, validate.
  2. Equation: copy a complexity formula from the math inventory, set your variables.
  3. Preview the whole README in the editor.
  4. Audit the result with the README health score.
  5. Commit — and if it feeds a docs site, lint in CI.

Platform support at a glance

PlatformMermaidKaTeX 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.

Quick reference

NeedTool
Diagram templatesDiagram inventory
Validate diagramMermaid validator
Equation templatesMath inventory
Preview mathEditor

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.