Rich docs with Storybook MDX

Components & documentation in harmony at last

Storybookis the standard tool for UI component development. It’s used to build the most popular design systems on the web, including Shopify Polaris , IBM Carbon , Salesforce Lightning , Auth0 Cosmos , and Airbnb Lunar .

Quality documentation like this is crucial to help people re-use your UI components, but it’s also a huge pain to get right. In practice, you spend more time maintaining your documentation system than actually writing docs!

Which is why at Storybook, we’re hell-bent on making UI component docs fast and easy. Our first step wasDocsPage, a tool to auto-generate best-practices documentation from your existing stories.

And today I’m excited to introduce fast, fully custom docs in Storybook, powered by MDX and available in Storybook 5.3-beta! :tada:

MDX enables you to customize Storybook’s auto-generated documentation with your own components, mix & match DocBlocks, and loop in non-technical teammates. All from within the comfortable confines of Markdown.

• :art: Customizable docs: Fully custom documentation made simple.
• :package: Ready-made building blocks: Reuse Storybook’s powerful DocBlocks.
• Write docs together: Powerful for devs, easy for designers and PMs
• :electric_plug: 100% compatible: Seamless Storybook integration that’s zero config

:bulb: What’s the big deal?

Earlier this year, the team outlined anambitious vision to rethink component documentation. Our first milestone was Storybook 5.2 that introducedDocsPage to automatically generate best practice UI docs from your existing stories.

Storybook Docs took off like a rocket, becoming one of the most popular documentation tools (by npm downloads ) in a matter of weeks! But even as teams embraced DocsPage, the desire to write fully custom documentation was clear.

Storybook MDX gives component authors an unparalleled balance of flexibility, cleanliness, and ease.MDX is an open, authorable format that fluidly interleaves Markdown and JSX components in the same file. It makes it easy to compose off the-shelf building blocks like color palettes, typography samples, and prop tables into long-form documentation.

What’s more, the straightforward MDX authoring experience means designers, PMs, and anyone familiar with Markdown can contribute to shared UI documentation. Intrepid alpha and beta users are already using Storybook as a single source of truth for their component libraries and design systems.