This document covers the MDX content management system used by the shadcn/ui documentation website. It explains how MDX files are organized, processed, and rendered into documentation pages, including frontmatter handling, static page generation, navigation, table of contents, and AI-optimized content delivery via specialized LLM routes.
For information about custom MDX components like <ComponentPreview> and the preview system, see page 8.2.
MDX documentation files are stored in apps/v4/content/docs/ and organized hierarchically. The file structure directly maps to URL paths through Next.js's dynamic routing system using the catch-all route [[...slug]].
Content Directory to URL Mapping
| File Path | Slug Array | URL Path |
|---|---|---|
(root)/index.mdx | [] | /docs |
installation/vite.mdx | ["installation", "vite"] | /docs/installation/vite |
changelog/2026-07-base-ui-default.mdx | ["changelog", "2026-07-base-ui-default"] | /docs/changelog/2026-07-base-ui-default |
Sources: apps/v4/app/(app)/docs/[[...slug]]/page.tsx:20-22, apps/v4/source.config.ts26-39
The documentation system uses fumadocs-mdx for processing. The system is built on top of a source object defined in @/lib/source which provides utilities for page retrieval and parameter generation.
MDX Build and Render Pipeline
The MDX body is extracted from the page.data object and rendered with the custom mdxComponents mapping. Highlighting is handled via rehype-pretty-code with custom transformers defined in apps/v4/source.config.ts.
Sources: apps/v4/app/(app)/docs/[[...slug]]/page.tsx:8-34, apps/v4/app/(app)/docs/[[...slug]]/page.tsx:155, apps/v4/mdx-components.tsx120-247 apps/v4/source.config.ts1-24
Pages are dynamically generated from the catch-all route [[...slug]]/page.tsx using Next.js's static generation capabilities.
The route exports critical configurations to ensure high performance and static delivery:
apps/v4/app/(app)/docs/[[...slug]]/page.tsx:16-18
The Page component retrieves data via source.getPage(params.slug) apps/v4/app/(app)/docs/[[...slug]]/page.tsx:76. It handles several specific content types:
/components/, it renders a DocsBaseSwitcher to toggle between different component bases (e.g., Radix vs Base UI) apps/v4/app/(app)/docs/[[...slug]]/page.tsx:145-154.changelog, neighbor navigation is disabled apps/v4/app/(app)/docs/[[...slug]]/page.tsx:83-86.mdxComponents map apps/v4/app/(app)/docs/[[...slug]]/page.tsx:155.findNeighbour from fumadocs-core/page-tree to provide "Previous" and "Next" links apps/v4/app/(app)/docs/[[...slug]]/page.tsx:86.Sources: apps/v4/app/(app)/docs/[[...slug]]/page.tsx:72-183, apps/v4/app/(app)/docs/[[...slug]]/page.tsx:145-156
The documentation includes a global command menu powered by fumadocs-core/search.
The CommandMenu component provides a unified interface for searching documentation, components, blocks, and styles. It uses the useDocsSearch hook to perform fetch-based searches against the /api/search endpoint apps/v4/components/command-menu.tsx65-67
Search and Tracking Flow
trackEvent with the name search_query apps/v4/lib/events.ts19shadcn add command tailored to the user's preferred package manager apps/v4/components/command-menu.tsx143-156Sources: apps/v4/components/command-menu.tsx42-106 apps/v4/lib/events.ts4-27
A primary goal of the documentation is being "AI-Ready". This is achieved through a dedicated LLM route and content transformation logic.
The route apps/v4/app/(app)/llm/[[...slug]]/route.ts serves documentation in a format optimized for Large Language Models. It uses processMdxForLLMs to transform MDX into plain markdown with embedded source code.
LLM Content Transformation Sequence
The processMdxForLLMs function in apps/v4/lib/llm.ts performs the following operations:
<ComponentsList /> tag with a full markdown list of components including their descriptions and URLs apps/v4/lib/llm.ts65-72<ComponentPreview /> tags with the actual source code of the component demo by looking up the file path in ExamplesIndex or StylesIndex apps/v4/lib/llm.ts77-100@/registry/bases/radix/) to standard user paths (e.g., @/components/) so the AI generates code that matches a standard installation apps/v4/lib/llm.ts102-132The DocsCopyPage component provides deep-links to various AI tools, pre-populated with a prompt that includes the current documentation URL apps/v4/components/docs-copy-page.tsx21-27
| Platform | Base URL | Implementation |
|---|---|---|
| v0 | https://v0.dev | apps/v4/components/docs-copy-page.tsx43-59 |
| ChatGPT | https://chatgpt.com | apps/v4/components/docs-copy-page.tsx60-74 |
| Claude | https://claude.ai/new | apps/v4/components/docs-copy-page.tsx75-89 |
| Scira | https://scira.ai/ | apps/v4/components/docs-copy-page.tsx90-122 |
Sources: apps/v4/app/(app)/llm/[[...slug]]/route.ts:25-50, apps/v4/lib/llm.ts65-143 apps/v4/components/docs-copy-page.tsx21-122
The mdxComponents object in apps/v4/mdx-components.tsx defines how standard HTML elements and custom documentation components are rendered.
| Component | Role | Implementation |
|---|---|---|
h1 - h6 | Auto-generates IDs and anchor links | apps/v4/mdx-components.tsx121-174 |
ComponentPreview | Renders a live component with source code | apps/v4/mdx-components.tsx11 |
ComponentSource | Displays the raw source code of a registry item | apps/v4/mdx-components.tsx12 |
Callout | Renders alert/info boxes | apps/v4/mdx-components.tsx7 |
ComponentsList | Renders a grid of component links (used on index pages) | apps/v4/mdx-components.tsx51-65 |
table | Wraps tables in a scrollable container | apps/v4/mdx-components.tsx177-181 |
pre | Custom styling for code blocks | apps/v4/mdx-components.tsx182-195 |
Sources: apps/v4/mdx-components.tsx1-120 apps/v4/mdx-components.tsx121-257
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.