Skip to main content

Content Style Guide

All levels

Consistency is what makes a reference feel trustworthy. Follow these and your PR sails through review.

Voice​

  • Clear and direct. Short sentences. Lead with the point.
  • Friendly, never fluffy. Cut "in today's fast-paced world." Respect the reader's time.
  • Opinionated, then honest. Give the one recommended way first, then note alternatives and trade-offs.
  • Examples over theory. Show a snippet or a concrete case; don't just describe.
  • American English.

Structure of a page​

---
sidebar_position: 2
title: "Your Page Title"
description: "One sentence for search and previews."
---

<LevelBadge level="beginner" />

A one or two sentence intro that states what the reader will get.

## Sections with ## headings
...

## Next
- 2–4 links to related pages
  • Start with the level badge (beginner | intermediate | advanced | all). Components are global — don't import them.
  • End with a "Next" / "Related" list of 2–4 internal links.
  • Use admonitions (:::tip, :::warning, :::note, :::info) for emphasis, sparingly.

The two hard rules​

:::warning Non-negotiable

  1. Cite sources for volatile facts. Model names, prices, limits, exact flags, beta features → link the official source and add <VerifyNote lastVerified="YYYY-MM-DD" source="…">. Never hard-code model facts — link to the models table. Details: Fact Verification.
  2. Don't fabricate. No invented stats, quotes, APIs, or features. If unsure, say so or mark [verify]. :::

Opinion vs official​

  • We're opinionated — that's the value. Recommend, don't just enumerate.
  • But the official docs are the source of truth. Defer to them, link to them, and never contradict them silently.

MDX gotchas​

  • Curly braces {like this} in prose are parsed as code by MDX — put them in backticks or code fences, or use [brackets] in examples.
  • Test locally: npm run build must pass (it fails on broken links).

Next​