MDX Documentation

Purpose and Scope

MDX is Storybook’s authoring format for long-form documentation that needs more structure and control than generated documentation alone. In Storybook Docs, a generated DocsPage aggregates stories, descriptions, docgen comments, props tables, and code examples automatically, while MDX lets authors decide where prose, examples, and embedded stories appear on the page. Use MDX when a component needs conceptual explanation, usage guidance, design rationale, migration notes, or tutorial-style documentation that should live inside the same Storybook navigation as the component examples. Sources: code/addons/docs/README.md

Storybook’s public docs describe MDX files as a mix of Markdown and JavaScript or JSX. That combination matters because the file can contain readable documentation headings and paragraphs, import stories from Component Story Format, and render Storybook doc blocks such as Meta and Canvas. The result is not a separate documentation system; it is a Storybook docs page that can reference the same stories, args, parameters, and component metadata used elsewhere in the project. MDX is therefore best understood as an authored layer over the story system, not a replacement for stories.

Relevant Source Files

• docs/contribute/framework.mdx — Defines Storybook framework integrations as packages for metaframeworks or builder-renderer combinations, which is the main repository-backed source for framework considerations on this page.
• code/addons/docs/README.md — Describes Storybook Docs, the distinction between DocsPage and MDX, the MDX embedding model, installation notes, and framework support for docs.
• code/core/src/docs-tools/README.md — Identifies shared docs utility responsibilities such as arg type extraction, dynamic snippet generation, and docs or controls detection.
• code/core/src/shared/open-service/services/story-docs/README.md — Documents the story-docs service that provides per-story snippets, descriptions, and file-level imports for docs pages and the Code panel.

Core Authoring Model

An MDX documentation page usually starts by importing Storybook doc blocks from @storybook/addon-docs/blocks and importing stories from a nearby CSF file. The Meta block connects the MDX page to the story module, and blocks such as Canvas render a selected story in the middle of the prose. This preserves the normal Storybook pattern: stories remain the source of executable component states, while MDX gives writers the freedom to arrange those states into a richer article, reference page, or tutorial. Sources: code/addons/docs/README.md

import { Canvas, Meta, Story } from '@storybook/addon-docs/blocks';
import * as CheckboxStories from './Checkbox.stories';
 
<Meta of={CheckboxStories} />
 
# Checkbox
 
Use this page to explain when and why a checkbox appears in your product.
 
<Canvas>
  <Story of={CheckboxStories.Unchecked} />
</Canvas>

Use this pattern when the reader needs more than a generated page can infer. A generated DocsPage is strong for standardized component reference, but it cannot know the narrative sequence your team wants: what problem the component solves, which variant to start with, what accessibility constraints apply, or how the component behaves inside a larger flow. MDX lets you place those explanations directly beside rendered examples, so design-system consumers do not have to jump between prose, source code, and a separate Storybook canvas.

Pure Documentation Pages and Embedded Stories

MDX can document a component, but it can also create pure documentation pages that sit alongside stories. A pure page might explain contribution guidelines, design tokens, release practices, brand voice, or application architecture without centering a single component export. When a page does need examples, MDX can import one or more CSF story modules and embed selected stories wherever they clarify the text. That is especially useful for pages that describe component combinations, because the prose can introduce the relationship before the rendered example appears.

The official docs also connect MDX to page-level and multi-component storytelling. Storybook supports everything from atomic components to composed pages, and MDX gives teams a place to explain the extra context that appears as components are combined. For example, a page about List and ListItem can explain the parent-child relationship before showing the composed story, or a page-level screen can explain which data is presentational and which behavior is mocked. In this workflow, the CSF stories keep examples executable while MDX keeps the documentation readable.

System-to-Code Mapping

Storybook Docs is implemented as an addon-oriented documentation layer. The docs README describes two user-facing modes: zero-config DocsPage generation and authored MDX pages. The same area also calls out installation of @storybook/addon-docs, peer dependency considerations, and framework support. Beneath that public surface, docs utilities support framework packages with arg type extraction, dynamic snippet generation, and detection of whether a project is using docs or controls. Those utilities are intentionally shared because framework integrations need common documentation behavior without duplicating logic. Sources: code/addons/docs/README.md, code/core/src/docs-tools/README.md

The story-docs service shows how documentation content is connected to story source. It provides per-story snippets, descriptions, and file-level import statements for docs pages, the Code panel, and the components HTML debugger. When the experimental docgen server is enabled, static snippets can be emitted to the manager Code panel through SNIPPET_RENDERED, while preserving parameters.docs.source.transform behavior in preview. This matters for MDX authors because embedded examples are still backed by Storybook’s story metadata and source-display pipeline, not by manually copied code samples. Sources: code/core/src/shared/open-service/services/story-docs/README.md

Framework Considerations

Storybook Docs supports the major view layers that Storybook supports, but framework behavior is still important when MDX pages render stories inline or display prop information. The framework contribution guide defines a Storybook framework as a Node package that supports either a metaframework such as Next.js, NuxtJS, or SvelteKit, or a builder-renderer combination such as Vite with React, Angular, Vue 3, or web components. For metaframeworks, the package is expected to recreate or mock enough app behavior that Storybook feels similar to the user’s application environment. Sources: docs/contribute/framework.mdx

That framework model explains why MDX examples should be authored with the project’s renderer and builder in mind. A React Vite project, Angular project, SvelteKit project, and Web Components project can all use Storybook Docs, but their component imports, provider setup, prop extraction, and inline rendering support may differ. If an MDX page embeds stories that depend on routing, app-level context, CSS pipelines, or metaframework conventions, make sure the relevant framework integration supplies those behaviors through Storybook configuration before treating the documentation as portable across projects.

Practical Guidance and Next Steps

Prefer generated docs for straightforward component references and MDX for pages where the reading order matters. Keep the source of truth for rendered component states in .stories files, then import those stories into .mdx pages instead of recreating examples manually. This keeps controls, args, testing hooks, source snippets, and embedded examples aligned. For design-system docs, a good default is to let Autodocs cover the API reference, then add MDX pages for usage guidance, accessibility notes, recipes, and multi-component workflows.

When adding a new MDX page, start with the nearest CSF stories, decide whether the page is component-bound or pure documentation, and add Meta accordingly. Use Canvas for examples that readers should inspect visually, and keep surrounding prose focused on decisions the example alone cannot communicate. If the page depends on framework behavior, verify the framework package and Storybook configuration first. Next, read the pages on Autodocs and DocsPage, Doc Blocks and Code Panel, Component Story Format, and framework-specific setup to understand how MDX participates in the rest of Storybook’s documentation pipeline.