Concepts

Content Lives In MDX Pages

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

• Use .md pages for portable plain Markdown.

• 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.

• Set changelog collections when you want release notes generated from MDX files.

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.

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.

Personalization Happens After Authentication

Personalized MDX lets one compiled page serve different guidance to different readers.

• Read safe values from user in MDX expressions.

• Select content with comparisons, ternaries, &&, and ||.

• Keep personalized responses private and out of shared caches.

• Test locally with relevate preview --user-data.

Relevate compiles every branch ahead of time and chooses the matching precompiled content on the server. Resolved user values are not written to search indexes, Markdown exports, or build artifacts.

Text Exports Help Agents And Support

Every public page can be requested as Markdown with a .md URL or an Accept: text/markdown header.

• Use this for AI tools, support workflows, and lightweight command-line reading.

• Use /skill.md to describe the docs site to compatible agents.

• Keep page titles, descriptions, and headings specific so exports remain useful out of context.

Changelogs Are Generated Collections

Changelog entries are MDX files with frontmatter such as type, date, label, and tags.

• Configure the collection in docs.json.

• Write one entry per release or product update.

• Let Relevate generate index pages, entry pages, RSS feeds, search records, and assistant records.

The Assistant Is Docs-Scoped

The Relevate Assistant answers from compiled docs exports.

• It works best when pages are focused and examples are close to the explanation.

• It should say when the docs do not answer a question.

• Hidden and noindex pages are excluded from public assistant-ready exports.

A Good Starter Docs Set

Start with:

• A homepage that explains the product

• A getting-started guide

• A quickstart for impatient readers

• A changelog for product changes

• A Markdown export and assistant plan for AI-aware docs

• A localization plan if you support more than one market