Writing Docs Overview
Purpose and Scope
Storybook documentation starts from the same place as Storybook development: stories. A story captures a component in a meaningful state, and the docs system turns those states into documentation that teammates can read, search, review, and share. The official docs describe this as a workflow where writing component stories during development also creates basic documentation that can be revisited later. From there, teams can choose between generated pages for fast coverage and authored pages for richer guidance, examples, and design-system narrative.
Sources: code/addons/docs/README.md
This page orients you to that choice. Use generated docs when you want every component to receive a useful baseline with minimal configuration. Use authored docs when the component needs explanatory prose, usage rules, migration advice, accessibility notes, or examples that are not obvious from the stories alone. The important distinction is not generated versus manual in isolation; it is whether the reader needs a reference assembled from source metadata, or a guide that explains intent and tradeoffs around the component.
Sources: code/addons/docs/README.md
Storybook Docs is implemented as part of the broader Storybook workshop rather than as a separate site generator. The repository-level README describes Storybook as a frontend workshop for building UI components and pages in isolation, used for UI development, testing, and documentation. Within that workshop, docs live near stories and can be viewed while the development server is running, built as static output, or published for stakeholders. That makes documentation an everyday development artifact instead of a release-only deliverable.
Sources: code/addons/docs/README.md
Relevant Source Files
- docs/releases/features.mdx — Defines Storybook's feature lifecycle vocabulary: Experimental, Preview, Stable, and Deprecated. This helps teams interpret maturity signals for documentation-related capabilities as Storybook evolves.
- code/addons/docs/README.md — Describes Storybook Docs, DocsPage, MDX, framework support, installation, preset options, and the generated-versus-authored documentation model.
- code/core/src/docs-tools/README.md — Identifies shared docs utilities used by framework packages, including ArgType extraction, dynamic snippet generation, and checks for whether users are using docs or controls.
- code/core/src/shared/open-service/services/story-docs/README.md — Describes the story-docs service that provides per-story snippets, descriptions, and file-level imports for docs pages, the Code panel, and related debugging surfaces.
Generated Docs: Autodocs and DocsPage
The generated path is the default starting point. The Docs addon README describes DocsPage as a zero-config aggregation of component stories, text descriptions, docgen comments, props tables, and code examples into clean, readable pages. The official documentation calls the current generated experience Autodocs: a baseline documentation page positioned near your stories that lists existing stories and relevant metadata. In practical terms, generated docs are best when the component API is already well expressed through stories, TypeScript or framework metadata, comments, args, and arg types.
Sources: code/addons/docs/README.md, code/core/src/docs-tools/README.md
Generated docs depend on a few shared concepts. Arg types describe the public surface of a component or story input, and the docs tooling includes extraction utilities so frameworks can supply those tables consistently. Dynamic snippet generation helps show source examples without forcing authors to copy code into separate docs files. The docs-tools README also calls out detection for whether a user is using docs or controls, which matters because Controls and Docs both consume story metadata but present it for different tasks: interactive exploration versus explanatory reference.
Sources: code/core/src/docs-tools/README.md
Choose generated docs for broad coverage, onboarding, and API reference. They are especially valuable in a component library where every component should have a consistent page showing examples, controls, prop information, and source snippets. Generated docs reduce drift because they reuse the stories developers already maintain. They also make it easier to enforce documentation as part of normal story authoring: if a story exists and the component metadata can be extracted, the docs page can expose that work without requiring a separate writing pass.
Sources: code/addons/docs/README.md, code/core/src/docs-tools/README.md
Authored Docs: MDX and Long-Form Guidance
Authored docs are for situations where a generated reference is not enough. The Docs addon README defines MDX as a syntax for writing long-form documentation with stories side-by-side in the same file. In contrast to DocsPage, which provides smart documentation out of the box, MDX gives authors full control over component documentation. The official docs also position MDX as the way to customize templates or create free-form pages for each component, including pure documentation pages embedded inside Storybook alongside stories.
Sources: code/addons/docs/README.md
A typical authored page explains why a component exists, how it should be used, and which examples are recommended or discouraged. For a design system, that might include accessibility expectations, content guidelines, do-and-do-not examples, links to Figma, or migration advice from an older component. MDX is appropriate because it lets prose, headings, and embedded story canvases share one document. The story remains executable and interactive, while the surrounding text teaches context that cannot be inferred from the rendered state alone.
Sources: code/addons/docs/README.md
A minimal authored docs page usually imports doc blocks and stories, declares metadata, then embeds a selected story inside a canvas. The README example uses Meta, Story, and Canvas from @storybook/addon-docs/blocks, imports a component story file, and connects the MDX page to those stories. That pattern keeps the page tied to real CSF exports instead of duplicating examples. When a story changes, the authored documentation can keep displaying the maintained story rather than a stale screenshot or copied code sample.
Sources: code/addons/docs/README.md
import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import * as CheckboxStories from './Checkbox.stories';
<Meta title='MDX/Checkbox' of={CheckboxStories} />
# Checkbox
With MDX we can include a story for Checkbox in the middle of prose.
<Canvas>
<Story of={CheckboxStories.Unchecked} />
</Canvas>System-to-Code Mapping
The documentation surface is assembled by several layers. At the user-facing layer, the Docs addon provides DocsPage and MDX as the two main documentation modes. At the framework-support layer, docs utilities help framework packages extract arg types, generate snippets, and determine whether docs or controls are active. At the service layer, story-docs provides per-story snippets, descriptions, and file-level imports used by docs pages, the Code panel, and the components HTML debugger.
Sources: code/addons/docs/README.md, code/core/src/docs-tools/README.md, code/core/src/shared/open-service/services/story-docs/README.md
This mapping explains why docs feel integrated across Storybook instead of isolated in one renderer. Component metadata and story metadata feed generated pages. Story source and import analysis feed source snippets. The Code panel relies on the same story-docs service that supports docs pages, so source display is part of the docs architecture rather than a separate convenience feature. The story-docs README also notes that component prop docgen lives in a sibling core/docgen service, keeping per-story source documentation separate from component prop extraction.
Sources: code/core/src/shared/open-service/services/story-docs/README.md
The preview and manager also participate in documentation. The story-docs README describes an experimentalDocgenServer mode where the preview storyDocsSourceBeforeEach hook emits static snippets to the manager Code panel via SNIPPET_RENDERED, while preserving parameters.docs.source.transform handling in preview. For authors, the practical lesson is that source snippets shown in docs and the Code panel are not just static markdown. They are produced through Storybook runtime and service behavior, and addon or parameter configuration can influence how they appear.
Sources: code/core/src/shared/open-service/services/story-docs/README.md
Choosing the Right Documentation Mode
Start with generated docs for every component, then add authored docs where readers need judgment. Generated docs answer questions like which props exist, what stories are available, and what the rendered output looks like under different args. Authored docs answer questions like which variant should be used in a checkout flow, how the component behaves with real content, or why one accessibility pattern was chosen over another. A mature Storybook usually contains both: consistent autogenerated references and curated MDX pages for high-value components or system-level guidance.
Sources: code/addons/docs/README.md
The feature lifecycle page gives teams a useful vocabulary for evaluating documentation-related capabilities as the project changes. Experimental features are functional but still evolving and best for prototypes or early integrations. Preview features are nearly production-ready, documented, and suitable for real projects, but may still receive minimal breaking changes in minor releases. Stable features are fully supported and follow semantic versioning, while Deprecated features are being phased out and should not be used for new development. Apply those labels when adopting newer docs capabilities or migration paths.
Sources: docs/releases/features.mdx
For project maintainers, the lifecycle vocabulary also helps set expectations with downstream teams. If a documentation feature is Experimental, do not build critical design-system publishing workflows around it without accepting churn. If a feature is Preview, plan time for feedback and minor adjustments. If a feature is Stable, it is a safer foundation for templates and conventions. If a feature is Deprecated, prefer migration work over adding new pages that depend on it. This keeps documentation architecture aligned with Storybook's support commitments.
Sources: docs/releases/features.mdx
Practical Authoring Flow
A practical documentation workflow begins by writing strong stories. Give each component representative states, meaningful names, and args that describe the component's public inputs. Then review the generated docs page and ask whether it teaches enough for a new teammate to use the component correctly. If the generated page already answers the key questions, improve metadata and comments rather than creating a separate page. If the page lacks rationale, usage guidance, or larger examples, add MDX around the existing stories.
Sources: code/addons/docs/README.md, code/core/src/docs-tools/README.md
Next, verify the source examples shown to readers. Because story-docs is responsible for snippets, descriptions, and file-level import statements for docs pages and the Code panel, the quality of story source matters. Keep stories small, named, and importable. Avoid hiding important setup in places that make snippets misleading. When source display needs adjustment, use docs source parameters and transforms intentionally, recognizing that the preview handling described by the story-docs service preserves parameters.docs.source.transform behavior.
Sources: code/core/src/shared/open-service/services/story-docs/README.md
Finally, decide how the page should be consumed. Generated docs are good for local development, review, and broad API discovery. MDX pages are good for curated design-system education and stakeholder-facing documentation. Static documentation builds and publishing workflows are covered separately, but the authoring decision happens earlier: make stories the source of truth for examples, let Autodocs provide the baseline, and reserve MDX for explanation that only a human author can provide.
Sources: code/addons/docs/README.md
Next Steps
After this overview, read the focused pages for Autodocs and DocsPage, MDX Documentation, Doc Blocks and Code Panel, and Build Documentation. Those pages cover the concrete configuration and authoring APIs in more detail. If you are deciding whether to adopt a newer documentation capability, also review the Feature Lifecycle release page so your team understands whether the feature is Experimental, Preview, Stable, or Deprecated before using it in critical documentation workflows.
Sources: docs/releases/features.mdx, code/addons/docs/README.md