Storybook MDX 自定义文档实战用 Guidelines / Dos / Donts 编写组件使用规范【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook在设计系统与组件库的文档中“哪些场景应该用这个组件、哪些场景不应该用”往往比组件 API 本身更难传达。Storybook 的 MDX 文档体系允许在文档页面中自由嵌入任意 JSX 组件因此你可以用Guidelines、Dos、Donts这样的结构为组件编写一组“该做 / 不该做”的视觉化使用规范。本文以 docs/_snippets/storybook-auto-docs-mdx-docs-dos-donts.md 中的代码片段为核心结合 Storybook 仓库中 docs/writing-docs/mdx.mdx 的完整说明讲解这类指南块如何被解析、如何接入完整 MDX 文档、如何让自定义文档被 Storybook 加载并给出可落地的配置与边界提示。读完本文你将能在自己的 Storybook 文档页中写出与官方文档同款的“Do / Dont”清单。一、先看核心片段Guideline.mdx 里发生了什么该关联文档本身是一段被文档站点通过CodeSnippets pathstorybook-auto-docs-mdx-docs-dos-donts.md /复用的 MDX 代码片段见 docs/writing-docs/mdx.mdx#L78完整内容如下Guidelines Dos - Use buttons for the main actions on your page - Identify the primary action and make it 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逐层拆解这段 JSXGuidelines外层容器把整组“使用规范”聚合为一个视觉区块。Dos用于罗列“推荐做法”每一项是一条 Markdown 无序列表项。示例中给出了两条关于按钮使用的正面建议——页面主操作使用按钮、明确唯一主操作并标记为primary。Donts用于罗列“反面做法”警示哪些情况会破坏交互一致性——纯导航行为应使用链接而非按钮、同一 UI 状态下不应出现多个primary按钮。值得注意的是这些组件内部渲染的是标准 Markdown 列表语法说明它们本质上是“用 JSX 包裹 Markdown 内容”的结构化组件与 MDX“在文档里混排 Markdown 与 JSX”的核心机制一脉相承。由于仓库源码中未发现 Storybook 内置同名 Doc Block在 code/addons/docs 目录检索不到Guidelines/Dos/Donts的组件实现按 docs/writing-docs/mdx.mdx#L76-L82 的说明这类组件应来自现成第三方组件或你在项目中自行封装使用时需像普通 JSX 一样先 import 再使用。二、定位这段 JSX 是 MDX 文档解剖的“最后一块积木”官方文档在讲解 MDX 页面结构Anatomy of MDX时把这组代码片段放在了段落的收尾处。它想说明的关键观点是MDX 支持任意 JSX 块。除了内置的 Doc Blocks 之外你还可以引入任何自定义 React 组件这让文档系统极具灵活性——例如想要一个风格化的“dos and donts”清单既可以用现成组件也可以自己写一个。也就是说一篇完整 MDX 组件文档通常由若干用空行分隔的“块”组成依次是JSX 注释{/* ... */}——MDX 中注释须写成 JSX 注释形态import 语句——从storybook/addon-docs/blocks导入Canvas、Meta等 Doc Block并导入对应 CSF 故事文件参考 docs/_snippets/storybook-auto-docs-mdx-docs-imports.mdMeta块——决定文档在侧边栏中的位置参考 docs/_snippets/storybook-auto-docs-mdx-docs-meta-block.md标准 Markdown 内容——按 CommonMark 语法书写说明文字参考 docs/_snippets/storybook-auto-docs-mdx-docs-definition.md任意 JSX 块——包括渲染故事的Canvas of{...} /等 Doc Block参考 docs/_snippets/storybook-auto-docs-mdx-docs-story.md自定义指南组件——即本文主角Guidelines及其内部的 Dos/Donts 列表。由于 MDX 在同一文件中混合了多种语言块之间必须用空行分隔漏掉空行往往会产生难以定位的解析错误这是 docs/writing-docs/mdx.mdx#L42 明确提示的坑。三、把规范清单接入一篇真实可运行的 MDX 页面单独一个Guidelines块无法独立工作需要融入一个完整的 MDX 文档。下面把官方解剖示例中的各部分组合成一个最小可用形态文件结构与命名取自 Checkbox.mdx 示例{/* 1. 文档注释说明本页面目的 */} import { Canvas, Meta } from storybook/addon-docs/blocks; import * as CheckboxStories from ./Checkbox.stories; import { Guidelines, Dos, Donts } from ./GuidelineComponents; // 自定义或第三方组件 {/* 2. Meta 块把文档挂到 Checkbox 的故事旁 */} Meta of{CheckboxStories} / {/* 3. 普通 Markdown 说明 */} # Checkbox A checkbox is a square box that can be activated or deactivated when ticked. {/* 4. 渲染真实故事 */} Canvas of{CheckboxStories.Unchecked} / {/* 5. 使用规范Do / Dont 清单 */} Guidelines Dos - Use checkboxes when users can select multiple options - Keep the label concise and descriptive /Dos Donts - Use a checkbox when a single binary choice is needed (use a switch instead) - Nest dependent options too deeply /Donts /Guidelines几个必须遵守的细节Meta的of应指向故事文件的完整导出集合CheckboxStories而不是组件本身否则生成的文档可能出现渲染问题——docs/_snippets/storybook-auto-docs-mdx-docs-meta-block.md 与其后的 Callout 对此有专门警告。若不想让文档紧贴故事可给Meta传title如Meta titleGuidelines/Checkbox /把节点放到任意导航层级或传name修改侧边栏节点名默认叫 “Docs”。Dos/Donts内部就是 Markdown 列表保持语义与视觉一致即可内容建议形成“正面做法 反面做法”的镜像对照如上例第 1 条 Dos 对应第 1 条 Donts。四、让自定义 MDX 被 Storybook 识别配置与三种摆放策略编写规范页之前需要确保.storybook/main.js|ts|cjs的stories配置把.mdx文件纳入扫描范围并启用storybook/addon-docs。配置原文见 docs/_snippets/storybook-auto-docs-main-mdx-config.mdexport default { // 替换为你的框架如 storybook/react-vite、storybook/vue3-vite 等 framework: storybook/your-framework, stories: [ // 与 stories 一起被扫描的 MDX 文档 ../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx), ], addons: [storybook/addon-docs], };扫描到 MDX 文件后Storybook 会根据文件内容决定页面在侧边栏中的身份官方将其归纳为三类场景1. 依附于已有故事的组件文档使用MetaDoc Block当需要文档与某个故事对齐时用Meta of{...} /关联可用title/name自定义标题与层级。示例见 docs/_snippets/storybook-auto-docs-baseline-example.md。2. 未依附的“文档专用页”如果只提供Meta而不带任何附加块如Meta titleDocumentation /Storybook 会把它当作 “documentation-only” 页面在侧边栏以不同形式渲染完整对比见 docs/_snippets/storybook-auto-docs-mdx-docs-docs-only-page.md。适合承载全局性使用规范、设计原则等非组件级内容。3. 完全省略Meta依靠文件系统定位对于独立页面例如组件测试规范、指南类文档可以安全地省略MetaStorybook 会按文件的物理路径推断标题与位置并覆盖同位置的自动生成文档。这种推断规则与 CSF 3.0 的 auto-title 机制一致。若你要覆盖一个通过tags开启的 Autodocs 页面docs/writing-docs/mdx.mdx#L114 建议同时移除对应的tags配置以避免报错。这三种模式下Guidelines/Dos/Donts清单都可以直接复用因为底层只是“MDX 中任意 JSX 组件”能力的体现。五、源码与文档佐证这条能力链路的边界在哪里为了让这篇指南具备可验证性下面把仓库中支撑该用法的证据链梳理一遍用法出处片段被 docs/writing-docs/mdx.mdx#L76-L78 的 MDX 解剖章节引用官方用它证明“MDX 可容纳任意 React 组件”。这是本用法的第一手依据。Doc Block 家族Storybook 把面向故事文档的官方组件统称为 Doc Blocks如Meta、Canvas、ArgTypes、Controls、Stories等完整的 API 清单见 docs/api/doc-blocks/index.mdxMeta的详细用法见 docs/api/doc-blocks/doc-block-meta.mdx。编写与发布闭环组件故事侧的规范见 docs/writing-stories 目录Autodocs 的开启方式见 docs/writing-docs/autodocs.mdxDoc Blocks 的编排技巧见 docs/writing-docs/doc-blocks.mdx。运行时前提虽然 MDX 生态支持 React、Preact、Vue 等多种运行时但 Storybook 的实现是React-only——你的文档以 React 渲染而故事仍按各自框架Vue、Angular、Web Components、Svelte 等渲染。因此在文档中使用的自定义组件包括 Dos/Donts 组件需要用 React 编写。MDX 版本Storybook 依赖 MDX 3 渲染文档这意味着组件编写须遵循 MDX 3 的 JSX 规范官方在 docs/writing-docs/mdx.mdx#L186 起的 Troubleshooting 部分汇总了迁移与兼容问题。六、实践建议与常见坑结合 docs/writing-docs/mdx.mdx 的常见问题清单在撰写包含规范清单的 MDX 时建议留意块与块之间必须有空行MDX 靠空行区分 Markdown / JSX / import 段落压缩行距极易触发难懂的解析报错。表格、脚注等 GFM 扩展默认不可用当前 Storybook 支持的 MDX 对 CommonMark 之外的表单特性支持有限。若文档规范清单需要表格可在.storybook/main中启用remark-gfm插件参考片段 docs/_snippets/storybook-main-config-remark-options.md。注意该包默认不随 Storybook 安装需单独安装为开发依赖。文档没渲染时先查stories路径如果组件故事无法生成文档多半是stories配置没有指向真实故事位置官方示例为../src/**/*.stories.(js|jsx|mjs|ts|tsx)检查时也要把../src/**/*.mdx一并纳入。inline关闭时控件不同步若通过 Doc Block 的inline配置关闭了故事的内联渲染文档页内控件不会实时更新故事——这是当前实现已知限制规范清单若紧邻可交互故事需留意。大段补充内容用MarkdownDoc Block规范之外的大块 Markdown如 CHANGELOG可交给MarkdownDoc Block 导入渲染见 docs/api/doc-blocks/doc-block-markdown.mdx避免单个 MDX 文件无限膨胀。结语把 “dos and donts” 结构化为Guidelines/Dos/Donts组件本质上是发挥 Storybook MDX 文档的“Markdown 任意 JSX”混合能力故事用 CSF 精确定义组件状态MDX 负责叙事与排版而像使用规范这样的内容则能复用现成或自定义的 React 组件。结合本仓库的 MDX 写作指南、Autodocs 说明与 Doc Blocks API 索引你可以把零散的设计共识沉淀为每个组件旁边可读、可维护、可交互的规范页——这正是 Storybook 作为“组件工作坊”区别于普通静态文档的核心价值所在。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/9 15:22:50 · 阅读 1.2k Storybook MDX 自定义文档实战：用 Guidelines / Dos / Donts 编写组件使用规范
Storybook MDX 自定义文档实战用 Guidelines / Dos / Donts 编写组件使用规范【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook在设计系统与组件库的文档中“哪些场景应该用这个组件、哪些场景不应该用”往往比组件 API 本身更难传达。Storybook 的 MDX 文档体系允许在文档页面中自由嵌入任意 JSX 组件因此你可以用Guidelines、Dos、Donts这样的结构为组件编写一组“该做 / 不该做”的视觉化使用规范。本文以 docs/_snippets/storybook-auto-docs-mdx-docs-dos-donts.md 中的代码片段为核心结合 Storybook 仓库中 docs/writing-docs/mdx.mdx 的完整说明讲解这类指南块如何被解析、如何接入完整 MDX 文档、如何让自定义文档被 Storybook 加载并给出可落地的配置与边界提示。读完本文你将能在自己的 Storybook 文档页中写出与官方文档同款的“Do / Dont”清单。一、先看核心片段Guideline.mdx 里发生了什么该关联文档本身是一段被文档站点通过CodeSnippets pathstorybook-auto-docs-mdx-docs-dos-donts.md /复用的 MDX 代码片段见 docs/writing-docs/mdx.mdx#L78完整内容如下Guidelines Dos - Use buttons for the main actions on your page - Identify the primary action and make it 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逐层拆解这段 JSXGuidelines外层容器把整组“使用规范”聚合为一个视觉区块。Dos用于罗列“推荐做法”每一项是一条 Markdown 无序列表项。示例中给出了两条关于按钮使用的正面建议——页面主操作使用按钮、明确唯一主操作并标记为primary。Donts用于罗列“反面做法”警示哪些情况会破坏交互一致性——纯导航行为应使用链接而非按钮、同一 UI 状态下不应出现多个primary按钮。值得注意的是这些组件内部渲染的是标准 Markdown 列表语法说明它们本质上是“用 JSX 包裹 Markdown 内容”的结构化组件与 MDX“在文档里混排 Markdown 与 JSX”的核心机制一脉相承。由于仓库源码中未发现 Storybook 内置同名 Doc Block在 code/addons/docs 目录检索不到Guidelines/Dos/Donts的组件实现按 docs/writing-docs/mdx.mdx#L76-L82 的说明这类组件应来自现成第三方组件或你在项目中自行封装使用时需像普通 JSX 一样先 import 再使用。二、定位这段 JSX 是 MDX 文档解剖的“最后一块积木”官方文档在讲解 MDX 页面结构Anatomy of MDX时把这组代码片段放在了段落的收尾处。它想说明的关键观点是MDX 支持任意 JSX 块。除了内置的 Doc Blocks 之外你还可以引入任何自定义 React 组件这让文档系统极具灵活性——例如想要一个风格化的“dos and donts”清单既可以用现成组件也可以自己写一个。也就是说一篇完整 MDX 组件文档通常由若干用空行分隔的“块”组成依次是JSX 注释{/* ... */}——MDX 中注释须写成 JSX 注释形态import 语句——从storybook/addon-docs/blocks导入Canvas、Meta等 Doc Block并导入对应 CSF 故事文件参考 docs/_snippets/storybook-auto-docs-mdx-docs-imports.mdMeta块——决定文档在侧边栏中的位置参考 docs/_snippets/storybook-auto-docs-mdx-docs-meta-block.md标准 Markdown 内容——按 CommonMark 语法书写说明文字参考 docs/_snippets/storybook-auto-docs-mdx-docs-definition.md任意 JSX 块——包括渲染故事的Canvas of{...} /等 Doc Block参考 docs/_snippets/storybook-auto-docs-mdx-docs-story.md自定义指南组件——即本文主角Guidelines及其内部的 Dos/Donts 列表。由于 MDX 在同一文件中混合了多种语言块之间必须用空行分隔漏掉空行往往会产生难以定位的解析错误这是 docs/writing-docs/mdx.mdx#L42 明确提示的坑。三、把规范清单接入一篇真实可运行的 MDX 页面单独一个Guidelines块无法独立工作需要融入一个完整的 MDX 文档。下面把官方解剖示例中的各部分组合成一个最小可用形态文件结构与命名取自 Checkbox.mdx 示例{/* 1. 文档注释说明本页面目的 */} import { Canvas, Meta } from storybook/addon-docs/blocks; import * as CheckboxStories from ./Checkbox.stories; import { Guidelines, Dos, Donts } from ./GuidelineComponents; // 自定义或第三方组件 {/* 2. Meta 块把文档挂到 Checkbox 的故事旁 */} Meta of{CheckboxStories} / {/* 3. 普通 Markdown 说明 */} # Checkbox A checkbox is a square box that can be activated or deactivated when ticked. {/* 4. 渲染真实故事 */} Canvas of{CheckboxStories.Unchecked} / {/* 5. 使用规范Do / Dont 清单 */} Guidelines Dos - Use checkboxes when users can select multiple options - Keep the label concise and descriptive /Dos Donts - Use a checkbox when a single binary choice is needed (use a switch instead) - Nest dependent options too deeply /Donts /Guidelines几个必须遵守的细节Meta的of应指向故事文件的完整导出集合CheckboxStories而不是组件本身否则生成的文档可能出现渲染问题——docs/_snippets/storybook-auto-docs-mdx-docs-meta-block.md 与其后的 Callout 对此有专门警告。若不想让文档紧贴故事可给Meta传title如Meta titleGuidelines/Checkbox /把节点放到任意导航层级或传name修改侧边栏节点名默认叫 “Docs”。Dos/Donts内部就是 Markdown 列表保持语义与视觉一致即可内容建议形成“正面做法 反面做法”的镜像对照如上例第 1 条 Dos 对应第 1 条 Donts。四、让自定义 MDX 被 Storybook 识别配置与三种摆放策略编写规范页之前需要确保.storybook/main.js|ts|cjs的stories配置把.mdx文件纳入扫描范围并启用storybook/addon-docs。配置原文见 docs/_snippets/storybook-auto-docs-main-mdx-config.mdexport default { // 替换为你的框架如 storybook/react-vite、storybook/vue3-vite 等 framework: storybook/your-framework, stories: [ // 与 stories 一起被扫描的 MDX 文档 ../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx), ], addons: [storybook/addon-docs], };扫描到 MDX 文件后Storybook 会根据文件内容决定页面在侧边栏中的身份官方将其归纳为三类场景1. 依附于已有故事的组件文档使用MetaDoc Block当需要文档与某个故事对齐时用Meta of{...} /关联可用title/name自定义标题与层级。示例见 docs/_snippets/storybook-auto-docs-baseline-example.md。2. 未依附的“文档专用页”如果只提供Meta而不带任何附加块如Meta titleDocumentation /Storybook 会把它当作 “documentation-only” 页面在侧边栏以不同形式渲染完整对比见 docs/_snippets/storybook-auto-docs-mdx-docs-docs-only-page.md。适合承载全局性使用规范、设计原则等非组件级内容。3. 完全省略Meta依靠文件系统定位对于独立页面例如组件测试规范、指南类文档可以安全地省略MetaStorybook 会按文件的物理路径推断标题与位置并覆盖同位置的自动生成文档。这种推断规则与 CSF 3.0 的 auto-title 机制一致。若你要覆盖一个通过tags开启的 Autodocs 页面docs/writing-docs/mdx.mdx#L114 建议同时移除对应的tags配置以避免报错。这三种模式下Guidelines/Dos/Donts清单都可以直接复用因为底层只是“MDX 中任意 JSX 组件”能力的体现。五、源码与文档佐证这条能力链路的边界在哪里为了让这篇指南具备可验证性下面把仓库中支撑该用法的证据链梳理一遍用法出处片段被 docs/writing-docs/mdx.mdx#L76-L78 的 MDX 解剖章节引用官方用它证明“MDX 可容纳任意 React 组件”。这是本用法的第一手依据。Doc Block 家族Storybook 把面向故事文档的官方组件统称为 Doc Blocks如Meta、Canvas、ArgTypes、Controls、Stories等完整的 API 清单见 docs/api/doc-blocks/index.mdxMeta的详细用法见 docs/api/doc-blocks/doc-block-meta.mdx。编写与发布闭环组件故事侧的规范见 docs/writing-stories 目录Autodocs 的开启方式见 docs/writing-docs/autodocs.mdxDoc Blocks 的编排技巧见 docs/writing-docs/doc-blocks.mdx。运行时前提虽然 MDX 生态支持 React、Preact、Vue 等多种运行时但 Storybook 的实现是React-only——你的文档以 React 渲染而故事仍按各自框架Vue、Angular、Web Components、Svelte 等渲染。因此在文档中使用的自定义组件包括 Dos/Donts 组件需要用 React 编写。MDX 版本Storybook 依赖 MDX 3 渲染文档这意味着组件编写须遵循 MDX 3 的 JSX 规范官方在 docs/writing-docs/mdx.mdx#L186 起的 Troubleshooting 部分汇总了迁移与兼容问题。六、实践建议与常见坑结合 docs/writing-docs/mdx.mdx 的常见问题清单在撰写包含规范清单的 MDX 时建议留意块与块之间必须有空行MDX 靠空行区分 Markdown / JSX / import 段落压缩行距极易触发难懂的解析报错。表格、脚注等 GFM 扩展默认不可用当前 Storybook 支持的 MDX 对 CommonMark 之外的表单特性支持有限。若文档规范清单需要表格可在.storybook/main中启用remark-gfm插件参考片段 docs/_snippets/storybook-main-config-remark-options.md。注意该包默认不随 Storybook 安装需单独安装为开发依赖。文档没渲染时先查stories路径如果组件故事无法生成文档多半是stories配置没有指向真实故事位置官方示例为../src/**/*.stories.(js|jsx|mjs|ts|tsx)检查时也要把../src/**/*.mdx一并纳入。inline关闭时控件不同步若通过 Doc Block 的inline配置关闭了故事的内联渲染文档页内控件不会实时更新故事——这是当前实现已知限制规范清单若紧邻可交互故事需留意。大段补充内容用MarkdownDoc Block规范之外的大块 Markdown如 CHANGELOG可交给MarkdownDoc Block 导入渲染见 docs/api/doc-blocks/doc-block-markdown.mdx避免单个 MDX 文件无限膨胀。结语把 “dos and donts” 结构化为Guidelines/Dos/Donts组件本质上是发挥 Storybook MDX 文档的“Markdown 任意 JSX”混合能力故事用 CSF 精确定义组件状态MDX 负责叙事与排版而像使用规范这样的内容则能复用现成或自定义的 React 组件。结合本仓库的 MDX 写作指南、Autodocs 说明与 Doc Blocks API 索引你可以把零散的设计共识沉淀为每个组件旁边可读、可维护、可交互的规范页——这正是 Storybook 作为“组件工作坊”区别于普通静态文档的核心价值所在。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考