# Markdown in guides

Pages are rendered by a safe Markdown renderer. Raw HTML is never passed through, so what a page can do is what this table says.

## What's rendered

| You write | You get |
| --- | --- |
| `#` to `####` | Headings, each with an anchor. The page's contents list shows the `##` and `###` ones. |
| Text separated by blank lines | Paragraphs. |
| `*em*`, `**strong**`, backticks | Emphasis, strong text and inline code. |
| A fence of three backticks with a language | A code block, with the language as its class. |
| Lines starting with `-`, `*`, `+` or `1.` | A flat list. |
| A table with a `---` row | A table, with column alignment. Cells hold inline text only. |
| Lines starting with `>` | A blockquote, up to three deep. |
| `> [!NOTE]`, `> [!TIP]` or `> [!WARNING]` on a quote's first line | A callout. |
| `---` alone on a line | A horizontal rule. |
| `![alt](_images/diagram.png)` | An image from the folder. |
| `[text](other-page#anchor)` | A link to another page, checked at build. |
| `[text](https://…)` or `mailto:` | A link out. |

## What isn't, and what to do instead

| Not supported | Instead |
| --- | --- |
| Nested lists: an indented item is plain text. | Make the sub-point its own sentence, or a table row. |
| A list item over two lines: the next line ends the list. | Keep each item to one line. |
| Code inside a list item: the fence ends the list, and a numbered list after it starts again at one. | Use `### 1.` headings for steps with code, each followed by its fence. |
| Raw HTML and HTML comments: they show as text. | Use Markdown, or leave it out. |
| Bare URLs, strikethrough, task lists, footnotes and hard line breaks. | Write links as `[text](url)`. |
| Other callouts, such as `[!IMPORTANT]`. | Use one of the three. |
| Images from another site: left out, with a warning. | Put the image in the folder. |
| Syntax highlighting and copy buttons. | Nothing: code shows as plain monospaced text. |

A link to a page that doesn't exist builds, but with a warning, and shows as plain text.

## Where this comes from

- `app/reference/_lib/markdown.ts`
- `app/docs/_lib/build.ts`