Write docs

Guides are the pages around your API reference: quickstarts, concepts, how-tos. Each one is an MDX file in the docs app's content/ folder. MDX is Markdown that can also use components, such as callouts, tabs and links to operations.

What's in this sectionCopy Anchor Link

Add a pageCopy Anchor Link

---
title: Authentication
description: Send your API key with every request.
---

Every request needs an API key in the `x-api-key` header.

## Get a key

Create a key in the dashboard, then try it with
[List bookings](op:travel/list-bookings).

{
  "title": "Guides",
  "pages": ["index", "quickstart", "authentication"]
}

Files and URLsCopy Anchor Link

A page's URL is its path in content/, without the extension. An index.mdx file takes its folder's URL.

Use .mdx for pages with components and .md for plain Markdown. output.basePath is added in front of every URL; don't include it in file names or links.

FrontmatterCopy Anchor Link

Every page starts with YAML frontmatter between --- lines.

---
title: On-call runbook
description: What to do when bookings fail.
access: [staff]
---

A page with access is left out of search, llms.txt and llms-full.txt for everyone, and its Markdown copy needs the same access. A rule in access.rules does the same for every page it matches. It still needs a server to protect it: see Private docs.

Write MarkdownCopy Anchor Link

Everything in GitHub Flavored Markdown works: headings, lists, links, images, tables, task lists, strikethrough, footnotes and fenced code blocks.

• Headings. ## and ### headings appear in the table of contents and get an anchor link. Don't add a # H1; the title is the H1.
• Links to guides. Write absolute paths such as /guides/webhooks, or relative file paths such as ./webhooks.mdx.
• Links to operations. Write [Create a booking](op:travel/create-a-booking). See Linking operations.
• Images. Put files in docs/public/ and link them by path, as in ![Dashboard](/images/dashboard.png). You can also keep an image next to the page and use a relative path.

Use your own componentsCopy Anchor Link

Register React components in the guide page. They become available in every MDX file, without an import:

import { PricingTable } from '@/components/pricing-table';

<GuidePage
  config={orbit}
  page={page}
  components={orbitMdxComponents(orbit, {
    a: createRelativeLink(source, page),
    PricingTable,
  }) as Record<string, unknown>}
/>;

Add them to app/(home)/page.tsx too if the home page uses them.

What every page getsCopy Anchor Link

These come from layout in orbitdocs.config.ts. See Layouts.

Each page is also available as Markdown at /md/<slug>/content.md and included in /llms-full.txt. Search indexes every heading and paragraph. Restricted pages are left out of search and /llms-full.txt, and their Markdown copy needs the same access as the page.

Next stepsCopy Anchor Link