Skip to content
Writing documentation

Writing pages

Add categories, order pages, and write your first document.

Create a category

Create docs/guides/, then add an optional _category.json:

json
{
  "title": "Guides",
  "sidebar_position": 1
}

Without this file, RDX derives a label from the folder name. Each top-level folder defines a sidebar category.

Create a page

Add docs/guides/first-page.mdx:

mdx
---
title: First page
description: Everything you need to begin.
link_position: 1
---

## Before you begin

Install the tools for your project.

## Your first example

Write a short, useful example.

The page title and description appear in the document header. Use ## for the first section below that header. link_position sets the page order within its category. Lower positions come first; ties and pages without positions use slug ordering. The filename supplies the fallback title when one is not provided.

Choose a file format

Use .md or .mdx for your pages. Both formats support frontmatter, headings, tables, Callouts, Tabs, Accordion, keyboard shortcuts, and all code block modes through RDX's Markdown syntax. You can mix both formats in a category.

For example, docs/guides/first-page.md has the URL /docs/guides/first-page. File extensions are omitted from page URLs. Keep one file per route: first-page.md and first-page.mdx would conflict.

Choose .md for Markdown content, including literal braces such as {placeholder}. Choose .mdx when you need MDX syntax. RDX's built-in components use the same Markdown notation in either format.

Search, section links, and the table of contents use both formats. Translated pages match the original by their path without the extension, so an original guides/first-page.mdx can have a guides/first-page.md translation. Version snapshots retain the files in their original format.

Write for readers

Use paragraphs, headings, lists, links, and code fences. The shared renderer handles their styling. Add Callouts, Tabs, or an Accordion when the content benefits from them.

Write these components with Markdown: > [!TIP] for a Callout, :::tabs for Tabs, :::accordion for an Accordion, and :kbd[Enter] for a keyboard key. No imports are required in your pages.

md
> [!TIP] Keep examples useful
> Explain the next step and show the reader what to expect.

For a custom homepage or logo, create components/home.tsx or components/logo.tsx and reference the component in rdx.config.ts.

Press Tab when opening a page to reveal Skip to content. Press Enter to move keyboard focus past the navbar and sidebar to the page title and content. Continue with Tab to reach the links and controls that follow.

On mobile, swipe left across the page text to open the next document, or right to return to the previous one. Page order follows the sidebar. Start away from the screen edges; code blocks, tables and interactive components keep their own touch interactions. The previous and next buttons also remain available.

Preview and publish

Save the file while pnpm dev is running. Use relative document links to connect pages. Run a production build before deploying; missing relative document links fail compilation rather than silently sending readers to another version.