* a bullet list is a paragraph too
* second item
```
Leading and trailing blank lines are ignored, and several consecutive blank
lines still count as a single break.
### Inline formatting
Light markdown works in any text, list item, caption, cell or box title:
```text
**bold** *italic* `code` [a link](https://revealjs.com)
[accented]{.accent} [red]{color=#c0392b} [large]{size=1.4em}
[big]{.lede} [small]{.sm}
```
- `[text]{...}` spans accept `.class` tokens (added as CSS classes — themes
provide roles such as `.accent`, `.lede`, `.sm`), `color=` and `size=`.
- Math spans (`$…$`, `$$…$$`) and HTML tags are left untouched.
- Escape a marker with a backslash: `\*`, `` \` ``, `\[`.
- The whole layer can be disabled per deck with `> markdown: false`.
### Math
`$inline$` and `$$display$$` math render with KaTeX. A bare `$$ … $$` line
produces a centered display equation; for a framed, theme-accented equation
box see [Callout boxes and framed equations](#callout-boxes-and-framed-equations).
Your LaTeX macros can be reused with [`> macros:` / `> macro:`](#katex-macros).
### Sizes and alignment
`> size:` sets a relative font size and `> align:` sets the alignment
(`left`, `center`, `right`, `justify`). `size` accepts a factor (`0.8`,
`120%`) or a **role name** — `title` (1.6), `lede` (1.25), `body` (1),
`sm` (0.8), `fine` (0.65). Their **scope depends on where they appear**:
- **Attached to a paragraph** (immediately before its content, with no
blank line in between): they affect only that paragraph.
- **Alone** (followed by a blank line) at the top of a slide or a column:
they become the default for that slide or that block.
- **Inside a `> … > end:` block** (callout box, card, fragment, table
cell): they apply from that line to the end of the block —
`> size: reset` / `> align: none` returns to the block's default.
- **In the settings block**: they become the presentation default.
`size` factors cascade multiplicatively (presentation × slide × block ×
paragraph).
```text
=== Sizes
> size: 0.8
> align: right
This paragraph is 80% of the base size and right-aligned.
> size: 0.5
* This list is half size…
* …and so is this item.
```
Images in a paragraph fill the block width by default and scale together
with the block font; you can still resize any of them with an explicit
width, e.g. `- ` and `
- ` tags.
```html
* Main point
* Supporting detail
* Second detail
* Fine detail
```
Prefix a bullet's text with `+` (optionally `+N`) to reveal that single item as
a fragment — it appears on click, in document order or at step `N`, just like the
`+` flag on cards, layers and callouts:
```html
* Shown immediately
* + Revealed on the next click
* +2 Revealed at step 2
```
Write `* \+ text` for a literal leading "+".
### Highlighted block
Use `[ ... ]` on a single line to produce a highlighted block.
```html
[ This is an important point. ]
```
### Code snippets
Use `@@` fences for code blocks. Optional language names or reveal.js
attributes can follow the opening fence.
```html
@@ python data-line-numbers
print('Hello')
for value in range(3):
show(value)
@@
```
## Columns
Use `||` to start and close a multi-column block. A line starting with `|`
starts the next column. Widths are optional; without them, columns share
the available width equally.
```html
||
Column A
* Velocity rule * Orientation rule |Column B
* Discrete state * Grid update || ``` Each block fills the full height of the central area and shrinks its own font until its content fits (per-block scaling). Blocks are spread across the full slide width, with an equal spacing at the edges and between them (`column-spacing`, a slide parameter). Set `> column-width: auto` on the slide to let Revealer rebalance the block widths so their font sizes come out as even as possible. Inside a column, bullet lists always start on their own line (they are rendered as block elements), so a list written right after a line of text does not flow next to it. You can still provide explicit widths. They are used as CSS `flex-basis` values: ```html || 30% Narrow column | 65% Wide column || ```
Inside a multi-column block, each column can choose its own size and
alignment:
```html
=== Comparison
||
> align: left
Left column
|
> align: justify
Longer text in the right column can be justified.
||
```
### Layout parameters
A slide is organised as a central area (the space left free by the optional
header and footer) filled with one or more **blocks** (columns). Each block
holds a stack of **paragraphs** and shrinks its own font until it fits. The
geometry is controllable:
| Command | Scope | Default | Description |
| --- | --- | --- | --- |
| `> header-height:` *fraction* | presentation | current look | **Header band height**, as a fraction of the slide height. |
| `> footer-height:` *fraction* | presentation | current look | **Footer band height**, as a fraction of the slide height. |
| `> header-margin:` *fraction* | slide | `0.05` | **Vertical breathing margin** between the header/footer and the central area, as a fraction of the slide height. |
| `> column-spacing:` *fraction* | slide | `0.05` | **Horizontal spacing** used at the edges and between blocks, as a fraction of the slide width. |
| `> column-width:` `equal`\|`auto` | slide | `equal` | **Block widths.** `equal` splits the width evenly; `auto` rebalances widths so the per-block font scales are as even as possible. |
| `> paragraph-spacing:` *number* | slide → block | `0.5` | **Spacing between paragraphs**, in line-heights. Defined inside a column block, it applies to that block only. |
| `> size:` *factor* | contextual | `1` | **Relative font size** multiplier (e.g. `0.8`, `120%`, `lede`). Cascades multiplicatively across scopes. |
| `> align:` `left`\|`center`\|`right`\|`justify` | contextual | inherited | **Text alignment.** |
## Layout DSL: filling the canvas
By default a slide lays its content out as [paragraphs](#paragraphs). For
figure-heavy slides that need exact geometry, `> fill` switches the slide
body to a full-height flex column, and `> row` / `> col` build a layout
grid whose heights resolve against the canvas:
```html
=== A figure-heavy slide
> fill
> row
> col 2/5 center
! Media/setup.png fill contain
> col 3/5
!! Media/experiment.mp4 | The experiment
> end: row
```
- `> fill [between|center|around|end]` — the optional keyword sets the
vertical distribution of the slide body.
- `> row [+[N]] [gap] [h=NNN]` opens a row of columns; `h=` pins the row
height (useful to keep content aligned across consecutive slides).
- `> col [size] [center] [relative] [clip] [+[N]]` starts the next column.
Sizes accept fractions (`2/5`), percentages, lengths (`300px`) or bare
flex weights; without sizes, columns share the width equally. `center`
centers the column content vertically; `relative` + `clip` let the
column host an absolutely-positioned overlay.
- Rows nest: a `> row` inside a column splits it further.
- `> end: row` closes the row.
- `> space` adds vertical whitespace in the flow. Bare `> space` is a
*filling* spacer (`flex: 1`) — it absorbs the free vertical space, so it
pushes blocks apart, centres one, or pins one to the bottom. `> space: 40px`
(also `2em`, `10%`) is a *fixed* gap of that height. Handy between two
consecutive `> grid(…)` blocks, which otherwise sit flush against each
other. (Filling needs a `> fill` slide; a fixed `> space:` works anywhere.)
Inside a `> table(...)` block, `> row` keeps its table meaning (a new table
row); everywhere else it opens a layout row.
The generic `> end: name` command closes any named environment (`table`,
`grid`, `row`, `stack`, `pin`, `info`, `warn`, `good`, `eq`, `frag`).
### Grids and cards
`> grid(rows, columns)` builds a grid of cards — like a table, but with
card styling and optional per-card fragment reveal:
```html
> grid(2,2) compact
> gap: 18px
> card
A bordered card
> card plain
! Media/logo.png h=80px
> card accent +
This card has an extra CSS class and reveals as a fragment
> card +: #EFF4FF
A fragment card with a background colour
> end: grid
```
Without `compact` the grid fills the slide; with it, the grid sizes to its
content and can sit next to other blocks. `plain` renders a chrome-less
cell. Any other token on `> card` is added as a CSS class, so themes can
offer card variants.
### Stacks and pins
`> stack` overlays several media layers in one cell, cross-fading as
fragments — convenient to build up a figure step by step:
```html
> stack h=400px
> layer
! Media/base.png fill
> layer +
! Media/with-annotations.png fill
> layer + clear
! Media/grid-overlay.svg fill contain
> end: stack
```
A fragment layer is opaque by default, hiding the layer beneath; `clear`
keeps it transparent (a see-through overlay). `h=` pins the stack height,
otherwise it fills its flex parent.
`> pin: x% y% [w%] [+]` places an absolute overlay with its center at the
given percentages of the slide body — annotations, arrows, badges:
```html
> pin: 75% 20% 15% +
An annotation revealed as a fragment
> end: pin
```
## Images and videos
`! path` inserts an image and `!! path` a video, each on a single line,
with optional flags, a fixed size and a caption. Media paths are relative
to the presentation folder.
```html
! Media/figure.png | A captioned figure
! Media/logo.png h=80px
!! Media/movie.mp4 loop | A movie that loops
```
| Flag | Effect |
| --- | --- |
| `fill` | Fill a sized parent (a grid card or a layout region), cropping as needed. |
| `contain` / `cover` | `object-fit` behaviour: fit without cropping / crop to fill. The default is `contain`, or `cover` when `fill` is set. |
| `top` | Anchor the media to the top of its box (`object-position`). |
| `h=...` / `w=...` | Fixed height / width (`px`, `em`, `%`, `vh`, `vw`), e.g. a logo strip. |
| `+` / `+N` | Reveal the media as a fragment (optionally with an explicit index). |
| `loop`, `autoplay`, `controls` | Video playback options. Videos are always muted, play inline, autoplay when their slide or fragment is shown and reset when it is hidden. |
A trailing `| caption` adds a caption, styled as a figure caption (or as a
card label when the media sits inside a card).
`! fig.pdf` works too: PDF figures are converted to SVG on the fly and
cached, so TikZ output and matplotlib PDFs drop straight in. Together with
`> build:` hooks and the theme-matched matplotlib styles this forms the
[figures pipeline](figures.md) — slides that regenerate their own figures
and never drift out of sync with the analysis.
## Fragments
Most block shortcuts accept a trailing `+` (reveal as a fragment) or `+N`
(fragment with an explicit `data-fragment-index`, for simultaneous or
out-of-order reveals): `! image.png +2`, `> col 2/5 +`, `> row +`,
`> info + Title`, `> eq +3`, `> card +`, `> layer +`, `> pin: 50% 50% +`.
To wrap arbitrary content in a fragment, use `> frag [N]`:
```html
> frag 1
This whole block appears as one fragment, math included: $x^2$.
> end: frag
```
The [browser editor](editor.md)'s fragment drawer (`F`) lists and reorders
a slide's whole reveal sequence.
## Callout boxes and framed equations
`> info`, `> warn` and `> good` produce coloured callout boxes with an
optional bold title; `> eq` frames an equation with the theme accent:
```html
> info Dataset
African elephant, Kruger National Park
> end: info
> eq +
E = mc^2
> end: eq
```
The `> eq` body is wrapped in `$$ ... $$` automatically when it contains no
`$`. A bare `$$ ... $$` line produces a plain centered equation without the
frame. Callout and equation boxes accept the `+` / `+N` fragment flag; a
title after the flag becomes the box title.
## Tables
Use `> table(rows, columns)` to start a table environment. Cells are
centered both vertically and horizontally, and the table fills the
available slide area. `> margin:` and `> border:` configure the current
table and must appear inside the table block. `> cell:` starts a new cell,
with an optional background colour. `> row:` starts a new row and its first
cell. `> end: table` closes the table explicitly, but the table is also
closed automatically at the end of the slide.
```html
> table(2,3)
> margin: 2rem
> border: true
> cell: #f5f5f5
Cell A
Centered text > cell * Item 1 * Item 2 > cell: #eaf3ff $E = mc^2$ > row Bottom left > cell: #fff3cd Bottom center > cell Bottom right > end: table ``` `> border: false` keeps the grid invisible. Cell background colours default to transparent.
## Citations
Use `> cite:` inside a slide to register BibTeX entries. In the visible
text, place markers with `
See [Bibliography](bibliography.md) for BibTeX setup and bibliography
slides.
## Speaker notes
Use `> notes:` to mark the rest of the slide source as speaker notes. The
optional value sets the notes font size for that slide (presentation
default: `> notesSize:`).
```html
=== Main result
The visible slide content goes here.
> notes: 1.1em
Remember to explain the intuition before showing the equation.
```
## Raw slide attributes
Use `> attr:` to append raw attributes to the generated `` element. This is useful for reveal.js features that are not exposed through a dedicated Revealer shortcut. ```html === Auto-animated step > attr: data-auto-animate Same element, next state.```
## Inline SVG and animation
Use `> svg:` to embed an SVG file inline at the position of the directive
(the path is relative to the presentation folder), then reveal or
transform its elements step by step with repeatable `> animate:` lines,
optionally hiding some elements up front with `> hide:`:
```html
=== Animated SVG
> svg: Media/Animated/demo.svg
> hide: #dot, #arrow
> animate: #box fill:#0F4C75
> animate: #dot opacity:1; fill:#c0392b @ 1s
> animate: #arrow opacity:1 @ 300ms
Reveal SVG elements step by step.
```
See [SVG animation](svg.md) for the full selector and duration syntax.
## Including other files
`> include: file.pres` replaces the line by the file's contents at build
time (recursive; paths resolve relative to the including file and must stay
inside the deck folder). It is made for lecture courses: keep each lecture
in its own `.pres` and assemble a master deck — see
[Recipes › Assembling a lecture course](recipes.md#assembling-a-lecture-course-with-include).
Included slides rebuild on save like the main file, but are **read-only in
the browser editor** — edit their own file instead.
## KaTeX macros
Reuse your LaTeX macros in the settings block, either from a `.tex` file of
`\newcommand` definitions (relative to the deck folder) or inline —
`> macro:` can be repeated:
```text
> macros: defs.tex
> macro: \half \frac{1}{2}
> macro: \R \mathbb{R}
```
Argument counts (`[2]`) can be declared but are dropped: KaTeX infers arity
from `#n` in the body. Custom `> katex: { ... }` options merge with the
bundled-KaTeX config and the macros instead of replacing them.
## Build diagnostics
The build never fails on a syntax mistake — but it no longer stays silent
either. Anything the parser has to drop or reinterpret prints a
`Warning: line N: …` in the terminal (both `revealer build` and the live
`revealer serve` log):
- an unrecognized `>` directive (e.g. a typo like `> grid(a,b)`), with a
hint when it looks like a construct child outside its parent
(`> card` without a `> grid`);
- a stray `> end: name` that closes nothing;
- a callout or equation block that is never closed **and** swallowed the
next construct into itself (auto-closing at a slide or column boundary
is fine and stays silent);
- a bare `> space` outside a `> fill` slide (it only *fills* there —
use `> space: ` elsewhere); - a media path (`!` / `!!`) that does not exist on disk.