Storybook 启用 MDX 自定义文档.storybook/main 配置逐字段解析与底层原理【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookMDXMarkdown JSX为 Storybook 提供了一边写结构化文档、一边嵌入可交互 Story 与 Doc Blocks的能力。本文聚焦于启用这条能力链路的第一环——.storybook/main.js|ts|cjs中的stories与addons配置逐字段拆解storybook/addon-docs的注册方式、MDX 文件与 CSF 故事文件的 glob 编排并结合当前仓库源码code/addons/docs、code/frameworks说明 MDX 文档页从被扫描到到被编译渲染的底层管线。读完本文你将能独立在任意新项目中一次性配好 MDX 文档基础设施并理解为什么这样写能生效。这个配置解决什么问题Storybook 的常规做法是用 Component Story FormatCSF 编写组件 Story再由 Autodocs 自动生成组件文档。但如果你需要在 Story 之外再编写纯定制化文档——例如组件用法指南、设计规范、最佳实践、验收清单等——就需要让 Storybook 额外识别并渲染.mdx文件。为此官方文档docs/writing-docs/mdx.mdx#L84-L90给出的第一步就是更新 Storybook 配置文件在stories数组中同时加入 MDX 文件与 Story 文件的 glob在addons中显式注册storybook/addon-docs。也就是说本文档docs/_snippets/storybook-auto-docs-main-mdx-config.md是官方Setup custom documentation搭建自定义文档工作流的入口配置全仓库docs/_snippets/中所有storybook-auto-docs-*.md示例Meta 块用法、standalone 页面、多组件文档等都依赖这则配置先就位。stories字段让 MDX 与 CSF 并列进入索引配置中最关键的是把两类文件都纳入stories扫描范围stories: [ // 你编写的 MDX 文档与你的 stories 放在一起 ../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx), ],逐段解读glob 表达式含义../src/**/*.mdx让 Storybook 的索引器扫描src下所有.mdx文档并将其登记为独立的Docs条目../src/**/*.stories.(js\|jsx\|mjs\|ts\|tsx)沿用默认的 CSF 故事文件约定覆盖 5 种主流 JS/TS 后缀两点实操注意事项路径基准是.storybook/目录。配置放在.storybook/main.js|ts|cjs中因此../src/...指的是从配置目录上溯一级到项目src。如果你的文档放在其他目录例如docs/需要相应调整 glob官方 Troubleshooting 中专门强调过文档无法渲染时优先检查stories是否给出正确的文件路径见 docs/writing-docs/mdx.mdx#L204-L206。不要漏掉两条 glob 中任意一条。只保留.stories.*会扫不到 MDX只保留*.mdx则组件 Story 全部丢失Doc Blocks 也就无故事可引用了。framework与addons字段framework: storybook/your-framework, addons: [storybook/addon-docs],framework是占位符必须替换为你实际使用的框架包例如storybook/react-vite、storybook/nextjs、storybook/vue3-vite、storybook/angular等即代码注释中your-framework的语义。addons: [storybook/addon-docs]是本配置的引擎。从源码可以确认注册storybook/addon-docs后其 preset 会向构建链注入 MDX 编译能力、Doc Blocks 所需的react/mdx-js/react别名解析并将 docs 相关的默认预设接入 Storybook。例如其 webpack preset 中注册了针对普通.mdx的 loader 规则而 Vite 场景则由 mdx-plugin 处理详见下文源码视角一节。三种写法变体CSF 3 与 CSF Next官方把这段配置按配置风格 × 语言 × 框架拆成了多个代码块本质内容一致写法入口不同。以下全部继承自原文档。变体一CSF 3 JavaScript.storybook/main.jsexport 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], };变体二CSF 3 TypeScript.storybook/main.ts// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. 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;TS 变体额外引入了StorybookConfig类型用类型系统约束stories、addons、framework等字段的拼写减少配置手误。变体三CSF Next 实验性——defineMain在原文档中标注为CSF Next 的变体不再手工export default一个对象而是从框架的 Node 入口导入defineMain工厂函数。以 React 为例.storybook/main.ts// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { defineMain } from storybook/your-framework/node; export default defineMain({ // Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) 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], });JavaScript 版本与 TS 版本完全同构仅去掉类型导入// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) import { 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], });defineMain的源码本质defineMain并非做了什么魔法而是一个恒等函数 类型约束的封装。原文档中 Angular 与 Web Components 变体的导入路径分别是storybook/angular/node与storybook/web-components-vite/node这一点在仓库源码中可以得到一一印证——每个框架的 Node 入口文件都导出了同样的defineMainexport function defineMain(config: StorybookConfig) { return config; }例如 react-vite 的 node 入口、nextjs 的 node 入口、angular 的 node 入口、web-components-vite 的 node 入口 结构完全一致。因此你可以据此推断规则CSF Next 风格下defineMain统一从framework-package/node子路径导入。常用映射如下均能在仓库code/frameworks/*/src/node/index.ts中核实框架framework字段值defineMain导入路径React Vitestorybook/react-vitestorybook/react-vite/nodeNext.jsstorybook/nextjsstorybook/nextjs/nodeVue 3 Vitestorybook/vue3-vitestorybook/vue3-vite/nodeAngularWebpack5storybook/angularstorybook/angular/nodeWeb Components Vitestorybook/web-components-vitestorybook/web-components-vite/nodeSvelte Vitestorybook/svelte-vitestorybook/svelte-vite/node需要留意的是CSF Next 属于实验性写法源码片段与文档中的 标记即为此意生产项目若不希望依赖实验 API使用前面两种 CSF 3 写法即可达到完全相同的效果。配置就位后MDX 文档如何进入侧边栏完成 main 配置并创建.mdx文件后Storybook 会根据文件内容与物理位置决定文档如何呈现这部分完整流程记录在 docs/writing-docs/mdx.mdx 的 Setup custom documentation 一节提供Meta of{...} /时文档会被挂到对应组件 Story 旁边。of必须引用故事文件的完整导出集合而非组件本身否则文档渲染可能出问题可用name覆盖侧边栏标题、用title将节点放到任意导航层级。只写一个空Meta /或干脆省略时Storybook 会将其视为 unattached 文档即 documentation-only 页面在侧边栏中以独立Docs条目渲染。不用 Meta 块时Storybook 依据文件物理位置推断标题与归属规则与 CSF 3.0 的 auto-title 启发式一致见 sidebar-and-urls 文档。此时若想覆盖某组件已有的 Autodocs 自动生成页官方建议同时移除通过tags开启的自动文档避免冲突。单页文档如项目 onboarding 指南、多组件合页、嵌入CHANGELOG.md等 Markdown 文件都可在同一套 main 配置下直接编写配合 Doc Blocks 与MarkdownDoc Block 实现。简言之本配置是这一切的前提——没有把*.mdx放进stories、没有注册addon-docs上面所有写法都不会被索引与渲染。源码视角addon-docs 如何消化你加的.mdx为了说明addons: [storybook/addon-docs]这条配置的真实价值可以直接观察其 preset 源码webpack 管线为普通.mdx文件注册 loader 规则将其交给storybook/addon-docs/mdx-loader编译见 preset.ts#L122-L132同时对形如*.stories.mdx/*.story.mdx的文件做了排除暗示这类文件走的是与纯文档不同的 CSF 索引管线。Vite 管线通过viteFinal将 mdx-plugin 插入插件链并保证它先于任何 React 相关插件执行见 preset.ts#L196-L199。依赖别名与版本一致性preset 会把react、react-dom、mdx-js/react统一别名到项目已装版本或 addon-docs 自带的兜底版本避免多个实例导致文档页渲染失败见 preset.ts#L23-L36。MDX 3构建时会输出Addon-docs: using MDX3表示 MDX 编译基于 MDX 3 生态并默认注入rehype-slug、rehype-external-links等 rehype 插件。React-only 的渲染层官方文档明确 MDX 运行层仅支持 React——MDX 文档本身以 React 渲染但其中的 Story 仍会在你选定的框架运行时React、Vue、Angular、Svelte、Web Components……中渲染见 docs/writing-docs/mdx.mdx#L80-L82。主 Story 选择逻辑MDX 文档页与 Autodocs 在挑选 primary story 时规则不同——MDX 页会选中第一个 Story无论是否带autodocs标签参见 usePrimaryStory.ts。因此把../src/**/*.mdx加进stories解决的是入口索引问题而addon-docs解决的是编译、别名与 Doc Blocks 运行时问题两者缺一不可。常见坑位与检查清单结合官方文档与上述源码落地时可按下述清单自查占位符是否替换storybook/your-framework与storybook/your-framework/node只是模板占位未替换会在启动时报包不存在。glob 基准目录stories中的路径是相对于.storybook/所在位置的../src默认对应项目srcMDX 放在别处时要同步改 glob。两类文件都要扫到*.mdx与*.stories.(js|jsx|mjs|ts|tsx)缺一不可前者负责文档、后者负责故事与组件元数据。版本一致性如遇 React 版本异常可能需要在项目内显式安装 react或重建node_modules让 addon-docs 别名解析到正确版本。与 Autodocs 的冲突若要自定义 MDX 覆盖自动生成的文档页建议移除相应tags自动文档开关避免同节点重复渲染报错。按以上配置完成后npm run storybook即可在侧边栏看到 MDX 生成的Docs条目并可用Meta、Canvas、Controls、Markdown等 Doc Blocks 组合出项目级或组件级的自定义文档体系。更完整的编写示例可继续阅读 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），仅供参考