Writing pages
Add categories, order pages, and write your first document.
Create a category
Create docs/guides/, then add an optional _category.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:
---
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.
> [!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.
Page navigation
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.