GuidesWriting docs
Markdown
Write pages in MDX: Markdown with components. Everything you can use, with examples.
Every page is an .mdx file in content/docs. The path of the file is the URL of the page:
| File | URL |
|---|---|
content/docs/index.mdx | /docs/ |
content/docs/quickstart.mdx | /docs/quickstart/ |
content/docs/api/events/send.mdx | /docs/api/events/send/ |
Page metadata
Start each file with a metadata export. The title and description appear at the top of the page, in search results, in the browser tab and in llms.txt.
export const metadata = {
title: "Quickstart",
description: "Send your first event in under five minutes.",
updated: "2026-10-14",
};
This guide takes you from zero to a delivered webhook.Then add the page to the sidebar in src/data/nav.ts. Running npm run dev warns you about pages that aren't in the navigation.
Text
Regular Markdown works: bold, italic, inline code, links and strikethrough. Links to other pages use their URL; external links open in a new tab.
Blockquotes are useful for quotes from customers or the spec you're implementing.
- Lists can be nested
- like this
- Task lists come from GitHub Flavored Markdown
- done
- not yet
Headings
Use ## and ### for sections. They get an anchor link, appear in On this page and are indexed by the search, so readers can jump straight to them.
Tables
| Option | Type | Default |
|---|---|---|
timeout | number | 30000 |
maxRetries | number | 2 |
Code blocks
Code is highlighted at build time with Shiki, so pages stay fast. Add a file name with title, highlight lines with {…} and number them with showLineNumbers:
```ts title="lib/relay.ts" {3} showLineNumbers
import { Relay } from "@relay/sdk";
export const relay = new Relay(process.env.RELAY_API_KEY);
```import { Relay } from "@relay/sdk";
export const relay = new Relay(process.env.RELAY_API_KEY);Every block gets a copy button. Diff-style highlighting works with the diff language:
- const relay = new Relay("rk_test_hardcoded");
+ const relay = new Relay(process.env.RELAY_API_KEY);Images
Put images in public/ and reference them by path: .