Markdown

Plain Markdown (.md) is the simplest way to write a guide. Every file in docs/ is a page. Pick a format per page: Markdown, Markdoc or MDX can sit side by side.

Title and frontmatter

---
title: Authentication
description: Get an access token and send it with every request.
---

Every request needs an access token...

Without a title in the frontmatter, a first # Heading becomes the page title. So a README-style file works as-is:

# Authentication

Every request needs an access token...

These frontmatter keys work too:

Key	Does
`description`	The page’s description, used by search engines and link previews.
`sidebar`	The page’s sidebar link: `label`, `order` and `badge`.
`tableOfContents`	Overrides `docs.toc` for this page. `false` hides “On this page”.
`template: splash`	A full-width page without sidebars, for a landing page.
`hero`	A title block with a tagline, an image and action links, for a landing page. See Landing pages.
`draft`	`true` leaves the page out of `rapidoc build`.
`pagefind`	`false` keeps the page out of search.

Landing pages

A page with template: splash and a hero is a landing page, like this site’s home page. Any page in docs/ can be one; point a link tab at it to give it its own tab.

---
title: Solutions
template: splash
hero:
  layout: stacked
  title: Ship faster with<br><mark>our APIs</mark>
  tagline: Prices, bookings and tracking for every parcel.
  image:
    html: <img src="/images/hero.png" alt="A booked shipment and its tracking timeline" width="520" height="460">
  actions:
    - text: Get started
      link: /docs/getting-started/quickstart/
    - text: Browse the APIs
      link: /catalog/
      variant: secondary
---

Key	Does
`hero.title`	The large heading; without it, the page `title`. Inline HTML works: `<br>` breaks the line, `<mark>` shows gradient text.
`hero.tagline`	The text under the heading. Inline HTML works.
`hero.image`	`html`: an `<img>` of a file in `public/`, or an inline SVG. Starlight’s `file`, `dark` and `light` keys take a path relative to the page.
`hero.actions`	Buttons: `text`, `link`, `variant` (`primary`, `secondary` or `minimal`) and `icon`.
`hero.layout`	`split` (default): the text left and the image right; without an image the text takes the full width. `stacked`: the text and buttons centred, the image below them.

On phones both layouts are one column, with the image below the text.

Links

Link to other guides by URL: [Errors](/docs/errors/). Link to an API reference page with /apis/<id>, to one tag with /apis/<id>/<tag>, and to one operation with its anchor:

See [Create a shipment](/apis/shipments/shipments#create-shipment).

Images

Put images in public/ and use their path from the site root:

![Label example](/images/label.png)

Code

Fenced code blocks are highlighted by Expressive Code, with a copy button. Add a title, mark lines, or show a terminal frame:

```js title="client.js" {2}
const res = await fetch('https://api.acme.com/v1/orders', {
  headers: { Authorization: `Bearer ${token}` },
});
```

```bash
npm install @acme/sdk
```

Callouts

Highlight a note, tip or warning with a ::: block:

:::tip[Use idempotency keys]
Retrying a POST with the same key never creates a second order.
:::

Use idempotency keys

Retrying a POST with the same key never creates a second order.

More types and options: Callouts.

Tables, lists, and the rest

GitHub-flavored Markdown works: tables, task lists, strikethrough, autolinks and footnotes.