Diagrams, math, charts
— still plain text.
Six blocks that render live in your notes and store nothing but their source. For each one: how to insert it, what it does, and exactly what ends up in your .md file.
The source is
the whole file
Every smart block keeps its source in your note and recomputes the picture when the file opens. There is no image cache, no sidecar, nothing to keep in sync — which is why a note with six diagrams in it is still a text file you can email, commit to git, or read in twenty years. The specifications sheet lists what each block writes.
There are two ways in. Press / and pick the block by name, or type the fence directly: three backticks followed by mermaid, chart or calc and then Enter becomes that block, while a ts fence stays an ordinary code block. Callouts and equations have no fence trigger and are inserted from the slash menu.
A smart block is still a block. Drag it by the handle in the left margin, duplicate it with ⌘D, or drop one inside a toggle, a callout or a column — the same moves that work on every other block in the editor.
Editing is the same everywhere: click a rendered block and its source appears underneath it, still rendered above, so you can watch the change land. Escape or a click elsewhere puts it back. While you type something briefly unfinished — a half-written arrow, an unclosed bracket — the last good render stays on screen and the problem shows up as a small warning icon you can hover, rather than a wall of red text that shoves your document around.
> [!WARNING]
> The migration drops the old sessions
> table. Take a backup before you run it.
Say it once,
say it loudly
- Five kinds, changed from the keyboard
- Any blocks inside, not just text
- A plain blockquote to any other reader
Here is the route map we settled on:
```ts
export const ROUTES = ['/', '/docs', '/specs'];
```
Code that looks
like code
- Highlighting for the common languages
- Copy button and language picker
- Line numbers stay out of the file
The area of a circle is $A = \pi r^2$.
The Gaussian integral, for the record:
$$
\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
$$
Equations, set
properly
$$ around a display equation and a single $ around an inline one, so Obsidian, Pandoc and GitHub all read it. Note that Ampersand deliberately does not convert dollar signs as you type — that way $5 stays five dollars.- KaTeX, rendered live
- Display and inline, both editable
- Native editable equations in Word
```mermaid
graph TD
A[Draft] --> B{Reviewed?}
B -->|Yes| C[Ship it]
B -->|No| D[Another pass]
```
A flowchart
you can grep
mermaid. Anything Mermaid draws works — flowcharts, sequence, class, state and Gantt — rendered live beside the text and re-themed automatically for light and dark mode. On disk it is a mermaid code fence, which means the same file renders as a diagram on GitHub, in Obsidian, and in most Markdown previewers without any help from us.- Every Mermaid diagram type
- Follows your light or dark theme
- Renders natively on GitHub
```chart
{
"mark": "bar",
"data": { "values": [
{ "month": "Jan", "sales": 28 },
{ "month": "Feb", "sales": 55 },
{ "month": "Mar", "sales": 43 }
]},
"encoding": {
"x": { "field": "month", "type": "nominal" },
"y": { "field": "sales", "type": "quantitative" }
}
}
```
Numbers, drawn
from the note itself
chart code fence holding the JSON, and you can resize or align it like an image.- The full Vega-Lite grammar
- Bind a chart to a table in the note
- Just JSON in a fenced block
```calc
# groceries
milk: 4.50
bread: 3.20
eggs: 5.00
subtotal
tax: subtotal * 8%
total
```
A calculator
that reads English
subtotal or total on their own line, take a percentage of something, convert units with 100 km in miles, or mix currencies — live rates when you are online, built-in ones when you are not. Lines starting with # or // are comments, handy as section labels — and only what you typed is stored: the results are never written to the file.- Labels, subtotals and totals
- Units, currencies and percentages
- Results recomputed, never saved
One more: ASCII charts
ascii-chart fence. It is the one chart that needs nothing to render it: the picture in the editor and the text in the file are the same thing.On the way out
On the web
Good to know
How do I add a Mermaid diagram to a Markdown file?
In Ampersand, type a forward slash and choose Mermaid Diagram, or type three backticks followed by mermaid and press Enter. Write the Mermaid syntax and the diagram renders beside it as you type. On disk it is an ordinary fenced code block tagged mermaid, which is exactly what GitHub renders natively — so the file works whether or not it is opened in Ampersand.
How is math stored in Ampersand?
As LaTeX between dollar signs, the same convention Obsidian, Pandoc and MathJax use: two dollars around a display equation on its own lines, one dollar around an inline formula. Ampersand typesets it with KaTeX as you write, but nothing else is stored — no image, no cached render — so the equation stays editable text in your file forever.
Will my smart blocks still work in Obsidian or on GitHub?
Yes, with varying degrees of live rendering. Callouts are GitHub-style alerts and Mermaid diagrams are mermaid code fences, both of which GitHub renders natively. Math in dollar signs renders in Obsidian, GitHub and Pandoc. A chart or calc block appears as a fenced block of readable source in other editors rather than a picture, because the source is all Ampersand ever stores.
Do diagrams and charts need an internet connection?
No. Mermaid, KaTeX, Vega-Lite charts and the calculation engine all run inside the app on your own machine, with no service to call. The single exception is converting between currencies in a calc block, which fetches live exchange rates when it can and falls back to built-in rates when you are offline.
What happens to smart blocks when I export to PDF or Word?
They are rendered first, so the exported document matches what you saw. Diagrams and charts become images, calc worksheets are computed, and table formulas resolve to their values. Word gets one upgrade: equations are exported as native OMML, so they stay editable in Word instead of arriving as pictures.
Where does Ampersand store the rendered diagram?
Nowhere. There is no image cache, no sidecar file and no database — a diagram, chart, equation or worksheet is redrawn from its source text each time the note is opened. That is why moving, syncing or emailing the .md file never breaks anything: the text really is the whole document.
Can I chart the numbers in a table?
Yes. Put the cursor under a table, type a slash and choose Chart from table, and Ampersand builds a chart from that table’s columns. The chart stays bound to the table, so editing a number redraws it. The binding travels inside the chart’s own specification, in a field the Vega-Lite standard ignores, so the block stays a valid spec.
Put a diagram
in your next note.
Every smart block is free, in a file that stays yours. Download Ampersand, type three backticks and mermaid, and watch it draw.
Free to start · Mac, Windows & Linux · No account required