Storybook 自定义文档页用不含 Meta 块的 MDX 文件按文件路径覆盖 Autodocs利用 Storybook 的文件系统索引机制你可以通过一个普通的*.mdx文件为组件编写更贴合业务的设计规范文档并让它在侧边栏中按物理路径自动定位、自动命名从而覆盖或补齐按tags自动生成的文档页。本文将给出可直接运行的.storybook/main配置与一个完整的Select.mdx示例并说明标题推断、路径归属和与autodocs标签交互时的注意事项。覆盖 Autodocs 的第三种姿势依赖文件系统而非 Meta 块Storybook 的 addon-docs 提供了一套基于 MDX 的文档方案对应指南见 docs/writing-docs/mdx.mdx。在已有的 Autodocs组件文档自动生成 之上为组件补充“人类手写”的文档时通常有两种主流做法在 MDX 中使用MetaDoc Block并通过title或ofprops 控制文档页的标题与归属示例见 docs/_snippets/storybook-auto-docs-baseline-example.md省略Meta块仅靠文件在磁盘上的物理位置决定文档出现在侧边栏的哪里。后者正是本文要展开的“Using the File System”场景源码文档位于 docs/writing-docs/mdx.mdx。它的最大优势是零元数据你不需要记忆Meta的 props、不需要导入 stories只要把 MDX 文件和目标组件放在合适的目录中Storybook 就会自动完成其余工作。当你准备为src/components/Select.tsx这类现有组件补充设计规范、使用指南或测试指引而不希望这些内容和组件实现耦合在同一份文档里时这种文件系统驱动的方式最为合适。前置配置让 Storybook 索引 MDX 与 stories在开始之前需要保证你的 Storybook 配置.storybook/main.js|ts|cjs既索引.stories.*文件也索引*.mdx文件并启用了 addon-docs。完整配置样板见 docs/_snippets/storybook-auto-docs-main-mdx-config.md这里给出最通用的 JS 版本export default { // 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], };其中stories数组中的两个 glob 缺一不可../src/**/*.mdx负责把自定义 MDX 文档纳入索引../src/**/*.stories.(js|jsx|mjs|ts|tsx)负责收集 CSF 故事文件。若使用 TypeScript可把配置写成带类型的StorybookConfig或使用各框架node入口暴露的defineMain帮助函数React/Vue/Angular 等对应写法均在上述样板的 Tab 中。主体示例无 Meta 块的 Select.mdx下面就是本主题对应的官方示例文件源片段见 docs/_snippets/storybook-auto-docs-custom-file.md。它存放于src/components/Select.mdx紧邻Select组件与它的 stories 文件# Select Select is a type of input that allows users to choose one or more options from a list of choices. The options are hidden by default and revealed when a user interacts with an element. It shows the currently selected option in its default collapsed state. ## Design implementation To help users get acquainted with the existing UI elements, it is recommended to use check the Figma file to see how the select input is implemented. ### When to use? In a select input where there are less than 3-4 items, consider using radio boxes, or radio inputs instead. ### How to use? To help users understand the options available in a select input, include a default option that is unselectable and acts as a label.请注意这份文档的构成没有任何Meta导入没有任何 Doc Block也没有引用任何 CSF 故事。它由以下纯 Markdown 结构组成一级标题# Select——同时充当页面主标题若干自然段落——交代组件的定位“允许用户从列表中选择一个或多个选项”与交互特征选项默认隐藏、选中项在折叠态可见## Design implementation二级章节——描述实现依据如对照 Figma 设计稿### When to use?/### How to use?三级小节——沉淀“何时使用”与“如何使用”的规范例如选项少于 3-4 个时建议改用 radio box、应提供一个不可选中且起标签作用的默认选项。这种骨架非常适合承载团队内部的设计规范Design guidelines与最佳实践类内容把“该不该用”“怎么用”沉淀为团队共识而非只罗列组件 API。MDX 支持标准 CommonMark 语法也可以用#/##/###组织多级目录。文件位置如何转化为侧边栏条目当 Storybook 加载这样一份省略Meta块的 MDX 文档后描述见 docs/writing-docs/mdx.mdx会使用与CSF 3.0 自动标题相同的启发式规则来推断文档的标题与位置可对照 docs/configure/user-interface/sidebar-and-urls.mdx 中关于 auto-title 的说明并在侧边栏中把它渲染为一个Docs条目。也就是说src/components/Select.mdx会被归属到与src/components/Select.stories.js|ts相同的分组层级成为该组件下的文档入口。把 MDX 文件放置在哪个目录就决定了文档在导航树中的分组与某组件 stories 同目录 → 文档挂到该组件分组下放在项目根级的src/GettingStarted.mdx之类的独立路径 → 文档成为项目级的独立文档页该用法的独立页面示例见 docs/_snippets/storybook-auto-docs-standalone-page.md。覆盖既有 Autodocs 页先处理 tags 再写文件“文件系统定位”还有一种常见诉求用自己的 MDX 覆盖某个组件本应由 Autodocs 自动生成的文档页。当同名路径下既有开启autodocs的 CSF又有这份 MDX 时后者会覆盖前者的自动生成文档。为避免冲突报错官方在 docs/writing-docs/mdx.mdx 中明确提示如果你覆盖的是通过tags配置启用的既有自动文档页建议移除对应的autodocstag以避免错误。Autodocs 本身是通过 tags 启用的机制见 docs/writing-docs/autodocs.mdx。因此若Select.stories.ts此前通过tags: [autodocs]生成了自动文档现在要改用手写 MDX应在 CSF 元数据中显式移除该 tagimport type { Meta } from storybook/your-framework; // e.g. react-vite、vue3-vite 等 import { Select } from ./Select; const meta { component: Select, // Disable auto-generated documentation for this component tags: [!autodocs], } satisfies Metatypeof Select; export default meta;更多框架与 CSF 写法的完整变体可参考 docs/_snippets/tags-autodocs-remove-component.md。这样既保留了 stories 用于在 Docs 与 Canvas 中展示又把说明性内容完全交给手写的Select.mdx职责划分干净且不会出现两套文档互相打架的情况。何时用 Meta 块、何时依赖文件路径同样是“自定义 MDX 文档”两种定位方式适合不同诉求取舍可参考 docs/writing-docs/mdx.mdx 的对照使用MetaDoc Block当文档需要“挂”到某个具体组件故事上Meta of{ButtonStories} /需要导入该 stories 文件的全部导出而不是组件本身或需要精确控制导航标题时Meta titleButton /、Meta of{...} nameInfo /。此时还可以组合Controls等 Doc Block 在文档内展示交互控件完整示例见 docs/_snippets/storybook-auto-docs-baseline-example.md。仅提供Meta但不带其他 props/块文档会被视为 “unattached” 的 documentation-only 页面在侧边栏中以不同形式呈现对比代码见 docs/_snippets/storybook-auto-docs-mdx-docs-docs-only-page.md。完全省略Meta块本文场景文档的位置、标题全部交由文件的物理路径与首行标题推断适合独立页面、测试指引、设计规范等无需强绑定故事的内容。你可以把这类文件当作组织文档结构的唯一依据改动文件位置即改动侧边栏结构无需维护任何映射关系。后续扩展与排查方向内容展示若需要把更丰富的 Markdown 内容如CHANGELOG.md直接嵌入 MDX 文档可借助 addon-docs 提供的MarkdownDoc Block 渲染导入内容。表格与脚注渲染当手写文档中使用了 GFM 扩展语法却渲染异常时可在配置中启用remark-gfm插件该插件默认未随 Storybook 提供需单独安装为开发依赖相关说明见 docs/writing-docs/mdx.mdx 的 Troubleshooting 章节。文档不生成如果 Storybook 未能为组件检测并渲染文档优先核对.storybook/main中stories配置是否覆盖了正确的.stories与.mdx路径。将这一整套机制与本仓库其他文档Autodocs、Doc Blocks 写作、文档发布配合使用就能从“组件自动文档”平滑演进到“自动 手写规范共存”的完整组件文档体系。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
