Skip to content
RelayDocumentation

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:

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

content/docs/quickstart.mdx
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

OptionTypeDefault
timeoutnumber30000
maxRetriesnumber2

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);
```
lib/relay.ts
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: ![Delivery log](/images/delivery-log.png).