# Markdown in descriptions

Descriptions in your OpenAPI document, for the API, a tag, an operation, a parameter, a request body, a schema or a security scheme, are rendered as a safe subset of Markdown. Anything outside it is shown as the text you wrote, never run.

## What's rendered

| You write | You get |
| --- | --- |
| A blank line between paragraphs | Separate paragraphs. Lines next to each other join into one. |
| `*text*` or `_text_` | Emphasis. |
| `**text**` | Strong text. |
| Text in backticks | Inline code. |
| A fence of three backticks or tildes, with an optional language | A code block, with the language as its class. |
| Lines starting with `-`, `*`, `+` or `1.` | A flat list, bulleted or numbered. |
| `[label](https://…)` or `[label](mailto:…)` | A link, marked `rel="nofollow ugc noopener"`. |
| `![alt](https://…)` | A link to the image: images aren't loaded. |

## What's shown as text

| You write | What the reader sees |
| --- | --- |
| Raw HTML, such as `<b>` or `<script>` | The tags as text. |
| A link to anything but http, https or mailto | The label, with no link. |
| Headings, tables, blockquotes and horizontal rules | The characters as you typed them. |
| An indented list item | Plain text: lists don't nest. |

Guides on a hosted docs site get more: headings, tables, blockquotes, callouts and images from the docs folder.

## Where this comes from

- `app/reference/_lib/markdown.ts`
- `app/reference/_lib/html.ts`
- `app/reference/_lib/page.ts`