前言
在前端开发中，我们常常需要编写文档或说明文本。而随着组件化的趋势不断发展，原先的文本格式已无法满足需求。此时，markdown 作为一种专门用于编写文档的语言应运而生。在 markdown 中，我们可以轻松地使用各种标记和语法来组织文本，以及插入代码和图片等。
另外，storybook 是一个流行的 UI 组件开发工具，它提供了一个简洁易用的交互式 UI 开发环境。然而，一个完备的 UI 文档不仅仅由代码和截图组成，还需要文字的解释补充，而 storybook 自带的 story 和 mdx 文件，尽管也支持 markdown 语法，还是难以组织和编排文档。这时，就需要一个能够让我们在 storybook 中使用 markdown 语法撰写文档的工具，这个工具就是我们今天介绍的 npm 包：storybook-markdown-jsx。
storybook-markdown-jsx 简介
storybook-markdown-jsx 是一个让您在 storybook 中使用 markdown 语法的工具。它支持使用 JSX 语法，以便您能够更自由地组织和编排 UI 文档。具体来说，它的特点包括：
- 支持使用 markdown 语法编写文本内容。
- 支持使用 JSX 定义组件，并方便地在文本中使用。
- 支持在 markdown 中添加 storybook 组件进行交互式演示。
- 支持通过导入外部 markdown 文件的方式引入文档片段。
安装和使用
安装
安装 storybook-markdown-jsx 很简单。只需要在项目的根目录下使用 npm 或 yarn 命令进行安装即可：
npm install storybook-markdown-jsx --save-dev
yarn add storybook-markdown-jsx --dev
基本使用
storybook-markdown-jsx 可以在 storybook 中直接使用。您只需要在.storybook/config.js 文件中按如下格式导入即可：
-- -------------------- ---- -------
------ - ------------- - ---- -------------------
------ - --------- - ---- -------------------------
------ - ----------------- - ---- ------------------------
------ -------- ---- -------------------------
---------------
-------- -
------ -------
--
------ -
--------- ----------------------------
--
---这里的 options 获取了默认显示的主题样式。withNotes 和 withMarkdownNotes 分别是 storybook 内置的添加笔记和文档的方式。
在 storybook 中，您可以像使用其他组件一样使用 markdown 语法撰写文档，并且可以使用 JSX 语法引入文档所需的组件。例如：
-- -------------------- ---- -------
------ - --------- - ---- -------------------
------ - -- ----- ---- --------
------ ----------- ---- ----------------
------ --- ---- --------------------
------ ------ ---- --------------
------------------------ -------
----------------
----- -
----- ----
--
------ -
--------- -------
--
--
--------------- -- -- ------------ ----这里我们使用了 mdx 和 README 来定义组件的文档部分。
高级使用
除了基本使用之外，storybook-markdown-jsx 还支持各种高级用法。
使用 markdown 中的 storybook 组件
在 markdown 中，我们可以使用 storybook 组件来展示一些交互式的 demo。例如：
-- -------------------- ---- -------
-- -----------
------
------ ----- ---- --------
------ -------- ---- ------------
------ - ------ - ---- ---------------------------
------ ----------- ---- ----------------
----------------
------------ ----------------------------- ------------
----- ------
---------------
-------------------------------
---- -------------------- ---- -------
-------------------------- ----- ---------- -----
-----
---------------
-------- -
------ -------
--
------ -
--------- -------------------
---------
-- --- --------- ---------- -- -------- --
------ ----- ---------------------------- -------- ----------
-------- -
---- --------------------------
------- --------------------
---- -------------- --- ----- ------ -------- -------
--- ---- ---
------
---------
------
--
---
--
---使用 markdown 文件片段
有时候，我们需要把一个大的 markdown 文件拆成多个小块儿。这时，storybook-markdown-jsx 提供了一个引入外部 markdown 文件的使用方式。
例如，我们有一个大的 markdown 文件README.md，而其中一个小块儿是关于MyComponent的。我们可以在 storybook 中通过storyFn.args属性传入该块儿的内容。
## MyComponent
{{MyComponent.md}}在 storybook 中，可以通过如下方式引入MyComponent.md：
-- -------------------- ---- -------
------ ----------- ---- ----------------
------ --- ---- --------------
------------------------ -------
----------------
----- -
----- -- -- -
------------ ------------------------
--------------------------------
--------------
--
--
--
--------------- -- -- ------------ ----您可以看到，我们使用了MDXProvider和MDXRenderer来渲染该块儿，并将其传递给 storybook 的docs参数中。
结尾
storybook-markdown-jsx 是一款很实用的工具，它可以让您在 storybook 中轻松地使用 markdown 语法。我们希望通过这篇教程，能够帮助您更好地了解和使用这个工具。如果您有其他问题或建议，欢迎在评论区与我们联系！
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005731781e8991b448e94ad