Markdown Docs
Storybook addon for auto importing markdown/html docs.
Table of Contents
Getting started
- Install the addon:
yarn add @storybook-extras/markdown -D- Add the addon to your Storybook config:
// .storybook/main.ts
import { StorybookConfig } from '@storybook/angular';
import { ExtrasConfig } from '@storybook-extras/preset';
const config: StorybookConfig & ExtrasConfig = {
...
"stories": [
"../*.@(md|html)",
"../src/**/*.stories.@(js|jsx|ts|tsx)"
],
"addons": [
"@storybook-extras/markdown",
...
],
...
}
export default config;- Optionally you may want to pass
includesand/orexcludesoptions if needed like so:
export default {
addons: [
{
name: '@storybook-extras/markdown',
options: {
includes: '../stories/**/*.@(md|html)',
excludes: [/\.component\.html$/],
stories: [
{
path: '../stories/markdown-main-js.md',
title: 'Markdown/main.js',
},
],
},
},
],
};That's it, you're done. Now you will find README & CHANGELOG along with HTML docs if you want as well, in your Storybook sidebar and you can open them and see the contents.
Custom Titles
Currently Storybook will be using the file name as the story title, e.g. README.md will be README. This addon supports multiple options to customize the title for your .md & .html files.
| Precedence | Option | Example |
|---|---|---|
| 1 | Use the HTML title tag |
<title>Docs/Custom Title</title> |
| 2 | Use the HTML meta tag, usign Meta will throw an error |
<meta title="Custom Title" /> |
| 3 | Uses a markdown comment in the file | {/*title:"Custom Title"*/} |
| 4 | Use predefined list of titles from main.js
|
See below |
| 5 | Use the filename with a + to separate the title. Note: full path will be omitted. |
Markdown+Custom Title.md becomes Markdown/Custom Title
|
Predefined Titles
// .storybook/main.ts
import { StorybookConfig } from '@storybook/angular';
import { ExtrasConfig } from '@storybook-extras/preset';
const config: StorybookConfig & ExtrasConfig = {
// if you are using @storybook-extras/markdown
addons: [
{
name: '@storybook-extras/markdown',
options: {
titles: {
'../README.md': 'Custom Title',
},
},
},
],
// if you are using @storybook-extras/preset
extras: {
markdown: {
titles: {
'../README.md': 'Custom Title',
},
},
},
};
export default config;NOTE:
Custom Title processing is dependendant on #20809
Read More
I have written a series of articles to explain the motivation and purpose behind this addon. Feel free to read through.
Addon-Kit is a developer’s dream come trueStorybook Markdown Docs (not mdx)Storybook Markdown Docs (not mdx) Part 2Storybook Addon for Auto Markdown ImportSupport .html files in StorybookCustom Titles for Storybook Docs?
Also make sure to check out these PRs that made this addon possible: