# Markdown basics

> For the complete documentation index, see [llms.txt](https://preview.writedocs.io/llms.txt).

How to write a page - text, headings, links, lists, tables, images and HTML - and what .md and .mdx files can each do.

Pages are written in Markdown. Everything in standard Markdown works, plus tables, task lists, strikethrough and footnotes.

## `.md` and `.mdx`

| | `.md` | `.mdx` |
| --- | --- | --- |
| Markdown | Yes | Yes |
| HTML | Yes | Yes |
| [Components](https://preview.writedocs.io/docs/content/components/) - `<Callout>`, `<Card>`, ... | No | Yes |
| [Snippets](https://preview.writedocs.io/docs/content/snippets/) - `import` | No | Yes |
| JavaScript expressions - `{1 + 1}` | No | Yes |

Use `.mdx` for pages with components - most pages. In an `.mdx` file, `{` and `<` start code and components. To write them as text, put them in backticks (`` `{id}` ``) or escape them: `\{`, `&lt;`.

## Text

```md
**Bold**, *italic*, ~~strikethrough~~, `inline code`, and a line break with two spaces at the end of a line.

> A quote, for a remark or a citation.
```

**Bold**, *italic*, ~~strikethrough~~, `inline code`.

> A quote, for a remark or a citation.

## Headings

The page's `title` is its main heading, so start sections at `##`:

```md
## Install the SDK

### On macOS
```

`##` and `###` headings are listed in the table of contents on the right. Every heading gets an anchor from its text - `## Install the SDK` is `#install-the-sdk` - and a link icon that appears on hover, to copy a link to it.

## Links

```md
[Quickstart](/docs/quickstart/)
[Install the SDK](/docs/sdk/#install-the-sdk)
[Our blog](https://blog.example.com)
<https://example.com>
```

Write links to your own pages from the site's root, starting with `/`. Page addresses end in a slash (`/docs/guides/setup/`), so a relative link like `[Install](install)` on that page points to `/docs/guides/setup/install/` - one level deeper than it looks. [`writedocs broken-links`](https://preview.writedocs.io/docs/cli/#writedocs-broken-links) finds those, and anchors that don't exist.

## Lists

```md
1. Create an account.
2. Copy your API key.
   - Keep it secret.
   - Rotate it every 90 days.

- [x] Install the SDK
- [ ] Send a test request
```

1. Create an account.
2. Copy your API key.
   - Keep it secret.
   - Rotate it every 90 days.

- [x] Install the SDK
- [ ] Send a test request

## Tables

```md
| Plan       | Requests per minute | Support |
| ---------- | ------------------: | :-----: |
| Free       |                  60 |    -    |
| Business   |               1,000 |  Email  |
```

| Plan       | Requests per minute | Support |
| ---------- | ------------------: | :-----: |
| Free       |                  60 |    -    |
| Business   |               1,000 |  Email  |

A colon in the separator row aligns a column: `---:` to the right, `:---:` to the center. A wide table scrolls sideways on a narrow screen. To filter a long table as the reader types, wrap it in a [Searchbar](https://preview.writedocs.io/docs/content/components/searchbar/).

## Images

```md
![The dashboard's home screen](/images/dashboard.png)
![A diagram next to this page](./flow.png)
```

The text in brackets is the image's description for screen readers - [`writedocs a11y`](https://preview.writedocs.io/docs/cli/#writedocs-a11y) reports images without one. Every image opens larger when clicked.

Images can be in any folder of the project - see [Project structure](https://preview.writedocs.io/docs/project-structure/#images-and-other-files). For a caption, a size, or a different image in dark mode, use the [Image](https://preview.writedocs.io/docs/content/components/image/) component.

Images load as the reader gets near them, and keep their place on the page while they do - see [How images load](https://preview.writedocs.io/docs/content/components/image/#how-images-load).

## Footnotes

```md
Rate limits are counted per API key.[^1]

[^1]: Keys created before 2024 share one limit per account.
```

Rate limits are counted per API key.[^1]

[^1]: Keys created before 2024 share one limit per account.

The notes are listed at the bottom of the page, linked both ways.

## Code

Fenced code blocks get highlighting, titles, line highlighting, diffs and more - see [Code blocks](https://preview.writedocs.io/docs/content/code-blocks/). Inline code goes in single backticks.

## HTML

HTML works in both `.md` and `.mdx` pages:

```html
<details>
  <summary>Show the full response</summary>

  The response includes ...
</details>

Press <kbd>Ctrl</kbd> + <kbd>K</kbd> to search.
```

In an `.mdx` file, write HTML the way JSX does: `className` instead of `class`, every tag closed (`<br />`, `<img ... />`), and `style={{ color: "red" }}` as an object.

## Styling with classes

Utility classes style an element without a stylesheet - spacing, layout, colors, sizes. They're the class names of Tailwind CSS, and `dark:` applies a class only in dark mode:

```mdx
<div className="grid grid-cols-2 gap-4 mt-8">
  <img className="rounded-lg border" src="/images/before.png" alt="Before" />
  <img className="rounded-lg border" src="/images/after.png" alt="After" />
</div>

<img className="block dark:hidden" src="/images/chart-light.png" alt="Usage chart" />
<img className="hidden dark:block" src="/images/chart-dark.png" alt="Usage chart" />
```

For your own classes and styles, see [Custom CSS and scripts](https://preview.writedocs.io/docs/configuration/custom-code/).