Every syntax extension and component, with live examples.
Mega pages are written in Markdown (CommonMark + GFM) or MDX, with the extensions below. Jupyter
notebooks (.ipynb) and a LaTeX subset (.tex) are converted into the same document model.
Everything is compiled on the server when a draft is previewed or published; readers receive
static HTML with pre-rendered math and code.
A picture can carry its size and placement right after it: width (a percentage of the column, or
pixels), height (pixels), align (left, center or right, on a line of its own) or
float (left or right: the text wraps around it, and it takes the full width on phones). A
picture alone in its paragraph is centered and never taller than the screen. MDX pages cannot use
this syntax.
A floated picture lets the text wrap around it, which suits small diagrams beside the paragraph that explains them. On a phone it takes the full width instead.
A floated picture lets the text wrap around it, which suits small diagrams beside the paragraph that explains them. On a phone it takes the full width instead.
For a caption and a number, wrap the picture in a figure, which takes the same width, align
and float: :::figure[Caption]{#fig-rc width=50% float=left}.
Block components use directive fences. Nest a component inside another by giving the outer fence
more colons:
1
::::exercise[Kirchhoff's voltage law]{#ex-kvl}
2
Write the loop equation.
3
4
:::solution
5
$\sum_k v_k = 0$
6
:::
7
::::
Exercise 1(Kirchhoff's voltage law)
Write the loop equation.
Show solution
The same components are available in MDX as JSX with literal props only. import/export and
{expressions} are rejected, so MDX pages are never executed:
TeX is rendered by MathJax 4 to SVG with hidden MathML for screen readers. These packages are
always available: base, ams, newcommand, color, boldsymbol.
Books opt into extra packages in their settings, and pages can add more in frontmatter
(math: { packages: [physics] }). Optional packages:
mathtools, cancel, amscd, cases, centernot, extpfeil, upgreek, gensymb, textcomp, units, mhchem, physics, braket, bbm, enclose.
Preset
Packages
stem
mathtools, cancel, cases, gensymb, units
physics
physics, braket, units, gensymb, cancel
chemistry
mhchem, units
engineering
mathtools, cancel, units, gensymb, extpfeil
A GitHub-style math fence is display math too, the same as $$ … $$.
A book-level preamble (\newcommand, \DeclareMathOperator…) applies to every page. Wrap
display math in an equation component to number it and refer to it:
mermaid fences render as Mermaid diagrams in the browser (strict security level, themed
from the page). The source stays available in a disclosure and in print.
tikz fences hold TikZ code: a picture's body (\draw …;), an environment
(tikzpicture, tikzcd, circuitikz, a pgfplots axis) or a whole document with
\begin{document}. Lines at the top such as \usetikzlibrary{…}, \usepackage{…} and
\tikzset{…} form its preamble; packages the environments need are added for you. Available
packages: tikz, pgfplots, tikz-cd, circuitikz, chemfig, tikz-3dplot, array, amsmath, amstext, amsfonts, amssymb.
1
```tikz alt="A commutative square" width=40%
2
\begin{tikzcd}
3
A \arrow[r, "f"] \arrow[d] & B \arrow[d, "g"] \\
4
C \arrow[r] & D
5
\end{tikzcd}
6
```
Options: alt="…" (the description screen readers use), width, align and float as for
pictures. Wrap the fence in :::figure[Caption]{#fig-id} to number it.
The editor draws diagrams in your browser (the TeX engine, about 5 MB, loads once) and saves the
drawing with the book when it appears and when you publish; readers get it as part of the page,
in the text colour. A diagram without a saved drawing (an imported page, say) is drawn in the
reader's browser.
chart fences draw charts from data. The options name the chart and its columns; the
body holds the data as CSV, TSV or JSON (the first row names the columns):
1
```chart type=line x=month y="revenue, cost" y-label="k$" alt="Revenue and cost by month"
2
month,revenue,cost
3
Jan,10,5
4
Feb,12,6
5
Mar,15,7
6
```
Option
Meaning
type
line, area, bar, scatter, pie, donut, histogram, heatmap, function (default line)
x, y
The category or x column, and the value columns (comma-separated). Default: the first text column and every number column
group
A column whose values become separate series (long-format data)
value
Heatmaps: the value column (x and y are the two categories)
Expressions use + - * / ^, parentheses, pi, e and sin, cos, tan, asin, acos, atan, atan2, sinh, cosh, tanh, exp, ln, log, log10, log2, sqrt, abs, floor, ceil, round, sign, pow, min, max.
An optional YAML block before the data adds reference lines and per-series styles:
1
```chart type=line
2
---
3
marks:
4
- y: 12
5
label: Target
6
series:
7
cost: { color: 3, dash: true, as: bar }
8
---
9
month,revenue,cost
10
Jan,10,5
11
```
Charts are drawn in the reader's browser and follow the theme, the accent colour and the article
style. Readers can walk through the points with the arrow keys, show the data as a table, open
the chart in the viewer and download the data; without JavaScript and in print the table stands
in. Wrap the fence in :::figure[Caption]{#fig-id} to number it.
A multiple-choice question: a task list where [x] marks the correct options (several make it select-all). A quote indented under an option ( > …) is its feedback; an explain block is shown after answering.
Markdown: :::choice[…]{…}
MDX: <Choice>
Accepts a label: {#id}
Numbered (question counter)
Attribute
Values
Description
difficulty
1, 2, 3
Difficulty from 1 (core) to 3 (challenging), shown as stars.
1
::::choice[Which of these are SI base units?]{#q-si-units}
2
- [x] kelvin
3
- [ ] volt
4
> Derived: one joule per coulomb.
5
- [x] ampere
6
7
:::explain
8
The seven base units are s, m, kg, A, K, mol and cd.