Markdown First

Every documentation file should be useful as a static markdown document before any React components or interactivity are added.

Human-First Authoring

Docs should be written for human readers and authors first, not optimized for programmatic consumption. Markdown has a well-defined AST (via remark/unified), so tooling can always extract structured data from files that were written to be readable. There is no need to compromise readability for machine parsing. Write naturally, and let the AST handle the rest.

Why Markdown

Markdown is the lowest-common-denominator format for reading documentation:

• GitHub renders .mdx files natively, so many users read docs directly in the repository.
• IDEs provide a table of contents, link navigation, and syntax highlighting out of the box. You can copy and paste markdown directly from your editor or attach it to a chat session, no website needed.
• AI agents prefer markdown because it is structured, predictable, and widely supported. Plain text files can be fed into any LLM context without scraping or building the docs first.

Anyone with a file explorer and a text editor has full access to the documentation.

Progressive Enhancement

Start with standard markdown features (links, headings, tables, code blocks), then layer React components on top for richer interactions.

For example, demos are linked as plain markdown so GitHub readers can click through to the source. At build time, these links are replaced with interactive React components. The CodeHighlighter component follows this pattern: its demos render as navigable links in markdown and become syntax-highlighted, interactive code blocks on the live site. Compare the GitHub-rendered view with the raw source to see this in action.

Reach for React components when the content needs interactivity or live state: tabs, variant toggles, collapsible panels, or embedded previews. For everything else, prefer plain markdown. A markdown table beats a custom component when the data is static, and a fenced code block beats an import when the snippet doesn't need highlighting beyond what the viewer provides.

Callout blocks use GitHub-style syntax (> [!NOTE], > [!TIP], > [!IMPORTANT]). In raw markdown they render as ordinary blockquotes, so the content is always readable. On the live site, the transformMarkdownBlockquoteCallouts plugin converts them into styled callouts.

Internal links use relative paths with page.mdx included (e.g. ../dialog/page.mdx), so they are Ctrl/Cmd + Clickable in any IDE. At build time, the page.mdx suffix is stripped to produce clean website URLs.

See File Navigation for the full set of file patterns and search shortcuts used across the repository.

Do / Don't

Do:

• Use standard markdown links, headings, tables, and code blocks as the primary content layer.
• Keep MDX imports grouped at the point of use, not scattered through prose.
• Link to demo source so GitHub readers can click through without a build step.
• Use relative paths with page.mdx included so links work in any IDE.

Don't:

• Rely on a React component for content that has no plain-markdown fallback.

• Use raw HTML tags when equivalent markdown syntax exists.

• Use HTML comments. MDX treats them as JSX, breaking the parse. Use link-reference comments instead:

  [//]: # 'Safe in MDX, invisible in rendered output'
  
  <!-- Breaks MDX, everything below this loses syntax highlighting -->
  
  # This heading still renders
  
  But your editor can no longer parse the file correctly.
  

• Embed large images inline. Store them in a co-located assets/ directory and reference them with a relative path.

• Assume readers have access to the live site; every page should be self-contained in a file explorer.

Images and Media

Images and diagrams follow the same progressive-enhancement principle. Store assets in an assets/ directory next to the page that references them and use standard markdown image syntax (![alt](./assets/diagram.png)). GitHub and IDEs render these natively.

For diagrams that change frequently, prefer a text-based format (Mermaid, ASCII) so diffs remain readable. Use raster images only when a visual is too complex for text and changes infrequently.

Autogenerated Files

Committing generated files is never ideal, but markdown is the best format to soften the friction. It diffs cleanly, GitHub renders rich diffs for it, and the result is a file that humans can actually read, not an opaque blob of JSON or HTML.

Files that are generated and committed, such as types.md and page indexes, are written in markdown so they can be read without any build step or tooling.

• Type references (types.md) are often the first thing a user reads when trying to understand a component's API. Markdown ensures this works in any viewer.
• Page indexes (page.mdx) list all pages within a group. If /components/dialog exists, /components should also exist for safe navigation. A generated page.mdx serves double duty: a live page on the site and a readable index in the repository. For example, the pipeline page index renders a full outline of every pipeline function directly on GitHub. Compare the GitHub-rendered view with the raw source to see how the generated markdown reads without a build step.

These generated markdown files also closely resemble what the server would return for the markdown content of a page, making them a natural alternative representation of the site for AI tools. An agent can read the committed markdown and get nearly the same information as a user browsing the live docs, without needing to fetch or render anything.

Related Conventions

• File Navigation - file structure patterns and search shortcuts.
• Fragment Delimiters - URL fragment hierarchy using :.