# Markdown reference

The Markdown your pages support: headings, lists, code, tables, links, images and callouts, and what is not allowed.

Pages are stored as GitHub-flavored Markdown with one addition, callouts. The editor writes this Markdown for you, and the AI writes it directly. This reference is useful when you read the raw `.md` copy of a page or paste content into the editor.

## Headings

```markdown
## A section
### A subsection
```

The page title is the page's heading, so pages start at level 2. Headings of level 2 and 3 get an anchor link and appear in the **On this page** outline. Deeper levels render but are not listed.

## Text

| Markdown | Result |
| --- | --- |
| `**bold**` | **bold** |
| `*italic*` | *italic* |
| `` `code` `` | `code` |
| `[text](https://example.com)` | An external link, opened in a new tab |
| `[Limits](/reference/limits)` | A link to another page of your docs |

## Lists

```markdown
- A bullet
- Another bullet

1. First step
2. Second step
```

## Code blocks

Use a fenced block with a language so it is highlighted and labeled.

````markdown
```typescript
const answer = 42;
```
````

Highlighted languages: Bash, C, C++, C#, CSS, diff, Dockerfile, Go, GraphQL, INI, TOML, Java, JavaScript, JSON, Kotlin, Markdown, PHP, Python, Ruby, Rust, SQL, Swift, TypeScript, HTML, XML, Vue and YAML. Common aliases such as `sh`, `shell`, `zsh`, `console`, `html`, `svg`, `toml`, `jsonc` work too. Every block has a copy button.

## Tables

```markdown
| Option | Default |
| --- | --- |
| `retries` | `3` |
```

## Block quotes

```markdown
> A quoted passage.
```

## Callouts

Callouts are Docup's own syntax. There are three types.

```markdown
> **Note:** Extra information the reader should know.

> **Tip:** A helpful suggestion.

> **Warning:** Something that can go wrong.
```

> **Note:** This is a note.

> **Tip:** This is a tip.

> **Warning:** This is a warning.

Use them rarely. In the `.md` copy of a page and in `llms-full.txt`, callouts are converted to block quotes such as `> **Note:** text`, so other tools can read them. In the editor, insert one with `/` and choose a callout.

## Images

Images use standard syntax with an absolute `https://` address, or a path that starts with `/`.

```markdown
![Alt text](https://example.com/diagram.png)
```

Images are loaded lazily. Other kinds of address are shown as their alt text. Docup does not host images inside pages; upload site-wide images such as the logo, favicon and social image in [Appearance](/settings/appearance) and [Search and sharing](/settings/search).

## Dividers

A line containing `---` draws a horizontal rule.

## Raw HTML

Raw HTML in a page is not rendered. It is shown as escaped text. This protects your readers and keeps every page consistent. Use Markdown, callouts and tables instead.

## Links the editor understands

The editor's link tool accepts web addresses. For links inside your docs, use the path, starting with a slash, so they keep working when your address changes.