Storybook MDX 文档专用页Documentation-only Page完整实战指南用 Meta Doc Block 构建独立文档与组件文档导读本文聚焦 Storybook 中一种高频且易混淆的 MDX 文档用法仅包含MetaDoc Block 的文档专用页Documentation-only Page。你将学会通过Meta title...与Meta of{...}两种形态分别产出不挂接任何组件的纯文档页与挂接到具体组件的文档页理解二者在侧边栏中的渲染差异并结合仓库源码Meta 块实现、MDX 编写指南、Meta API 文档掌握其底层原理与最佳实践。什么是 Documentation-only Page在 MDX 文档编写指南 的Writing unattached documentation一节中官方给出了一个明确的定义场景假设你在为一个现有组件编写文档但只提供了MetaDoc Block且不附加任何其他 props 或 blocksStorybook 会将其视为unattached文档即documentation-only页面并在侧边栏中以不同的方式渲染。换句话说Documentation-only Page 是指一个 MDX 文件只声明了元信息Meta不挂接 CSF 故事文件、也不渲染任何 Doc Block从而在文档侧边栏中成为一个独立入口。它是 Storybook MDX 体系中纯文档形态的最小单元也是从组件文档走向项目级文档如设计规范、测试指南、贡献说明的起点。Documentation-only 与 Attached 文档的区别维度Documentation-onlyunattachedAttached 文档与故事文件的关系不关联任何 CSF 文件通过Meta of{...}关联 CSF 文件定位方式titleprop 或文件物理路径auto-titleofprop 指定故事文件侧边栏位置由title或文件路径决定的任意位置出现在组件故事列表之下可用 Doc Block受限无法使用需要 attached 上下文的块可使用Stories等 attached 模式的块典型用途设计规范、指南、项目级说明组件 API 文档、组件扩展文档Attached与Unattached的完整定义见 Meta Doc Block APIattached 文档条目显示在组件故事列表旁unattached 文档条目可通过title显示在侧边栏的任意位置。完整示例同一 MDX 文件中的两种形态关联文档docs/_snippets/storybook-auto-docs-mdx-docs-docs-only-page.md给出了一个同时演示两种形态的ExampleDocumentation.mdx示例其中包含三个渲染变体Common / Svelte CSF / CSF 3核心代码如下import { Meta } from storybook/addon-docs/blocks; import * as ExampleComponentStories from ./ExampleComponent.stories; {/* Documentation-only page */} Meta titleDocumentation / {/* Component documentation page */} Meta of{ExampleComponentStories} /import { Meta } from storybook/addon-docs/blocks; import * as ExampleComponentStories from ./ExampleComponent.stories.svelte; {/* Documentation-only page */} Meta titleDocumentation / {/* Component documentation page */} Meta of{ExampleComponentStories} /import { Meta } from storybook/addon-docs/blocks; import * as ExampleComponentStories from ./ExampleComponent.stories; {/* Documentation-only page */} Meta titleDocumentation / {/* Component documentation page */} Meta of{ExampleComponentStories} /逐行拆解导入Metaimport { Meta } from storybook/addon-docs/blocks;该语句必须位于文件顶部。关于其他可导入的 Doc Blocks如Canvas、Story可参考 MDX 导入示例。导入 CSF 故事文件import * as ExampleComponentStories from ./ExampleComponent.stories;。注意必须使用命名空间导入import * as因为Meta的ofprop 接收的是故事文件的完整导出集合。Documentation-only 形态Meta titleDocumentation /仅提供title将文档页放到侧边栏的Documentation节点下不关联任何组件。Component documentation 形态Meta of{ExampleComponentStories} /通过of引用故事文件将 MDX 挂接到组件的故事列表之下。Svelte 变体的差异Svelte 项目在导入故事文件时需指向.stories.svelte文件如./ExampleComponent.stories.svelte。而标记为tabTitleCSF 3的变体与 Common 变体内容一致仅用于在文档站点中以不同标签页呈现实际写法没有差异。Meta Doc Block 的完整配置要真正用好 documentation-only 页面必须掌握Meta的三个核心 prop详见 Meta API 文档of类型CSF 文件的导出集合ModuleExports作用将 MDX 文件挂接到指定 CSF 文件及其故事上关键约束必须传入import * as得到的完整导出集合不能传默认导出component 本身。Meta的 TypeScript 类型定义Meta.tsx为BaseAnnotations { of?: ModuleExports; title?: string }其中ModuleExports即模块导出集合类型印证了这一约束附带效果挂接后可在 MDX 中使用需要 attached 上下文的 Doc Block如Stories同时文档条目默认命名为docs.defaultName默认为Docs可通过nameprop 覆盖title类型string作用为 unattached MDX 文件设置文档条目标题与侧边栏位置典型用法Meta titlepath/to/Introduction /可以按/划分层级将文档放到侧边栏任意位置此即 documentation-only 页面的核心定位方式name类型string作用为 attached 文档条目设置名称。可以为同一组件挂接多个 MDX 文件并分别命名例如Meta of{ComponentStories} nameSpecial Docs /官方文档特别提示向Meta提供ofprop 时务必引用故事文件的完整导出集合而不是组件本身否则会导致生成的文档出现渲染问题。两种页面形态的底层原理源码层面Meta 块如何工作Meta块的实现位于 code/addons/docs/src/blocks/blocks/Meta.tsx其源码注释明确写道This component is used to declare component metadata in docs and gets transformed into a default export underneath the hood.该组件用于在文档中声明组件元信息底层会被转换为默认导出。从源码可以观察到关键逻辑当传入of时调用context.referenceMeta(of, true)建立文档与故事文件的关联Meta.tsx第 17-19 行随后尝试通过context.storyById()获取主故事并渲染Anchor若获取失败catch 分支直接返回null注释说明It is possible to useMetain an unattached MDX file——这正是 documentation-only 页面在底层得到支持的依据Meta.tsx第 21-27 行。这也解释了为什么Meta块不渲染任何可见内容它本质上是文档元信息的声明机制可见内容由文档正文中的 Markdown 与其他 Doc Blocks 提供。渲染差异attached 与 unattachedattachedMDX 文件出现在对应组件的故事列表之下默认名为Docs可配置docs.defaultName或namepropunattacheddocumentation-only不关联故事文件通过titleprop 或文件物理路径auto-title决定侧边栏位置通常渲染为独立的Docs条目。侧边栏定位的两条路径Documentation-only 页面在侧边栏的定位有两条路径官方文档均有阐述titleprop 显式指定如Meta titleDocumentation /将节点放到指定层级。文件物理路径推断auto-title省略Meta或仅提供of/title之外的形态时Storybook 使用与 CSF 3.0 auto-titles 相同的启发式规则依据 MDX 文件的物理位置推断标题与位置并渲染为Docs条目。实战应用纯文档页与项目级文档Documentation-only 页面的典型使用场景是编写不依赖任何具体组件的独立文档。官方 MDX 指南中的独立页面示例演示了一个src/GettingStarted.mdx其中使用标准 Markdown 结构标题、目录、小节编写设计资源 / 开发资源类的内容# 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. ---该页面未提供MetaStorybook 会依据文件物理位置推断其在侧边栏的位置并将其渲染为Docs条目。这种基于文件系统的方式在 MDX 指南中有专门论述对于独立页面、组件测试指南等场景可以安全地省略Meta块Storybook 会用文件物理位置来决定侧边栏归属并覆盖同位置任何已有的自动生成文档。注意事项若你正在用tags配置属性覆盖某个已有的自动生成文档页面官方建议移除对应标签以避免冲突详见 Autodocs 配置Documentation-onlyunattachedMDX 页面无法自定义目录TOC由于当前实现不支持为其定义 parametersTOC 始终回退到全局默认配置该限制在 Autodocs 排障章节中明确说明。相关能力延伸自定义文档与自动文档的协作Autodocs 通过tags: [autodocs]自动生成组件文档配置方式MDX 文档页可与之并存或覆盖单个组件文档覆盖若只需覆盖单个组件的文档页官方推荐直接创建 MDX 文件并通过Meta of{} /引用自定义模板若需要在非 React 项目中使用 MDX 生成文档模板可给Meta提供isTemplatepropMDX 模板用法并在.storybook/preview或故事文件中导入使用MDX 与 CSF 的分工CSF 适合精炼地定义故事并提供 TypeScript 类型安全与自动补全MDX 适合编写结构化文档并与交互式 JSX 元素组合MDX 指南。常见问题与排障MDX 文档页没有出现在侧边栏检查.storybook/main.js|ts中stories配置是否正确包含 MDX 文件路径如../src/**/*.mdx以及addons中是否注册了storybook/addon-docs。文档页位置不符合预期需要固定位置使用Meta titlepath/to/Node /显式指定层级希望跟随文件位置省略Meta或保持仅of的 attached 形态让 auto-title 按物理路径推断。无法在文档页中使用某个 Doc Block某些 Doc Block如Stories需要 attached 上下文。若文档页是 unattached 形态应通过Meta of{...} /挂接故事文件后再使用。总结Documentation-only Page 是 Storybook MDX 文档体系中无组件依赖的纯文档最小形态其本质是只含MetaDoc Block、不挂接 CSF 文件的 MDX 文档。通过Meta title...可将其定位到侧边栏任意位置通过Meta of{...}则可将其挂接到具体组件的故事列表。其底层实现Meta.tsx在无 attached 上下文时返回null从源码层面确认了这种形态的合法性。无论是编写设计规范、测试指南还是项目级入门文档理解并熟练运用 documentation-only 页面都是掌握 Storybook 文档体系的关键一步。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考