MDX

若要更詳細的整理 Storybook 文件，可以使用 Markdown 語法搭配 JSX 的格式 - MDX。

有二種使用 MDX 方法

• Story in MDX

這種寫法是把 MDX 同時作為Stories與Doc的進入點，原本的xx.stories.js 會變成改用xx.stories.mdx。

• MDX with Story

另一種寫法是Stories與Doc各自分開來寫，各式表述。原本的xx.stories.js 寫 Story，xx.mdx 用以做文件顯示。

在文件需要顯示元件時，可以使用<Story id=”some--id” />將元件鑲嵌在 MDX 中。

Story in MDX

MDX 與 CSF (Component Story Format) 是同一層級的的格式，亦即 MDX 與 CSF 一樣都可以拿來撰寫元件的Stories。

來看看下面這個範例

<!--- Checkbox.stories.mdx -->

import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks';
import { Checkbox } from './Checkbox';

<Meta title="MDX/Checkbox" component={Checkbox} />

# Checkbox

With `MDX` we can define a story for `Checkbox` right in the middle of our
Markdown documentation.

<!--- This is your Story template function, shown here in React -->

export const Template = (args) => <Checkbox {...args} />

<Canvas>
  <Story name="Unchecked" args={{ 
      label: 'Unchecked'
    }}>
    {Template.bind({})}
   </Story>
  <Story name="Checked" args={{ 
      label: 'Unchecked', 
      checked: true 
    }}>
    {Template.bind({})}
   </Story>
  <Story name="Secondary" args={{
    label: 'Secondary', 
    checked: true, 
    appearance: 'secondary'
  }}>
    {Template.bind({})}
   </Story>
</Canvas>

此語法寫完產生的成果如下圖

而原本在 export default 對應 Component 的 decorators 或 parameters 都需要移動到 MDX 的 中。

<!-- MyComponent.stories.mdx --->

<Meta
  title='MyComponent'
  decorators={[ ... ]}
  parameters={{ ... }}
/>

<Story name="story" decorators={[ ... ]} parameters={{ ... }} >
...
</Story>

MDX with Story

如果有現成的Stories.js或是希望關注點分離，就可以使用這樣的方式。

<!-- MyComponent.stories.mdx --->

import { Story } from '@storybook/addon-docs/blocks';

<Story id="some-component--some-name" />

import { Story } from '@storybook/addon-docs/blocks';

# Default

這是一個 Default Task Component

<Story id="task--default"/>

# Pinned

這是一個 Pinned Task Component

<Story id="task--pinned"/>

# Archived

這是一個 Archived Task Component

<Story id="task--archived"/>

我自己也比較喜歡這樣方式做為文件的整理

Documentation-only MDX

如果有時候需要在沒有Stories的狀況下，產生一個說明頁，也可以直接建立一個 **.mdx 來呈現。

Next

當我們把Storybook準備的差不多了，就可以把Storybook先行部署起來，讓專案成員先行去檢視元件的組成是否符合預期，下個單元就要來做部署的相關注意事項及說明。

Reference

MDX - Vue、Angular

MDX Format - Vue、Angular