Guides

Guides are long-form documentation pages — tutorials, walkthroughs, and conceptual explanations that sit alongside your API reference. They live in categories in your sidebar and are written in Markdown with MDX support.

Writing a Guide

There are two ways to create guide content in ReadMe:

With the Agent

Open the Agent from any page and describe what you need. The Agent can draft entire guides, rewrite existing content, translate pages, and insert MDX components — all while referencing your OpenAPI spec and existing docs for accuracy.

Examples of what you can ask:

• "Write a getting started guide based on my API spec"
• "Add a Python code example to the authentication section"
• "Translate this page to Japanese"
• "Find every page missing a code example and list them"

The Agent works on single pages or across your entire docs site. See Agent for the full feature reference.

In the Editor

1. Toggle into Edit Mode from the top navigation.
2. Click + next to a category to create a new page.
3. Write in the editor — type / to insert code blocks, callouts, images, tabs, and other components.
4. Toggle between Edit and View to preview how the page will render.

You can also switch to Raw Mode (three-dot menu → Raw Mode) to edit the underlying Markdown directly.

See Creating and Managing Guides for the full walkthrough.

Organizing Content

Guides are organized into categories (sidebar sections) and pages within those categories.

• Categories: Click + NEW CATEGORY in the sidebar to create one. Name them by user task or skill level (e.g., "Getting Started", "Authentication", "Advanced Usage").
• Pages: Each page gets a title, a URL slug (auto-generated from the title), and can be hidden while you draft.
• Subcategories: Nest pages under a parent page for multi-page tutorials.
• Ordering: Drag pages in the sidebar to reorder, or edit _order.yaml if you use bi-directional sync.

Checking Quality

The Linter validates each page against your style guide as you edit. Configure rules for tone, formatting, terminology, and common errors. Issues can be fixed manually or resolved by the Agent directly from the linter results.

To score your entire docs site at once, run a Docs Audit. It aggregates linter results across all pages and surfaces gaps, inconsistencies, and broken links.

Interactive Content with MDX

Guides support MDX — Markdown with inline JSX components. Use built-in components like <Tabs>, <Callout>, <Image>, and <Cards>, or create your own reusable components.

   const client = new ReadMeAPI(apiKey);

See MDX for the component reference.

Reusing Content

📘

Enterprise Feature

Reusable Content is available on Enterprise plans.

Create reusable content blocks for content that appears on multiple pages (authentication steps, environment setup, standard warnings). Update the block once and it changes everywhere. Insert blocks from the / command menu.

See Reusable Content for setup.

Next Steps

1. Create your first guide in the editor.
2. Set up the Agent to draft and edit content with AI.
3. Configure the Linter with your style guide rules.
4. Add interactive elements with MDX components.
5. Connect to GitHub for collaborative editing via pull requests.