Math, Mermaid & Diagram Embeds

The plain-text diagrams Markdown finally supports

Math (LaTeX-style)

GitHub renders LaTeX math natively (since 2022) using KaTeX. Inline math: $ ... $ . Display math: $$ ... $$ on its own paragraph. The same syntax works on most modern docs platforms (GitLab, Obsidian, Notion, MkDocs Material with the right plugin).

Mermaid diagrams

```mermaid fenced blocks render as flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, state machines, and more. GitHub renders Mermaid natively. Diagram source lives in the file — diff-friendly, version-controlled, no binary export pipeline.

Other diagram dialects

GeoJSON — ```geojson renders a map on GitHub.
STL — ```stl renders 3D models on GitHub.
PlantUML, GraphViz — supported on some platforms (MkDocs with plugin), not GitHub.

Portability tactic: if you ship to a non-GitHub target that doesn't render Mermaid, render the diagram once with mmdc (mermaid-cli) and commit the SVG next to the source. Reference the SVG; keep the source as a fallback. Editable + portable.

Code

Inline and display math·markdown

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

The normal distribution PDF:

$$
f(x) = \frac{1}{\sigma\sqrt{2\pi}} \, e^{-\frac{1}{2}\left(\frac{x - \mu}{\sigma}\right)^2}
$$

Mermaid — flowchart·markdown

```mermaid
flowchart LR
    A[Push to main] --> B{CI passing?}
    B -- yes --> C[Deploy to Vercel]
    B -- no --> D[Block release]
    C --> E[Site live]
```

Mermaid — sequence diagram·markdown

```mermaid
sequenceDiagram
    participant U as User
    participant W as WebUI
    participant B as Backend
    U->>W: send message
    W->>B: POST /api/chat
    B-->>W: SSE stream
    W-->>U: render tokens
```

Render Mermaid to SVG (CLI fallback)·bash

# Install once
npm install -g @mermaid-js/mermaid-cli

# Render a .mmd file
mmdc -i diagram.mmd -o diagram.svg

# Or extract a fenced block from a Markdown file:
# (some editors have 'export diagram as SVG' built in)

Exercise

Take a system you understand well (your auth flow, your CI pipeline, your data model) and write its Mermaid diagram as a fenced block in a Markdown file. Push to GitHub and view it. Then export to SVG with mmdc and commit the SVG next to the source. Reference both in another doc. You now have a portable, editable diagram pipeline.

Math, Mermaid & Diagram Embeds

The plain-text diagrams Markdown finally supports

Math (LaTeX-style)

Mermaid diagrams

Other diagram dialects

Code

External links

Exercise

Progress

Comments 0