iT邦幫忙

第 12 屆 iT 邦幫忙鐵人賽

DAY 24
1
Modern Web

玩轉 Storybook系列 第 24

玩轉 Storybook: Day 24 MDX

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 - VueAngular

MDX Format - VueAngular


上一篇
玩轉 Storybook: Day 23 DocsPage and Doc Blocks
下一篇
玩轉 Storybook: Day 25 將 Storybook 持續部署
系列文
玩轉 Storybook30

尚未有邦友留言

立即登入留言