chan.dev / posts

MDX docs

🌱 This post is in the growth phase. It may still be useful as it grows up.

Intro

[!youtube, social] YouTube, Social

Storybook has full support for MDX.

[!b-roll] screen: typing markingdown then using a React component

Markdown + React components? It’s the dream, right?
Storybook takes that dream even further with a full set of components for adding great documentation to your components.

[!b-roll] screen: adding blocks to new docs page template

let’s dive in.

Add an MDX file to Storybook

[!short] That’s how to {title}

To add an MDX file in Storybook:

[!short] MDX in Storybook make it easy to write documentation in markdown while utilizing the components in your component library or design system.

[!full] Storybook has built-in support for MDX. So you don’t have to do anything special. Just start writing.

import { Button } from "./Button.tsx";
# Button
Primary UI component for user interaction
<Button primary={true} label="Button" />

Use Storybook Doc Blocks in MDX

![bug] > <Meta /> only seems to work when imported as a named export (directly). Not when using property accessy on a module object * as DocBlock DocBlock.Meta.

[!short] That’s how to… {title}

[!fullvideo] For the title and description, I’d like to use the data we have defined in our component and eliminate this one-off text. [! b-roll] show component definition

[!short] Re-using metadata ensures that your documentation stays in sync with component code. And you just saw how easy it is to achieve with Storybook doc blocks.

[!full] Now our documentation will stay in sync with our source code and story files. But can we do the same for this story here? [!b-roll] showing the code with the docblocks but story still one-off Yes.

import { Button } from "./Button.tsx";
import * as ButtonStories from "./Button.stories.tsx";
import { Meta, Title, Description } from "@storybook/blocks";
<Meta of={ButtonStories} />
<Title />
<Description />
<Button primary={true} label="Button" />

Add Stories to MDX

[!short] That’s how to {title}

[!full]

Outro

MDX + docblocks is a real godsend for component-driven documentation. When I first started implementing component libraries and design systems in Rails, we had to rig together 5 very different tools and the experience was still bad. This is awesome.

Well that’s it for today’s quick tip. Check out one of these videos if you want to start generating docs automatically. And get subscribed to see our upcoming overview of all the doc blocks.

Thanks for watching. I’m chantastic. And I’ll see you in the next one!