Build Documentation

Purpose and Scope

Storybook documentation can be previewed during development and built as a static artifact for publishing. This page explains the docs-specific workflow described by the repository documentation: use the docs mode flag with the development server when writing or reviewing documentation, then use the same mode with the production build command when the documentation is ready to share. The workflow is intended for teams that already author stories, Autodocs content, or MDX pages and need a focused output for stakeholders who care primarily about component documentation rather than the full interactive workshop.

Sources: docs/writing-docs/build-documentation.mdx

Docs mode is a different presentation of the same documentation source material rather than a separate documentation system. The source page says Storybook looks for stories available in MDX or Component Story Format and displays the documentation based on what has been added. That means a documentation build is still driven by the story and docs files maintained alongside components. The mode changes how the Storybook interface is arranged: documentation receives the focus, individual stories are flattened, the icons differ, and the toolbar is not shown in the rendered layout.

Relevant Source Files

• docs/writing-docs/build-documentation.mdx — Defines the official reader workflow for previewing documentation with the development server, building static documentation with the production build command, understanding docs-mode caveats, and choosing a publishing destination.

Preview Documentation Locally

During development, add a package script that starts Storybook in documentation mode. The documentation source recommends wrapping the command in a script so contributors do not need to remember the exact command-line flag. When that script runs, Storybook generates a preview of the final documentation experience instead of the normal development interface. This is useful before publishing because authors can confirm that MDX pages, generated documentation, story examples, and component-level docs appear in the documentation-first navigation and layout that readers will later see.

{
  "scripts": {
    "storybook-docs": "storybook dev --docs"
  }
}

The local preview flow should be treated as an authoring checkpoint. Run the docs script while editing MDX, story descriptions, or generated docs inputs so that mistakes are caught in the mode where documentation will actually be consumed. The documented caveats matter here: the top-level item represents the primary story for the component, each story is shown in a flattened mode, and the toolbar is absent. If a team depends on toolbar-driven globals for examples, authors should verify that the documentation still communicates the intended state clearly in this reduced documentation layout.

Build and Publish Static Docs

For publication, use the docs mode flag with the production build command. The source page recommends adding a separate build script to the project package file, mirroring the development script but using the static build entry point. When executed, Storybook enters documentation mode again and writes the generated documentation output into the standard static output folder. That folder can then be uploaded by the same deployment systems used for a regular static Storybook, while presenting a docs-focused build to designers, product managers, engineers, or external stakeholders.

{
  "scripts": {
    "build-storybook-docs": "storybook build --docs"
  }
}

The documented static output location is the folder named by Storybook for built assets, so publishing is primarily a hosting concern after the command completes. The page explicitly names common hosting providers such as Vercel, Netlify, and S3 as examples, but the important contract is that the command produces static files that can be served by a static host. Because the same docs-mode caveats apply to the built output, previewing locally before deployment helps prevent surprises in navigation, toolbar availability, and story presentation after the files are uploaded.

System-to-Code Mapping

The same flag is the conceptual bridge between the preview and production steps. In development, it changes the running Storybook so authors can inspect the documentation experience interactively. In production, it changes the generated static build so the output is documentation-focused. The page does not describe a separate configuration file for docs-only builds; instead, it frames documentation mode as a command-line switch applied to the normal Storybook development and build commands. That makes the workflow easy to adopt incrementally in existing projects.

Implementation Details and Caveats

Docs mode intentionally reduces parts of the standard Storybook interface. The toolbar is hidden, story entries are displayed with a flattened presentation, and the top-level navigation item refers to the primary story for a component. These behaviors help readers focus on documentation instead of exploratory controls, but they also mean authors should review examples that depend on interactive globals, toolbar state, or deep story hierarchy. A good docs build should still explain the component clearly when the interface is optimized for reading rather than for broad workshop-style exploration.

Sources: docs/writing-docs/build-documentation.mdx

Next Steps

After adding the preview and build scripts, run the preview command while editing documentation and run the build command before deploying. If the generated output is too sparse, improve the source material rather than changing the publishing flow: add Autodocs inputs, write MDX for long-form explanations, or compose pages with doc blocks. For deployment mechanics, continue to the publishing guidance; for richer authoring, continue to the pages on Autodocs, MDX documentation, and doc blocks so the static documentation build has high-quality content to render.