Writing docs

Frontmatter

Every page starts with it. title is the only required field; the rest are optional but the first three are expected by review.

---
title: Rate limits
description: One-sentence summary used by search and social cards.
sidebar:
  order: 4
  badge: { text: New, variant: tip }
---

description is not decoration — it feeds the <meta name="description"> tag, the search index and the link previews in Slack.

Linking

Use absolute paths with a trailing slash so the link survives a page moving between sections:

See [Versioning](/guides/versioning/).

Relative links (./versioning/) break silently when a file is moved. CI’s link check fails the build on a 404, which is the only reason absolute paths are safe to insist on.

Components

Starlight ships asides, cards, tabs, steps and file trees. They are MDX-only for the ones that take children:

import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';

<Aside type="caution">This changes the public API.</Aside>

House style

• Sentence case for headings, not Title Case.
• Second person, active voice: “Add the key”, not “The key should be added”.
• One idea per paragraph; short paragraphs beat long ones.
• Code blocks always carry a language tag — it drives syntax highlighting and copy buttons.
• Link the first mention of another product surface, then stop.