MDX for documentation that can stay alive

Documentation usually begins as prose and code samples. That is the right default: text is portable, reviewable, searchable, and kind to version control.

Some ideas still become clearer when a reader can touch them.

Markdown is the authoring floor

A new TPG article is one .mdx file with a small metadata export. Headings become stable anchors automatically, article navigation comes from the filename, and the index is built from the same metadata.

Authors do not need to create a route, update a sidebar array, or copy a page component.

export const meta = {
  title: "A focused title",
  description: "One sentence for cards and search.",
  section: "Build",
  order: 40
};

## A stable, linkable heading

Write normal Markdown here.

MDX is the ceiling

MDX lets a document opt into a curated component when prose is no longer enough. The role explorer in the getting-started guide is one example: it lets a reader compare runtime roles without leaving the conceptual flow.

The useful constraint is curated. Arbitrary product code inside an article makes content difficult to maintain. A small component library keeps interactions accessible, visually consistent, and safe to reuse.

Links are part of the interface

Every second- and third-level heading receives a deterministic slug. The table of contents uses the same slugging algorithm, so copied deep links survive reloads and can be shared in issue discussions.

Good article slugs should describe the idea, not its location in a current navigation tree. /docs/room-model can move between sections without breaking external links.

Content should fail loudly

The content registry validates required metadata during development and builds. A blog post without a publication date or a docs page without a section is an error, not a half-rendered card.

That is a small thing, but it keeps the easy authoring path from becoming an inconsistent publishing path.