The recent Storybook 5.2 release delivers a new approach for generating design system documentation. Storybook 5.2 streamlines component documentation to make best practice documentation easier for anyone creating Storybook projects.
Storybook 5.2 introduces three main approaches for improving design system documentation:
- DocsPage: Zero-config component documentation
- MDX: Unifying stories and long-form documentation
- Component Story Format (CSF): Portable component examples
As explained by Michael Shilman, a core member of the Storybook team:
The centerpiece of 5.2 is DocsPage, a zero-config template for auto-generating best-practice component documentation from your existing stories.
Storybook strives to enable the development of UI components in isolation. The normal Storybook workflow has developers build stories to capture the key states of a component without focusing on complex dependencies or APIs. DocsPage then leverages these existing stories to generate documentation. These stories are executable, testable, and remain in sync with production code, keeping documentation in sync with the codebase. DocsPage inputs stories, combines the stories with code comments and property tables for the component, generating documentation pages.
MDX extends DocsPage to allow authoring stories and long-form documentation in the same file, typically an ES module. MDX combines markdown syntax with JSX, allowing developers to configure component documentation with arbitrary content and layout. MDX also provides a library of Doc Blocks to save time with common documentation tasks like displaying component properties.
To make MDX stories possible, Storybook revamped their story format. Component Story Format (CSF) provides a portable approach for authoring Storybook stories as ES6 modules. Higher-level formats like MDX or Github-flavored Markdown (GFM) can get compiled into CSF, allowing the Storybook community flexibility in how to author stories while retaining compatibility with the Storybook ecosystem.
Beyond the improved approach to generating documentation, Storybook 5.2 improves its addon APIs with a React hooks-inspired API, improves its TypeScript support with bundled Typescript types for most packages, adds support for React hooks, provides an experimental version of Storybook that leverages Parcel rather than webpack, and adds additional Storybook preset configurations.
Storybook is available under the MIT open-source license. Contributions are welcome via the Storybook GitHub project and should follow Storybook's contribution guidelines and code of conduct.