Storybook Markdown Docs

Supporting .md docs in Storybook — Part 1

This article is part of a series , feel free to look at the others below 👇👇.

• Addon-Kit is a developer’s dream come true
• Supporting .md docs in Storybook — Part 1
• Supporting .md docs in Storybook — Part 2
• Storybook Addon for Auto Markdown Import
• Supporting .html files in Storybook

Traditionally every project you work on at some point will have a README.md and/or CHANGELOG.md. These files are just sitting there, waiting for someone to take a look at them, specifically take a look at them. You would only go there when you need them, ever thought of the loneliness they feel just waiting for you to look for them.

Then comes Storybook in all its glory presenting documentation for everything in your app except these lonely files. But wait, there is a solution.

One of the many many options that Storybook provide is buried deep into the addon-docs is called transcludeMarkdown and this option basically allows you to import markdown files as if they were React components.

Simple enough, all you need to do is change the main.js file a little bit.

module.exports = {
  addons: {
    '@storybook/addon-essentials',
    {
      name: '@storybook/addon-docs',
      options: {
        transcludeMarkdown: true
      }
  }
}

Next steps are as easy as importing the markdown document into a .mdx file like so:

import { Meta } from '@storybook/blocks';
import Changelog from './CHANGELOG.md';

<Meta title='Changelog' />

<Changelog />

To be honest, this approach didn’t work for me, no idea why. And while this is the recommended way by Storybook, I still wanted to experiment with other approaches. So, I disabled transcludeMarkdown and I made the following change:

import { Meta, Description } from '@storybook/blocks';

<Meta title='Changelog' />

<Description>{require('./CHANGELOG.md')}</Description>

This time, it worked. Take it with a grain of salt, but there is no way to use Markdown docs directly without another .mdx file to import it, YET. But at least README.md & CHANGELOG.md are no longer alone, and they are served beautifully alongside the other project documents in my Storybook.