Skip to main content
Search...

mdx

Authoring MDX in this docs site (syntax, components, and project-specific conventions).

MDX in this docs site is powered by Velite + @mdx-js/mdx with custom plugins and components.

This page is the source of truth for writing docs that render correctly here.

What works

  • Standard Markdown (CommonMark)
  • GFM features (tables, task lists, strikethrough)
  • JSX inside markdown
  • import / export in MDX
  • Custom docs components such as Callout, Tabs, Steps, ComponentPreview, and ComponentSource

Required frontmatter

Every docs page should include frontmatter with at least:

---
title: your-page-title
description: One sentence summary for nav/SEO.
---
---
title: your-page-title
description: One sentence summary for nav/SEO.
---

Project-specific components

Callout

<Callout icon={<Lightbulb />} title="Tip">
Keep examples short and copy-pasteable.
</Callout>
<Callout icon={<Lightbulb />} title="Tip">
Keep examples short and copy-pasteable.
</Callout>

Steps + Step

<Steps>
  <Step>Install dependencies</Step>
  <Step>Add the component</Step>
  <Step>Run your app</Step>
</Steps>
<Steps>
  <Step>Install dependencies</Step>
  <Step>Add the component</Step>
  <Step>Run your app</Step>
</Steps>

Tabs

<Tabs defaultValue="npm">
  <TabsList>
    <TabsTrigger value="npm">npm</TabsTrigger>
    <TabsTrigger value="pnpm">pnpm</TabsTrigger>
  </TabsList>
  <TabsContent value="npm">
 
~~~bash
npm install your-package
~~~
 
  </TabsContent>
  <TabsContent value="pnpm">
 
~~~bash
pnpm add your-package
~~~
 
  </TabsContent>
</Tabs>
<Tabs defaultValue="npm">
  <TabsList>
    <TabsTrigger value="npm">npm</TabsTrigger>
    <TabsTrigger value="pnpm">pnpm</TabsTrigger>
  </TabsList>
  <TabsContent value="npm">
 
~~~bash
npm install your-package
~~~
 
  </TabsContent>
  <TabsContent value="pnpm">
 
~~~bash
pnpm add your-package
~~~
 
  </TabsContent>
</Tabs>

ComponentPreview

Use this to render an interactive preview from the registry index.

<ComponentPreview name="button-1" description="Basic button example." />
<ComponentPreview name="button-1" description="Basic button example." />

ComponentSource

Use this to render source from a file or folder.

<ComponentSource path="packages/registry-ui/src/button" />
<ComponentSource path="packages/registry-ui/src/button" />
  • Path is resolved from monorepo root in this docs app pipeline.
  • A directory path renders tabbed files; a single file path renders one code block.

Code blocks

Use fenced blocks with language identifiers:

~~~tsx title="components/demo.tsx" showLineNumbers
export function Demo() {
  return <div>Hello</div>
}
~~~
~~~tsx title="components/demo.tsx" showLineNumbers
export function Demo() {
  return <div>Hello</div>
}
~~~

MDX gotchas

  • Autolink syntax like <https://example.com> is not supported in MDX. Use [label](https://example.com).
  • Unescaped < and { can break parsing; escape as \< and \{ when they are plain text.
  • HTML comments (<!-- -->) are not valid in MDX. Use {/* comment */}.
JavaScriptNext.js