Storybook addon-docs 选项配置详解通过 csfPluginOptions 与 mdxPluginOptions 定制文档构建行为【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文聚焦 Storybook 官方 docs 插件storybook/addon-docs在注册阶段暴露的配置入口csfPluginOptions与mdxPluginOptions。它们分别控制CSF 源码增强source enrichment与MDX 文档编译两大内部管线直接影响 Autodocs 自动生成的文档质量与 MDX 页面的渲染能力。读完本文你将能够在.storybook/main.js|ts中精准配置 addon-docs例如用null关闭 CSF 插件、为 MDX 编译器追加remark-gfm以修复表格与脚注渲染并理解这些选项在 Storybook 源码中的真实作用路径。一、什么是 addon-docs 的 Addon options在 docs/writing-docs/autodocs.mdx 的 Addon options 一节中官方文档说明了 docs 插件的扩展点addon-docs 接受若干选项用于定制文档页Documentation page的行为。这些选项不属于任何单个 story 或 MDX 文件而是在注册 addon 时作为整体注入 Storybook 构建管线位于 Storybook UI 配置文件.storybook/main.js|ts中Option作用csfPluginOptions为 Storybook 的 CSF 插件提供附加配置设为null可禁用该插件。mdxPluginOptions提供 MDX 文档的附加配置与插件配置对应编译选项。其配套的代码示例被整理为独立片段文件 docs/_snippets/addon-docs-options.md覆盖 CSF 3普通对象导出与 CSF NextdefineMain两代配置语法以及react、vue3-vite、angular、web-components等多个框架入口。二、在 .storybook/main 中注入 options 的标准写法要传入选项不能再用字符串简写addons: [storybook/addon-docs]而必须把 addon 写成对象形式{ name: storybook/addon-docs, options: { ... } }。下面是 CSF 3 时代的主配置写法TypeScript// 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 { framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], addons: [ { name: storybook/addon-docs, options: { csfPluginOptions: null, mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [], }, }, }, }, ], }; export default config;对应的 JavaScript 版本export default { // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], addons: [ { name: storybook/addon-docs, options: { csfPluginOptions: null, mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [], }, }, }, }, ], };CSF Next 时代defineMain 写法若项目使用实验性的 CSF Next 配置语法则需要从框架对应的node子路径导入defineMain把整个配置对象包起来。以 React 系框架为例// 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: [ { name: storybook/addon-docs, options: { csfPluginOptions: null, mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [], }, }, }, }, ], });该模式对 Angular、Vue 3、Web Components 同样适用只需换成各自的入口与包名Angularimport { defineMain } from storybook/angular/nodeframework: storybook/angularVue 3import { defineMain } from storybook/vue3-vite/nodeframework: storybook/vue3-viteWeb Componentsimport { defineMain } from storybook/web-components-vite/nodeframework: storybook/web-components-viteoptions 内部结构与外层写法在 CSF 3 与 CSF Next 间完全一致详见 docs/_snippets/addon-docs-options.md 中逐框架、逐语言重复展示的变体。三、csfPluginOptions控制 CSF 源码增强插件csfPluginOptions面向的是 addon-docs 内置的 CSF 插件CSF plugin该插件的作用是增强enrich项目里的.stories文件使其能被 Docs 更好地消费例如为 Source 展示生成更准确的可执行代码、把参数元数据与文档块关联起来。null 语义与默认行为当csfPluginOptions未配置时插件默认启用——在 code/addons/docs/src/preset.ts 中通过解构默认值const { csfPluginOptions {}, mdxPluginOptions {} } options兜底为空对象truthy因此插件照常被注入。当csfPluginOptions显式设为null时addon-docs 将不再对 CSF 文件做源码增强。同样在 preset.ts 的 Webpack 分支中可以看到...(csfPluginOptions ? [csfPluginWebpack({ ...csfPluginOptions, enrichCsf })] : [])即只有该选项为真值时才把插件加入构建Vite 分支viteFinal的if (csfPluginOptions)判断逻辑与此一致见 code/addons/docs/src/preset.ts。若你需要在禁用增强的同时保留 Docs 页面的其他能力把该项设为null是最直接的做法这与 code/addons/docs/README.md 中对预设选项的描述吻合。底层接线从类型定义看DocsOptions将该项声明为csfPluginOptions?: EnrichCsfOptions | null其中EnrichCsfOptions来自storybook/internal/csf-toolscode/addons/docs/src/preset.ts。CSF 插件本身是一个基于unplugin实现的跨构建工具插件code/addons/docs/src/csf-plugin/index.ts同时提供vite通过plugin-csf的 transform 钩子对 story 文件做转换webpack/rspack以enforce: post追加webpack-loader规则命中 story 正则转换核心复用storybook/internal/csf-tools的loadCsf、enrichCsf、formatCsf流程code/addons/docs/src/csf-plugin/webpack-loader.ts。此外可以注意到插件启用时 preset 会把来自experimental_enrichCsf特性预设的开关一并注入preset.ts 中csfPluginWebpack({ ...csfPluginOptions, enrichCsf })说明CSF 增强本身已接入 Storybook 的特性开关体系——实际是否需要该特性由你的 Storybook 版本与features配置决定。四、mdxPluginOptionsMDX 文档编译配置mdxPluginOptions用于定制 addon-docs 对.mdx文件的编译。其类型定义非常简短code/addons/docs/src/compiler/types.tsimport type { compile as mdxCompile } from mdx-js/mdx; export type MdxCompileOptions Parameterstypeof mdxCompile[1]; export interface CompileOptions { mdxCompileOptions?: MdxCompileOptions; }也就是说mdxPluginOptions本质上就是一层薄封装最终透传给mdx-js/mdx的compile函数的第二参数。因此凡是 MDX 编译器支持的选项都可放在mdxCompileOptions内最常见的就是remarkPluginsmarkdown 解析阶段的 remark 插件数组本文示例中的remarkPlugins: []即为空数组占位rehypePluginsHTML 生成阶段的 rehype 插件数组其余由mdx-js/mdx支持的编译项。默认注入与合并规则虽然用户可以直接书写mdxCompileOptions但 Storybook 会对其做强制合并而不是原样透传。从 code/addons/docs/src/preset.ts 的mdxLoaderOptions组装逻辑可以看到三个关键事实providerImportSource 被强制指向addon-docs 自带的mdx-react-shim用户写入的mdxCompileOptions通过展开运算符覆盖在其后rehypePlugins 采用先用户后默认的追加策略rehypePlugins: [...(用户的 rehypePlugins ?? []), rehypeSlug, rehypeExternalLinks]即无论用户是否配置构建时都会补上rehype-slug为标题生成锚点 id与rehype-external-links为外链补充属性合并完成的选项最终交给storybook/addon-docs/mdx-loader使用。Vite 侧逻辑几乎一致viteFinal中注册mdxPlugin(options)该插件会先从 presets 拉取options得到mdxPluginOptions再按相同规则合并默认值后调用内部compile见 code/addons/docs/src/mdx-plugin.ts。因此无论你使用 Webpack 还是 Vite 作为 buildermdxPluginOptions的写法与效果是统一的。MDX 3 与文件命中范围preset.ts 中加载器规则为test: /\.mdx$/并排除(stories|story)\.mdx文件即普通的.mdx文档走 addon-docs 的完整编译管线同时源码中会记录Addon-docs: using MDX3的日志说明当前实现基于 MDX 3。这意味着你写入的 remark/rehype 插件需要与项目锁定的 MDX 版本兼容。五、实战用 remark-gfm 修复表格与脚注渲染mdxPluginOptions最典型的真实用例是解决MDX 文档里的 Markdown 表格渲染不正确问题。在 docs/writing-docs/mdx.mdx 的排障章节中官方明确指出Storybook 当前使用的 MDX 版本默认不含 GitHub Flavored MarkdownGFM能力若要渲染表格、删除线、任务列表等 GFM 扩展语法需要在.storybook/main.js|ts中启用remark-gfm插件。其配套片段文件是 docs/_snippets/storybook-main-config-remark-options.md核心写法如下import remarkGfm from remark-gfm; export default { // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], addons: [ // Other addons go here { name: storybook/addon-docs, options: { mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [remarkGfm], }, }, }, }, ], };需要注意的实操要点remark-gfm需要单独安装它并不随 Storybook 默认分发文档特别提醒必须以开发依赖devDependency形式通过你的包管理器单独安装后才能import remarkGfm。该项配置只影响文档的编译结果不依赖任何 story 元数据remarkPlugins数组可以按需追加多个插件Storybook 会原样保留并交给 MDX 编译器执行remarkPlugins: []即空插件集合的等价写法。六、变更生效与验证方式addon-docs 的 options 属于构建期配置修改main.js|ts后需要重启 Storybookstorybook dev才会重新走一遍 addon 注册与 loader/插件组装流程。验证是否生效可以从三个层面观察文档渲染结果启用remark-gfm后Autodocs 或 MDX 页面里的 GFM 表格、脚注应能正确排版Autodocs 相关说明见 docs/writing-docs/autodocs.mdx源码表现将csfPluginOptions从默认改为null前后对比故事源码/文档展示差异可感知 CSF 增强开关的影响构建日志启动时出现Addon-docs: using MDX3提示说明 MDX 编译管线已进入 MDX 3 路径该日志输出于 code/addons/docs/src/preset.ts。相关参考选项完整示例片段docs/_snippets/addon-docs-options.mdGFM 渲染修复示例docs/_snippets/storybook-main-config-remark-options.mdAutodocs 中 Addon options 文档章节docs/writing-docs/autodocs.mdxMDX 文档与表格渲染排障docs/writing-docs/mdx.mdxWebpack/Vite preset 接线实现code/addons/docs/src/preset.ts、Vite MDX 插件 code/addons/docs/src/mdx-plugin.ts、编译选项类型 code/addons/docs/src/compiler/types.tsCSF 插件的 unplugin 实现code/addons/docs/src/csf-plugin/index.tsaddon-docs 自述预设选项总览code/addons/docs/README.md【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Storybook addon-docs 选项配置详解通过 csfPluginOptions 与 mdxPluginOptions 定制文档构建行为【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文聚焦 Storybook 官方 docs 插件storybook/addon-docs在注册阶段暴露的配置入口csfPluginOptions与mdxPluginOptions。它们分别控制CSF 源码增强source enrichment与MDX 文档编译两大内部管线直接影响 Autodocs 自动生成的文档质量与 MDX 页面的渲染能力。读完本文你将能够在.storybook/main.js|ts中精准配置 addon-docs例如用null关闭 CSF 插件、为 MDX 编译器追加remark-gfm以修复表格与脚注渲染并理解这些选项在 Storybook 源码中的真实作用路径。一、什么是 addon-docs 的 Addon options在 docs/writing-docs/autodocs.mdx 的 Addon options 一节中官方文档说明了 docs 插件的扩展点addon-docs 接受若干选项用于定制文档页Documentation page的行为。这些选项不属于任何单个 story 或 MDX 文件而是在注册 addon 时作为整体注入 Storybook 构建管线位于 Storybook UI 配置文件.storybook/main.js|ts中Option作用csfPluginOptions为 Storybook 的 CSF 插件提供附加配置设为null可禁用该插件。mdxPluginOptions提供 MDX 文档的附加配置与插件配置对应编译选项。其配套的代码示例被整理为独立片段文件 docs/_snippets/addon-docs-options.md覆盖 CSF 3普通对象导出与 CSF NextdefineMain两代配置语法以及react、vue3-vite、angular、web-components等多个框架入口。二、在 .storybook/main 中注入 options 的标准写法要传入选项不能再用字符串简写addons: [storybook/addon-docs]而必须把 addon 写成对象形式{ name: storybook/addon-docs, options: { ... } }。下面是 CSF 3 时代的主配置写法TypeScript// 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 { framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], addons: [ { name: storybook/addon-docs, options: { csfPluginOptions: null, mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [], }, }, }, }, ], }; export default config;对应的 JavaScript 版本export default { // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], addons: [ { name: storybook/addon-docs, options: { csfPluginOptions: null, mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [], }, }, }, }, ], };CSF Next 时代defineMain 写法若项目使用实验性的 CSF Next 配置语法则需要从框架对应的node子路径导入defineMain把整个配置对象包起来。以 React 系框架为例// 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: [ { name: storybook/addon-docs, options: { csfPluginOptions: null, mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [], }, }, }, }, ], });该模式对 Angular、Vue 3、Web Components 同样适用只需换成各自的入口与包名Angularimport { defineMain } from storybook/angular/nodeframework: storybook/angularVue 3import { defineMain } from storybook/vue3-vite/nodeframework: storybook/vue3-viteWeb Componentsimport { defineMain } from storybook/web-components-vite/nodeframework: storybook/web-components-viteoptions 内部结构与外层写法在 CSF 3 与 CSF Next 间完全一致详见 docs/_snippets/addon-docs-options.md 中逐框架、逐语言重复展示的变体。三、csfPluginOptions控制 CSF 源码增强插件csfPluginOptions面向的是 addon-docs 内置的 CSF 插件CSF plugin该插件的作用是增强enrich项目里的.stories文件使其能被 Docs 更好地消费例如为 Source 展示生成更准确的可执行代码、把参数元数据与文档块关联起来。null 语义与默认行为当csfPluginOptions未配置时插件默认启用——在 code/addons/docs/src/preset.ts 中通过解构默认值const { csfPluginOptions {}, mdxPluginOptions {} } options兜底为空对象truthy因此插件照常被注入。当csfPluginOptions显式设为null时addon-docs 将不再对 CSF 文件做源码增强。同样在 preset.ts 的 Webpack 分支中可以看到...(csfPluginOptions ? [csfPluginWebpack({ ...csfPluginOptions, enrichCsf })] : [])即只有该选项为真值时才把插件加入构建Vite 分支viteFinal的if (csfPluginOptions)判断逻辑与此一致见 code/addons/docs/src/preset.ts。若你需要在禁用增强的同时保留 Docs 页面的其他能力把该项设为null是最直接的做法这与 code/addons/docs/README.md 中对预设选项的描述吻合。底层接线从类型定义看DocsOptions将该项声明为csfPluginOptions?: EnrichCsfOptions | null其中EnrichCsfOptions来自storybook/internal/csf-toolscode/addons/docs/src/preset.ts。CSF 插件本身是一个基于unplugin实现的跨构建工具插件code/addons/docs/src/csf-plugin/index.ts同时提供vite通过plugin-csf的 transform 钩子对 story 文件做转换webpack/rspack以enforce: post追加webpack-loader规则命中 story 正则转换核心复用storybook/internal/csf-tools的loadCsf、enrichCsf、formatCsf流程code/addons/docs/src/csf-plugin/webpack-loader.ts。此外可以注意到插件启用时 preset 会把来自experimental_enrichCsf特性预设的开关一并注入preset.ts 中csfPluginWebpack({ ...csfPluginOptions, enrichCsf })说明CSF 增强本身已接入 Storybook 的特性开关体系——实际是否需要该特性由你的 Storybook 版本与features配置决定。四、mdxPluginOptionsMDX 文档编译配置mdxPluginOptions用于定制 addon-docs 对.mdx文件的编译。其类型定义非常简短code/addons/docs/src/compiler/types.tsimport type { compile as mdxCompile } from mdx-js/mdx; export type MdxCompileOptions Parameterstypeof mdxCompile[1]; export interface CompileOptions { mdxCompileOptions?: MdxCompileOptions; }也就是说mdxPluginOptions本质上就是一层薄封装最终透传给mdx-js/mdx的compile函数的第二参数。因此凡是 MDX 编译器支持的选项都可放在mdxCompileOptions内最常见的就是remarkPluginsmarkdown 解析阶段的 remark 插件数组本文示例中的remarkPlugins: []即为空数组占位rehypePluginsHTML 生成阶段的 rehype 插件数组其余由mdx-js/mdx支持的编译项。默认注入与合并规则虽然用户可以直接书写mdxCompileOptions但 Storybook 会对其做强制合并而不是原样透传。从 code/addons/docs/src/preset.ts 的mdxLoaderOptions组装逻辑可以看到三个关键事实providerImportSource 被强制指向addon-docs 自带的mdx-react-shim用户写入的mdxCompileOptions通过展开运算符覆盖在其后rehypePlugins 采用先用户后默认的追加策略rehypePlugins: [...(用户的 rehypePlugins ?? []), rehypeSlug, rehypeExternalLinks]即无论用户是否配置构建时都会补上rehype-slug为标题生成锚点 id与rehype-external-links为外链补充属性合并完成的选项最终交给storybook/addon-docs/mdx-loader使用。Vite 侧逻辑几乎一致viteFinal中注册mdxPlugin(options)该插件会先从 presets 拉取options得到mdxPluginOptions再按相同规则合并默认值后调用内部compile见 code/addons/docs/src/mdx-plugin.ts。因此无论你使用 Webpack 还是 Vite 作为 buildermdxPluginOptions的写法与效果是统一的。MDX 3 与文件命中范围preset.ts 中加载器规则为test: /\.mdx$/并排除(stories|story)\.mdx文件即普通的.mdx文档走 addon-docs 的完整编译管线同时源码中会记录Addon-docs: using MDX3的日志说明当前实现基于 MDX 3。这意味着你写入的 remark/rehype 插件需要与项目锁定的 MDX 版本兼容。五、实战用 remark-gfm 修复表格与脚注渲染mdxPluginOptions最典型的真实用例是解决MDX 文档里的 Markdown 表格渲染不正确问题。在 docs/writing-docs/mdx.mdx 的排障章节中官方明确指出Storybook 当前使用的 MDX 版本默认不含 GitHub Flavored MarkdownGFM能力若要渲染表格、删除线、任务列表等 GFM 扩展语法需要在.storybook/main.js|ts中启用remark-gfm插件。其配套片段文件是 docs/_snippets/storybook-main-config-remark-options.md核心写法如下import remarkGfm from remark-gfm; export default { // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. framework: storybook/your-framework, stories: [../src/**/*.mdx, ../src/**/*.stories.(js|jsx|mjs|ts|tsx)], addons: [ // Other addons go here { name: storybook/addon-docs, options: { mdxPluginOptions: { mdxCompileOptions: { remarkPlugins: [remarkGfm], }, }, }, }, ], };需要注意的实操要点remark-gfm需要单独安装它并不随 Storybook 默认分发文档特别提醒必须以开发依赖devDependency形式通过你的包管理器单独安装后才能import remarkGfm。该项配置只影响文档的编译结果不依赖任何 story 元数据remarkPlugins数组可以按需追加多个插件Storybook 会原样保留并交给 MDX 编译器执行remarkPlugins: []即空插件集合的等价写法。六、变更生效与验证方式addon-docs 的 options 属于构建期配置修改main.js|ts后需要重启 Storybookstorybook dev才会重新走一遍 addon 注册与 loader/插件组装流程。验证是否生效可以从三个层面观察文档渲染结果启用remark-gfm后Autodocs 或 MDX 页面里的 GFM 表格、脚注应能正确排版Autodocs 相关说明见 docs/writing-docs/autodocs.mdx源码表现将csfPluginOptions从默认改为null前后对比故事源码/文档展示差异可感知 CSF 增强开关的影响构建日志启动时出现Addon-docs: using MDX3提示说明 MDX 编译管线已进入 MDX 3 路径该日志输出于 code/addons/docs/src/preset.ts。相关参考选项完整示例片段docs/_snippets/addon-docs-options.mdGFM 渲染修复示例docs/_snippets/storybook-main-config-remark-options.mdAutodocs 中 Addon options 文档章节docs/writing-docs/autodocs.mdxMDX 文档与表格渲染排障docs/writing-docs/mdx.mdxWebpack/Vite preset 接线实现code/addons/docs/src/preset.ts、Vite MDX 插件 code/addons/docs/src/mdx-plugin.ts、编译选项类型 code/addons/docs/src/compiler/types.tsCSF 插件的 unplugin 实现code/addons/docs/src/csf-plugin/index.tsaddon-docs 自述预设选项总览code/addons/docs/README.md【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
