Markdown

The page renders markdown with markdown-it (CommonMark and GitHub tables and strikethrough) plus the extensions below. examples/features.md uses every one of them; preview it to see them all.

GitHub alertsCopy Anchor Link

> [!NOTE]
> Useful information.

> [!TIP]
> Helpful advice.

> [!IMPORTANT]
> Key information.

> [!WARNING]
> Needs attention.

> [!CAUTION]
> Risky consequences.

They look like on GitHub, in the light and the dark theme.

Table of contentsCopy Anchor Link

Put ${toc} (or [[toc]]) on a line of its own to insert a table of contents of the headings. The toc preview option takes markdown-it-toc-done-right options, e.g. { level = { 2, 3 } } to list only ## and ### headings.

Every heading has an anchor link, shown when you hover it.

ListsCopy Anchor Link

- [x] Task lists
- [ ] with checkboxes

Term
: Definition lists

Footnotes and emojiCopy Anchor Link

A claim.[^source] :tada:

[^source]: The footnote.

:name: becomes the emoji of that name.

CodeCopy Anchor Link

Fenced code blocks are highlighted with highlight.js when they name a language:

```rust
fn main() {}
```

Blocks named mermaid, chart, dot, plantuml, flowchart or sequence-diagrams become diagrams.

MathCopy Anchor Link

Math is rendered with KaTeX, including chemistry with mhchem:

Use $...$ or \(...\) for inline formulas, and $$...$$ or \[...\] for display equations. Display markers start at the beginning of a line; the equation can be on the same line or span multiple lines. Both styles work without configuration and can be mixed in the same document.

So that escaped brackets in prose stay text, a \[...\] line holding only letters, digits, spaces and colons (such as \[1\] or \[TODO: fix\]), or one starting with TODO/todo, is not treated as math. Use $$...$$ for such formulas.

Inline: $E = mc^2$, \(a^2 + b^2 = c^2\), and $\ce{CO2 + C -> 2 CO}$.

$$
\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
$$

\[
E = mc^2
\]

A formula with an error is shown in red instead of breaking the page. KaTeX options, such as macros, go in the katex preview option.

ImagesCopy Anchor Link

![relative to the markdown file](./images/logo.png)
![absolute, or from a parent directory of the file](/images/logo.png)
![with a size](./images/logo.png =200x100)
![only the width](./images/logo.png =200x)
<img src="images/logo.png" width="50">

• Relative paths are resolved against the markdown file's directory, or images_path when it is set.
• A path starting with / is an absolute path when that file exists. Otherwise it is looked up in the markdown file's directory and its parents, as in many static site generators.
• =WIDTHxHEIGHT sets the size; either side may be left out, and both may be percentages.
• Only images, audio and video are served from disk: an image path that points at any other kind of file gets nothing.

Front matterCopy Anchor Link

YAML front matter at the top of the file is hidden by default. Set front_matter in the preview options to change it:

• "panel" shows it in a collapsed panel above the document
• "raw" renders it as markdown

opts = { preview_options = { front_matter = "panel" } }

Raw HTMLCopy Anchor Link

HTML in the markdown file is rendered, including <details>, <kbd> and <img>. To preview files you don't trust, turn it off:

opts = { preview_options = { mkit = { html = false } } }

mkit takes any markdown-it option. linkify (turning URLs into links) and typographer (smart quotes and dashes) are on by default.