npm 包 storybook-markdown-jsx 使用教程

阅读时长 7 分钟读完

前言

在前端开发中,我们常常需要编写文档或说明文本。而随着组件化的趋势不断发展,原先的文本格式已无法满足需求。此时,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 很简单。只需要在项目的根目录下使用 npmyarn 命令进行安装即可:

基本使用

storybook-markdown-jsx 可以在 storybook 中直接使用。您只需要在.storybook/config.js 文件中按如下格式导入即可:

-- -------------------- ---- -------
------ - ------------- - ---- -------------------
------ - --------- - ---- -------------------------
------ - ----------------- - ---- ------------------------
------ -------- ---- -------------------------

---------------
  -------- -
    ------ -------
  --
  ------ -
    --------- ----------------------------
  --
---

这里的 options 获取了默认显示的主题样式。withNoteswithMarkdownNotes 分别是 storybook 内置的添加笔记和文档的方式。

在 storybook 中,您可以像使用其他组件一样使用 markdown 语法撰写文档,并且可以使用 JSX 语法引入文档所需的组件。例如:

-- -------------------- ---- -------
------ - --------- - ---- -------------------
------ - -- ----- ---- --------

------ ----------- ---- ----------------

------ --- ---- --------------------
------ ------ ---- --------------

------------------------ -------
  ----------------
    ----- -
      ----- ----
    --
    ------ -
      --------- -------
    --
  --
  --------------- -- -- ------------ ----

这里我们使用了 mdxREADME 来定义组件的文档部分。

高级使用

除了基本使用之外,storybook-markdown-jsx 还支持各种高级用法。

使用 markdown 中的 storybook 组件

在 markdown 中,我们可以使用 storybook 组件来展示一些交互式的 demo。例如:

-- -------------------- ---- -------
-- -----------

------
------ ----- ---- --------
------ -------- ---- ------------
------ - ------ - ---- ---------------------------

------ ----------- ---- ----------------

----------------
  ------------ ----------------------------- ------------
    ----- ------
  ---------------
  -------------------------------
--
-- -------------------- ---- -------

-------------------------- ----- ---------- -----

-----
---------------
  -------- -
    ------ -------
  --
  ------ -
    --------- -------------------
      ---------
      -- --- --------- ---------- -- -------- --
      ------ ----- ---------------------------- -------- ----------
      -------- -
        ---- --------------------------
          ------- --------------------
            ---- -------------- --- ----- ------ -------- -------
              --- ---- ---
            ------
          ---------
        ------
      --
    ---
  --
---

使用 markdown 文件片段

有时候,我们需要把一个大的 markdown 文件拆成多个小块儿。这时,storybook-markdown-jsx 提供了一个引入外部 markdown 文件的使用方式。

例如,我们有一个大的 markdown 文件README.md,而其中一个小块儿是关于MyComponent的。我们可以在 storybook 中通过storyFn.args属性传入该块儿的内容。

在 storybook 中,可以通过如下方式引入MyComponent.md

-- -------------------- ---- -------
------ ----------- ---- ----------------
------ --- ---- --------------

------------------------ -------
  ----------------
    ----- -
      ----- -- -- -
        ------------ ------------------------
          --------------------------------
        --------------
      --
    --
  --
  --------------- -- -- ------------ ----

您可以看到,我们使用了MDXProviderMDXRenderer来渲染该块儿,并将其传递给 storybook 的docs参数中。

结尾

storybook-markdown-jsx 是一款很实用的工具,它可以让您在 storybook 中轻松地使用 markdown 语法。我们希望通过这篇教程,能够帮助您更好地了解和使用这个工具。如果您有其他问题或建议,欢迎在评论区与我们联系!

来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/6005731781e8991b448e94ad

纠错
反馈