Markdown basics

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

.md and .mdx

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: \{, <.

Text

**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 ##:

## 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

[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 finds those, and anchors that don’t exist.

Lists

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.

• Install the SDK
• Send a test request

Tables

| 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.

Images

![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 reports images without one. Every image opens larger when clicked.

Images can be in any folder of the project - see Project structure. For a caption, a size, or a different image in dark mode, use the Image component.

Images load as the reader gets near them, and keep their place on the page while they do - see How images load.

Footnotes

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.¹

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. Inline code goes in single backticks.

HTML

HTML works in both .md and .mdx pages:

<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:

<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.