Storybook 独立文档页实战用 MDX 编写项目级 MDX 指南并接入文档侧边栏【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook导读在 Storybook 中MDX 不仅能用于为某个组件编写与 story 关联的文档还能创建与组件完全解耦的独立文档页standalone documentation page例如项目 onboarding 指南、设计规范、测试用例编写规范等。本篇指南以仓库 docs/_snippets/storybook-auto-docs-standalone-page.md 中完整示例为骨架讲解如何在.storybook/main中启用 MDX、如何编写一份可被 Storybook 自动识别并放入侧边栏的独立 MDX 文档页并结合作者位于 code/addons/docs 的 addon-docs 源码说明其标题推断与“未挂载文档”处理的底层机制。读完你即可在自己的 Storybook 项目中从零落地一份“Getting Started”式的项目级文档页。什么时候该用独立文档页在 MDX 系列文档的编写 MDX 文档主篇中“Working with standalone documentation pages”一节明确指出独立文档页是常见用法它既适用于单个组件也适用于整个项目。典型的落地场景包括编写项目 onboarding新成员上手流程说明告诉新人如何安装依赖、运行开发服务器、贡献代码整理设计/开发规范如 UI 规范、编码规范、Git 提交约定、工具链清单沉淀跨组件的最佳实践如组件测试编写指南、可访问性a11y要求清单。这类内容的特点是它们并不对应某个具体组件的某个具体 story而是依附于目录或项目本身。若仍用Meta of{...}硬绑到某个 story 文件反而会让内容归属错位。因此 Storybook 提供了一套“基于文件系统位置”的放置方式不写 Meta、把文件放在合适目录Storybook 依据文件物理路径在侧边栏中推断标题与层级。第一步在配置中启用 MDX 文档在动手写 MDX 之前需要确认.storybook/main支持.js/.ts/.cjs同时满足两个条件参照配套代码片段 storybook-auto-docs-main-mdx-config.mdstories数组包含 MDX 文件的 glob例如../src/**/*.mdxaddons中注册了storybook/addon-docs编写 MDX 文档的基础 addon。以 CSF 3 风格、TypeScript 配置为例import type { StorybookConfig } from storybook/your-framework; const config: StorybookConfig { // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. framework: storybook/your-framework, stories: [ // Your documentation written in MDX along with your stories goes here ../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx), ], addons: [storybook/addon-docs], }; export default config;在最新风格CSF Next使用defineMain下写法一致只是引入入口变为defineMainimport { defineMain } from storybook/your-framework/node; export default defineMain({ framework: storybook/your-framework, stories: [ ../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx), ], addons: [storybook/addon-docs], });注意storybook/your-framework是占位符需替换为实际框架包例如react-vite、nextjs、vue3-vite、web-components-vite、storybook/angular等代码片段中 Angular、Web Components 等框架均有对应变体。将../src/**/*.mdx加入stories是前提中的前提——若遗漏Storybook 根本不会扫描到你的文档文件也就不会为其生成侧边栏条目。理解三种自定义文档形态主文档 mdx.mdx 的 “Setup custom documentation” 章节把自定义文档划分为三类理解它们能帮你判断独立文档页究竟“独立”在哪形态关键写法侧边栏呈现与既有 story 关联的文档Meta of{CheckboxStories} /作为该 story 相邻的 Docs 节点名称默认 “Docs”可用name改或title指定任意位置纯文档页documentation-onlyMeta titleDocumentation /无of、无其他块被 Storybook 视为“未挂载”文档在侧边栏中单独渲染基于文件系统的独立文档页不写任何 Meta 块依据文件物理路径推断标题与层级渲染为 Docs 条目三种形态的对比见配套片段 storybook-auto-docs-mdx-docs-docs-only-page.md展示Meta有无of/title的差异与 storybook-auto-docs-custom-file.md展示纯基于文件系统、无 Meta 的Select.mdx。本文主角——独立文档页——属于第三类某些使用场景独立页面、组件测试指南等并不需要提供MetaDoc Block可以直接省略它。完整示例一份GettingStarted.mdx下面是 storybook-auto-docs-standalone-page.md 提供的完整文件内容。它是文档正文在 “Working with standalone documentation pages” 小节引用的原始代码块建议新建src/GettingStarted.mdx文件名与目录可按你的项目结构调整并整体复制# Getting Started Welcome! Whether youre a designer or a developer, this guide will help you get started and connect you to the essential resources you need. ## Table of Contents - [Design Resources](#design-resources) - [Figma](#figma) - [UI/UX Design Guidelines](#uiux-design-guidelines) - [Design Assets](#design-assets) - [Development Resources](#development-resources) - [Coding Standards](#coding-standards) - [Version Control](#version-control) - [Development Tools](#development-tools) --- ## Design Resources ### Figma [Figma](https://www.figma.com/) is a collaborative design and prototyping tool. Its the heart of the design process, allowing designers to work together seamlessly. - **Get Access**: If youre not already part of the Figma project, request access from the project lead or manager. ### UI/UX Design Guidelines Before you dive into designing, familiarize yourself with our UI/UX design guidelines. They provide valuable insights into our design philosophy and standards. - [UI/UX Guidelines Document](https://your-design-guidelines-link.com) ### Design Assets All the essential design assets like logos, icons, and brand guidelines can be found in the Figma project. Ensure you have access and familiarize yourself with these assets for consistency. --- ## Development Resources ### Coding Standards Maintaining a consistent code style is essential for collaborative development. Our coding standards document will guide you on best practices. - [Coding Standards Document](https://your-coding-standards-link.com) ### Version Control We use Git for version control. Make sure you have Git installed and are familiar with its basics. ### Development Tools Your development environment is critical. Here are some tools and resources to help you set up your workspace: - **Code Editor**: We recommend using [Visual Studio Code](https://code.visualstudio.com/) for development. Its highly customizable and supports a wide range of extensions. - **Package Manager**: [npm](https://www.npmjs.com/) is the package manager we use for JavaScript projects. Install it to manage project dependencies.上面示例中出现的your-design-guidelines-link.com、your-coding-standards-link.com等为占位链接Figma、VS Code、npm 链接属于示例语境中演示的外部资源引用——实际使用时请全部替换为你们项目的真实内网链接或真实资源地址。解剖这份文档为什么它能“自己长”到侧边栏里把这份GettingStarted.mdx拆开看可以发现它没有任何import { Meta }、也没有任何 Doc Block JSX通篇由纯 Markdown/MDX 语法构成一级标题H1# Getting Started定义文档主标题的语义起点渲染为页面顶部大标题导语段落用一两句话说明文档读者对象designer or developer与文档价值帮助读者快速定位目录Table of Contents使用 Markdown 列表嵌套锚点链接#design-resources等借助标题自动生成的锚点实现页内跳转分隔线---将“设计资源”与“开发资源”两大块视觉区分二级标题H2 三级标题H3组织出Design Resources / Figma、Development Resources / Coding Standards这样的清晰层级加粗列表项 普通列表项用于“Get Access”这类动作提示与资源清单。这里需要特别解释锚点命名的规则示例中的[UI/UX Design Guidelines](#uiux-design-guidelines)指向三级标题 “UI/UX Design Guidelines”其锚点#uiux-design-guidelines由标题文本自动生成——统一转小写、空格转为连字符、非字母数字符号如/被去除。同理Figma→#figma、Version Control→#version-control。如果你的标题写成其他形式请务必让目录里的锚点与渲染出的标题 id 完全对应否则页内跳转会失效。为什么不用写 MetaStorybook 也能确定它的位置这是独立文档页区别于组件文档页的核心机制。文档正文mdx.mdx 的 “Using the File System” 与 “Working with standalone documentation pages” 两节给出了权威解释要点如下省略 Meta 是安全的对于独立页面或组件测试指南等场景可以放心省略 Meta Doc Block位置来自文件物理路径Storybook 会依据文件在磁盘上的实际位置把文档放到侧边栏对应层级推断规则复用 auto-title文档加载后Storybook 使用与CSF 3.0 自动标题auto-title stories相同的启发式规则来推断标题与位置并在侧边栏将其渲染为一个Docs条目可直接覆盖 autodocs若该文件位置原本存在通过tags配置开启的自动生成文档这份自定义 MDX 会覆盖它。主文档在此处特别提示当你覆盖一份由tags开启的自动生成文档页面时建议同时移除对应tags配置以免报错。换句话说src/GettingStarted.mdx这类路径会参与标题的自动推断。想让独立文档出现在某个分组下把它放进对应目录并起一个语义化文件名即可。源码视角未挂载 MDX 在 addon-docs 内部是如何被容忍的从源码可以进一步印证“独立 MDX 页可以被正常渲染”这一设计意图。MetaDoc Block 的实现位于 code/addons/docs/src/blocks/blocks/Meta.tsxtype MetaProps BaseAnnotations { of?: ModuleExports; title?: string }; export const Meta: FCMetaProps ({ of }) { const context useContext(DocsContext); if (of) { context.referenceMeta(of, true); } try { const primary context.storyById(); return Anchor storyId{primary.id} /; } catch { // It is possible to use Meta in an unattached MDX file return null; } };从这段实现可以推断出的关键设计是仅当传入ofprop 时Meta 才会调用context.referenceMeta(of, true)把文档挂载到对应 story 的元数据上当 MDX 中没有任何 story 上下文可用时例如纯独立文档页context.storyById()会抛错Meta 捕获异常后直接返回null而不是中断整篇文档渲染源码注释 “It is possible to useMetain an unattached MDX file” 与文档中 documentation-only 页面、独立文档页的行为描述完全一致说明“未挂载的 MDX 文件是被官方设计支持的一等公民”。这也解释了为什么示例文件不写 Meta 也能工作文档渲染链路并不强制要求每个 MDX 都必须锚定一个 story 上下文。从独立文档页进阶内容更丰富时该怎么做独立文档页跑通之后如果希望它包含更多结构化内容主文档 mdx.mdx 还提供了若干“不改变独立定位”的扩展方向可对照使用想突出与组件无关的规范性条目dos donts 等可在 MDX 中嵌入任意 React 组件或使用 storybook-auto-docs-starter-example.md 展示的Story of{...} /、Controls /等 Doc Block 组合需要导入已有 Markdown如 CHANGELOG使用MarkdownDoc Block 渲染外部.md内容需要在一个页面里文档化多个组件直接在文件中用Canvas of{...} /、Story of{...} meta{...} /引用多份 story参见 storybook-auto-docs-mdx-file.md 的Page.mdx示例需要链接到其他文档页或 story文档内支持 Storybook 内部导航链接。指向某文档条目用?path/docs/some--id需要精确到节选锚点时追加#conclusion指向 Canvas 中的 story 则用?path/story/some--id。常见误区速查忘了把../src/**/*.mdx加进stories文档不会被扫描侧边栏自然没有条目。这是最常见的“MDX 不生效”原因在独立页里强行写Meta of{...}会使页面重新变成“挂载”在某个 story 下的组件文档失去独立定位锚点与标题不一致目录链接#xxx若与标题自动生成的 id 不匹配页内跳转会 404想覆盖 autodocs 却保留tags按官方提示应一并移除对应自动文档的tags配置避免冲突报错编写外部链接时保留占位 URL示例中的your-design-guidelines-link.com等只是模板发布前务必替换。小结一份不写任何 Meta、纯由 Markdown 结构化内容组成的GettingStarted.mdx之所以能自动出现在 Storybook 侧边栏并被渲染为独立Docs页靠的是 Storybook 对“未挂载 MDX”的设计支持启用 MDX 扫描 glob、省略 Meta Doc Block、按文件物理路径复用 CSF 3.0 auto-title 规则推断标题与层级。本文提供的完整示例可直接作为项目 onboarding 页、规范页或指南页的起点结合仓库内的配套片段与 Meta.tsx 源码你既可以照抄落地也能在遇到“文档没出现”“位置不对”等问题时快速定位根因。想进一步了解自动生成的组件文档与 Doc Block 用法可继续阅读仓库中 docs/writing-docs/mdx.mdx 同目录下的 autodocs 与 doc-blocks 章节。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考