GitHub/storybook
1
0
Fork 0
mirror of https://github.com/storybookjs/storybook.git synced 2025-04-04 19:21:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

Update /docs/writing-docs/mdx for Docs/MDX 2

Browse Source
This commit is contained in:
Kyle Gach 2022-12-14 14:17:17 -07:00
parent a9e0bb735a
commit 76982ec019
5 changed files with 187 additions and 235 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/snippets/common/my-component-with-custom-syntax-highlight.mdx.mdx
View File

@ -1,11 +1,10 @@
````md
<!-- MyComponent.stories.mdx -->
import { Meta } from '@storybook/addon-docs';
{/* MyComponent.mdx */}
import { Meta } from '@storybook/blocks';
import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
<Meta title="A Storybook story with a custom syntax highlight for SCSS" />
<Meta title="A Storybook doc with a custom syntax highlight for SCSS" />
# SCSS example

4
docs/snippets/common/my-component-with-global-syntax-highlight.mdx.mdx
View File

@ -1,7 +1,7 @@
```md
<!-- MyComponent.stories.mdx -->
{/* MyComponent.mdx */}
import { Meta } from '@storybook/addon-docs';
import { Meta } from '@storybook/blocks';
<Meta title="A storybook story with syntax highlight registered globally" />

3
docs/snippets/common/storybook-main-enable-transcludemarkdown.js.mdx
View File

@ -4,8 +4,7 @@
module.exports = {
stories: [
//👇 Changes the load order of our stories. First loads the Changelog page
'../src/Changelog.stories.mdx',
'../stories/**/*.stories.mdx',
'../src/Changelog.mdx',
'../stories/**/*.stories.@(js|jsx|ts|tsx)',
],
addons: [

34
docs/snippets/react/checkbox-story.mdx.mdx
View File

@ -1,38 +1,16 @@
```md
<!-- Checkbox.stories.mdx -->
{/* Checkbox.mdx */}
import { Canvas, Meta, Story } from '@storybook/addon-docs';
import { Canvas, Meta, Story } from '@storybook/blocks';
import * as CheckboxStories from './Checkbox.stories';
import { Checkbox } from './Checkbox';
<Meta title="MDX/Checkbox" component={Checkbox} />
<Meta of={CheckboxStories} />
# Checkbox
With `MDX`, we can define a story for `Checkbox` right in the middle of our
Markdown documentation.
With `MDX` we can compose Markdown documentation with `Checkbox` stories and interactive controls.
<Canvas>
<Story
name="Unchecked"
args={{
label: 'Unchecked',
}}
render={(args) => <Checkbox {...args} />} />
<Story
name="Checked"
args={{
label: 'Unchecked',
checked: true,
}}
render={(args) => <Checkbox {...args} />} />
<Story
name="Secondary"
args={{
label: 'Secondary',
checked: true,
appearance: 'secondary',
}}
render={(args) => <Checkbox {...args} />} />
<Story of={CheckboxStories.Unchecked} />
</Canvas>
```

374
docs/writing-docs/mdx.md
View File

@ -2,51 +2,33 @@
title: 'MDX'
---
<div class="aside">
💡 Currently, there's an issue using MDX stories with IE11, which **doesn't affect** the [Docs page](./docs-page.md). It's a known MDX issue, and once it's solved, Storybook's MDX implementation will be updated accordingly.
</div>
MDX is a [standard file format](https://mdxjs.com/) that combines Markdown with JSX. It means you can use Markdown’s terse syntax (such as # heading) for your documentation, write stories that compile to our component story format, and freely embed JSX component blocks at any point in the file. All at once.
[MDX](https://mdxjs.com/) files mix Markdown and Javascript/JSX to create rich interactive documentation. You can use Markdown’s readable syntax (such as `# heading`) for your documentation, include stories defined in [Component Story Format (CSF)](../api/csf.md), and freely embed JSX component blocks at any point in the file. All at once.
In addition, you can write pure documentation pages in MDX and add them to Storybook alongside your stories.
![MDX simple example result](./mdx-hero.png)
<div class="aside">
Writing stories directly in MDX was deprecated in Storybook 7. Please reference the <LinkWithVersion version="6.5" href="./mdx.md">previous documentation</LinkWithVersion> for guidance on that feature.
</div>
## Basic example
Let's get started with an example that combines Markdown with a single story:
Let's get started with an example, `Checkbox.mdx`, that combines Markdown with a single story
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'react/checkbox-story.mdx.mdx',
'angular/checkbox-story.mdx.mdx',
'vue/checkbox-story.mdx-2.mdx.mdx',
'vue/checkbox-story.mdx-3.mdx.mdx',
'svelte/checkbox-story.mdx.mdx',
'common/checkbox-story.mdx.mdx',
]}
usesCsf3
csf2Path="writing-docs/mdx#snippet-checkbox-story"
/>
<!-- prettier-ignore-end -->
And here's how that's rendered in Storybook:
![MDX simple example result](./mdx-simple.png)
As you can see, a lot is going on here. We're writing Markdown, we're writing JSX, and we're also defining Storybook stories that are drop-in compatible with the entire Storybook ecosystem.
Let's break it down.
## MDX-flavored CSF
MDX-flavored [Component Story Format (CSF)](../api/csf.md) includes a collection of components called "Doc Blocks", that allow Storybook to translate MDX files into Storybook stories. MDX-defined stories are identical to regular Storybook stories, so they can be used with Storybook's entire ecosystem of addons and view layers.
For example, here's the first story from the Checkbox example above, rewritten in CSF:
This MDX file references a story file, Checkbox.stories.js, that is written in [Component Story Format (CSF)](../api/csf.md):
<!-- prettier-ignore-start -->
@ -60,120 +42,211 @@ For example, here's the first story from the Checkbox example above, rewritten i
<!-- prettier-ignore-end -->
There's a one-to-one mapping from the code in MDX to CSF. As a user, this means your existing Storybook knowledge should translate between the two.
And here's how that's rendered in Storybook:
## Writing stories
![MDX simple example result](./mdx-simple.png)
Let's look at a more realistic example to see how MDX works:
There’s a lot going on here. We're writing Markdown, we're writing JSX, and we're also defining and referencing Storybook stories that are drop-in compatible with the entire Storybook ecosystem.
<!-- prettier-ignore-start -->
Let’s break it down.
<CodeSnippets
paths={[
'react/badge-story.mdx.mdx',
'angular/badge-story.mdx.mdx',
'vue/badge-story.mdx-2.mdx.mdx',
'vue/badge-story.mdx-3.mdx.mdx',
'svelte/badge-story.mdx.mdx',
]}
usesCsf3
csf2Path="writing-docs/mdx#snippet-badge-story"
/>
### MDX and CSF
<!-- prettier-ignore-end -->
The first thing you’ll notice is that your component docs consists of two files in two different formats: one for defining your stories, and the second one for documenting them. This split leverages the best qualities of each format:
And here's how that gets rendered in Storybook:
- **CSF** is great for succinctly defining stories (component examples). If you use TypeScript, it also provides type safety and autocompletion.
- **MDX** is great for writing structured documentation and composing it with interactive JSX elements.
![MDX page](./mdx-page.png)
If you’re coming from an older version of Storybook, you might be accustomed to using MDX both for documentation AND for defining stories in the same `.stories.mdx` file. We’ve deprecated this functionality and plan to remove it in a future version of Storybook. We provide migration scripts to help you onto the new format.
## Customizing ArgTypes with MDX
### Anatomy of MDX
As already mentioned [above](#mdx-flavored-csf), there's a one-to-one mapping between MDX and CSF.
Assuming you’re already familiar with CSF, we can dissect the MDX side of things a bit further.
Based on this principle, if the Badge story included the following `ArgTypes`:
The document consists of a number of blocks separated by blank lines. Since MDX mixes a few different languages together, it uses those blank lines to help distinguish where one starts and the next begins. Failing to separate blocks by whitespace can cause (sometimes inscrutable) parse errors.
<!-- prettier-ignore-start -->
Going through the code blocks in sequence:
<CodeSnippets
paths={[
'common/badge-story-custom-argtypes.js.mdx',
]}
/>
```jsx
{
/* Checkbox.mdx */
}
```
<!-- prettier-ignore-end -->
Comments in MDX are JSX blocks that contain JS comments.
Transitioning them into MDX format is relatively seamless and would only require the following change to the story:
```jsx
import { Canvas, Meta, Story } from '@storybook/blocks';
import * as CheckboxStories from './Checkbox.stories';
```
<!-- prettier-ignore-start -->
Imports the components and stories that will be used in the JSX throughout the rest of the file.
<CodeSnippets
paths={[
'common/badge-story-custom-argtypes.mdx.mdx',
]}
/>
```jsx
<Meta of={CheckboxStories} />
```
<!-- prettier-ignore-end -->
The `Meta` block defines where in the sidebar the document will be placed. In this case, it is placed alongside the Checkbox’s stories. By default, the docs sidebar node is titled `"Docs"`, but this can be customized by passing a `name` prop (e.g. `<Meta of={CheckboxStories} name="Info" />`). If you want to place a docs node at an arbitrary point in the navigation hierarchy, you can use the `title` prop (e.g. `<Meta title="path/to/node" />`).
And here's how that gets rendered in Storybook:
```jsx
# Checkbox
<video autoPlay muted playsInline loop>
<source
src="custom-argTypes-mdx-optimized.mp4"
type="video/mp4"
/>
</video>
With `MDX` we can compose Markdown documentation with
`Checkbox` stories and interactive controls.
```
<div class="aside">
MDX2 supports standard markdown ([”commonmark”](https://commonmark.org/)) by default, and can be extended to support [GitHub-flavored markdown (GFM)](https://github.github.com/gfm) and other other extensions (see [Breaking changes](#breaking-changes), below).
If you find yourself with a considerably sized <code>argTypes</code> implementation. You can extract them into a variable and pass them as a prop.
```jsx
<Canvas>
<Story of={CheckboxStories.Unchecked} />
</Canvas>
```
</div>
Finally, MDX supports blocks of arbitrary JSX.
## Embedding stories
In this case, we are leveraging “Doc Blocks”, which is a library of documentation components that are designed to work with Storybook stories to do things like show your stories, your component APIs & controls for interacting with your components inside your documentation, among other utilities.
Suppose you have an existing story and want to embed it into your docs. Here's how to show a story with ID some--id. Check the browser URL in Storybook v5+ to find a story's ID.
In addition to Doc Blocks, MDX can incorporate arbitrary React components, making it a very flexible documentation system. Suppose you want a stylized list of “dos and don’ts” for your component, you can use off-the-shelf components or write your own.
<!-- prettier-ignore-start -->
```jsx
<Guidelines>
<Dos>
- Use buttons for the main actions on your page - Identify the primary action and make that
`primary`
</Dos>
<Donts>
- Use a button when a link will do (e.g. for navigation only actions) - Use multiple primary
buttons in a single UI state
</Donts>
</Guidelines>
```
<CodeSnippets
paths={[
'common/component-story-mdx-embed.mdx.mdx',
]}
/>
### Known limitations
<!-- prettier-ignore-end -->
- While MDX2 supports a variety of runtimes (React, Preact, Vue), Storybook’s implementation is React-only. That means that your documentation is rendered in React, while your stories are rendered in the runtime of your choice (React, Vue, Angular, Web-components, Svelte, etc.)
You can also use the rest of the MDX features in conjunction with embedding. That includes source, preview, and prop tables.
## Breaking changes
## Decorators and parameters
There are a lot of breaking changes if you’re moving from MDX1 to MDX2. As far as we know, all of these are due to changes in the MDX library itself, rather than changes to Storybook’s usage. Nevertheless, as an MDX user, you will probably need to update your MDX files as part of the upgrade. MDX has published their own [Migration guide](https://mdxjs.com/migrating/v2/#update-mdx-files). Here we try to summarize some of the key changes for Storybook users.
To add decorators and parameters in MDX:
### Custom components apply differently
<!-- prettier-ignore-start -->
From the MDX migration guide:
<CodeSnippets
paths={[
'common/component-story-mdx-decorators-params.mdx.mdx',
]}
/>
> We now “sandbox” components, for lack of a better name. It means that when you pass a component for `h1`, it does get used for `# hi` but not for `<h1>hi</h1>`
<!-- prettier-ignore-end -->
This means that the first heading in the following example gets replaced, whereas the second heading does not. This doesn’t sound like a big change, but in practice is extremely disruptive and manifests itself in a variety of ways. Unfortunately, this cannot be automatically converted in a safe way.
Global parameters and decorators work just like before.
```jsx
# some heading
<h1>another heading</h1>
```
### Lack of Github Flavored Markdown (GFM)
Also from the MDX migration guide:
> We turned off GFM features in MDX by default. GFM extends CommonMark to add autolink literals, footnotes, strikethrough, tables, and task lists. If you do want these features, you can use a plugin. How to do so is described in [our guide on GFM](https://mdxjs.com/guides/gfm/).
In Storybook, you can apply MDX options, including plugins, in the main configuration file:
```js
// .storybook/main.js
import remarkGfm from 'remark-gfm';
module.exports = {
// ...
addons: [
// ...
{
name: '@storybook/addon-docs',
options: {
mdxCompileOptions: {
remarkPlugins: [remarkGfm],
},
},
},
],
};
```
### Automigration
We’ve created an automigration to make this easier, and are including things that we can fix automatically as we find them.
```jsx
npx storybook@next automigrate --fixId mdx1to2
```
<!-- We’ll be documenting the most disruptive changes that we can’t automigrate as they are reported by the community. So far, the list of top offenders include. -->
## Documentation-only MDX
Typically, when you use Storybook MDX, you define stories in the MDX, and documentation is automatically associated with those stories. But what if you want to write Markdown-style documentation without any stories inside?
Suppose you don't define stories in your MDX. In that case, you can write MDX documentation and associate it with an existing story or embed that MDX as its own documentation node in your Storybook's navigation.
If you don't define a Meta, you can write Markdown and associate with an existing story. See ["CSF Stories with MDX Docs"](../../addons/docs/docs/recipes.md#csf-stories-with-mdx-docs).
To get a "documentation-only story" in your UI, define a `<Meta>` as you normally would, but don't define any stories. It will show up in your UI as a documentation node:
MDX documents do not have to reference stories. If the `<Meta>` only has a `title` and no `of` prop, (for example, `<Meta title="Intro" />`) and if you use no `<Story>` blocks, that document will be considered "documentation-only" and appear differently in the sidebar navigation menu:
![MDX docs only story](./mdx-documentation-only.png)
### Syntax highlighting
### Creating a Changelog story
One common use case for documentation-only MDX is importing a project's `CHANGELOG.md`, so that users can easily refer to the CHANGELOG via a documentation node in Storybook.
First, ensure that `transcludeMarkdown` is set to `true` in `main.js`:
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/storybook-main-enable-transcludemarkdown.js.mdx',
]}
/>
<!-- prettier-ignore-end -->
Then, import the markdown and treat the imported file as a component in the MDX file:
```mdx
import { Meta } from '@storybook/blocks';
import Changelog from '../CHANGELOG.md';
<Meta title="Changelog" />
<Changelog />
```
![Changelog markdown in an MDX story](./changelog-mdx-md-transcludemarkdown-optimized.png)
## Linking to other stories and pages
When writing MDX, you may want to provide links to other stories or documentation pages and sections. You can use the `path` query string.
Considering a story with ID `some--id`, this redirects to the **Docs** tab of the story:
```md
[Go to specific documentation page](?path=/docs/some--id)
```
This redirects to the **Canvas** tab of the story:
```md
[Go to specific story canvas](?path=/story/some--id)
```
You can also use anchors to target a specific section of a page:
```md
[Go to the conclusion of the documentation page](?path=/docs/some--id#conclusion)
```
<div class="aside">
💡 By applying this pattern with the Controls addon, all anchors will be ignored in Canvas based on how Storybook handles URLs to track the args values.
</div>
![MDX anchor example](./mdx-anchor.webp)
## Syntax highlighting
When writing your documentation with Storybook and MDX, you get syntax highlighting out of the box for a handful of popular languages (Javascript, Markdown, CSS, HTML, Typescript, GraphQL). For other formats, for instance, SCSS, you'll need to extend the syntax highlighter manually:
@ -216,100 +289,3 @@ Write your documentation as you usually would, and your existing SCSS code block
/>
<!-- prettier-ignore-end -->
### Creating a Changelog story
One common use case for MDX-only docs stories is importing a project's `CHANGELOG.md` into an MDX story, so that users can easily refer to the CHANGELOG via a documentation node in Storybook.
First, ensure that `transcludeMarkdown` is set to `true` in `main.js`:
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/storybook-main-enable-transcludemarkdown.js.mdx',
]}
/>
<!-- prettier-ignore-end -->
Then, import the markdown and treat the imported file as a component in the MDX file:
```mdx
import { Meta } from '@storybook/addon-docs';
import Changelog from '../CHANGELOG.md';
<Meta title="Changelog" />
<Changelog />
```
![Changelog markdown in an MDX story](./changelog-mdx-md-transcludemarkdown-optimized.png)
## Linking to other stories and pages
When writing MDX, you may want to provide links to other stories or documentation pages and sections. You can use the `path` query string.
Considering a story with ID `some--id`, this redirects to the **Docs** tab of the story:
```md
[Go to specific documentation page](?path=/docs/some--id)
```
This redirects to the **Canvas** tab of the story:
```md
[Go to specific story canvas](?path=/story/some--id)
```
You can also use anchors to target a specific section of a page:
```md
[Go to the conclusion of the documentation page](?path=/docs/some--id#conclusion)
```
<div class="aside">
💡 By applying this pattern with the Controls addon, all anchors will be ignored in Canvas based on how Storybook handles URLs to track the args values.
</div>
![MDX anchor example](./mdx-anchor.webp)
## MDX file names
Unless you use a custom [Webpack configuration](../builders/webpack.md#extending-storybooks-webpack-config), all of your MDX files should have the suffix `*.stories.mdx`. This tells Storybook to apply its special processing to the `<Meta>` and `<Story>` elements in the file.
<div class="aside">
Be sure to update [.storybook/main.js](../configure/overview.md#configure-story-rendering) file to load `.stories.mdx` stories, as per the addon-docs installation instructions.
</div>
## MDX 2
Starting with Storybook 6.5, [MDX 2](https://mdxjs.com/blog/v2/) is introduced as an experimental opt-in feature. To enable it, you'll need to take additional steps. Documented below is our recommendation.
Run the following command to add the necessary dependency.
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/storybook-mdx2-install.yarn.js.mdx',
'common/storybook-mdx2-install.npm.js.mdx',
]}
/>
<!-- prettier-ignore-end -->
Update your Storybook configuration (in `.storybook/main.js|ts`) and add the `previewMdx2` feature flag as follows:
<!-- prettier-ignore-start -->
<CodeSnippets
paths={[
'common/storybook-main-enable-mdx2.js.mdx',
]}
/>
<!-- prettier-ignore-end -->