Content Lives In MDX Pages

Each guide, landing page, or reference page is a Markdown or MDX file.

  • Use MDX pages for guides and explanations.

  • Use built-in components when plain Markdown is not enough.

  • Keep one main goal per page.

Your docs.json file controls the site around your content.

  • Set the site name, logo, colors, and appearance.

  • Set tabs, groups, and page order.

  • Set search, footer links, errors, and redirects.

Navigation Guides Readers

Good docs are easy to scan.

  • Put onboarding pages near the top.

  • Group pages by task.

  • Keep the number of top-level tabs small.

If a new reader cannot tell where to start in a few seconds, improve the navigation before adding more pages.

Languages Are A First-Class Concern

Use translated page files and language-aware navigation to support multiple languages.

  • Add navigation.languages to enable the language selector.

  • Store translated pages in locale folders such as fr/ or nl/.

  • Translate labels in navigation so tabs and groups match the selected language.

Components Improve Clarity

Use components when they make the page easier to read.

  • Use callouts for important context.

  • Use cards to guide readers to the next page.

  • Use code groups when the same task needs examples in multiple programming languages.

A Good Starter Docs Set

Start with:

  • A homepage that explains the product

  • A getting-started guide

  • A quickstart for impatient readers

  • A localization plan if you support more than one market

Full Image