Storybook 插件：JSDoc 到 MDX

描述

此 Storybook 插件会自动扫描项目中的 JavaScript 或 TypeScript 文件，提取 JSDoc 注释，并生成全面的 MDX 文档。它与 Storybook 无缝集成，通过直接从源代码中提取的详细见解和示例来增强组件文档。

例如，以下 TypeScript 代码

/**
 * Interface representing a person with an optional age property.
 */
interface Person {
    name: string;
    age?: number;
}

/**
 * Function that prints a person's name and optionally age if provided.
 * @param {Person} person The person.
 */
function printPerson(person: Person): void {
    console.log(`Name: ${person.name}`);
    if (person.age !== undefined) {
        console.log(`Age: ${person.age}`);
    }
}

将在 Storybook 中显示如下

目录

1. 要求
2. 安装
3. 使用方法
4. 配置
5. 特性
6. 未来计划和开发
7. 贡献
8. 许可证
9. 致谢

要求

• Storybook@>=7.0.0 (已确认兼容 Storybook@8.x，包括最新的 8.6.x 版本)
• React、Vue、Angular 或 Storybook 支持的任何其他框架

此插件是框架无关的，应适用于 Storybook 支持的任何 UI 框架。如果遇到任何兼容性问题，请在 GitHub 上提出 issue。

安装

要安装此插件，请在终端中运行以下命令

npm install storybook-addon-jsdoc-to-mdx --save-dev

或者如果您更喜欢使用 Yarn

yarn add storybook-addon-jsdoc-to-mdx --dev

使用方法

安装后，将此插件添加到您的 .storybook/main.js 配置文件中

Storybook 7.x

module.exports = {
  addons: [
    // other addons
    {
      name: 'storybook-addon-jsdoc-to-mdx',
      options: {
        folderPaths: ['./src/'], // paths to folders with JS/TS code
        extensions: ['ts', 'js'] // file extensions to include
      }
    }
  ]
};

Storybook 8.x (ESM 格式)

以下是我们的测试项目中一个完整的、可用的 .storybook/main.js 配置示例

/** @type { import('@storybook/react-webpack5').StorybookConfig } */
const config = {
  stories: [
    "../code/**/*.mdx",
    "../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)",
  ],

  addons: [
    "@storybook/addon-links",
    "@storybook/addon-essentials",
    "@storybook/addon-onboarding",
    "@storybook/addon-interactions",
    {
      name: "storybook-addon-jsdoc-to-mdx",
      options: {
        folderPaths: ["./code"],
        extensions: ["ts", "js"]
      },
    },
    "@chromatic-com/storybook"
  ],

  framework: {
    name: "@storybook/react-webpack5",
    options: {
      builder: {
        useSWC: false // Recommended if you encounter issues with SWC
      },
    },
  },

  docs: {
    autodocs: true
  },
  
  // This is optional - only needed if you have issues with JSX processing
  webpackFinal: async (config) => {
    config.module.rules.push({
      test: /\.(js|jsx)$/,
      exclude: /node_modules/,
      use: {
        loader: 'babel-loader',
        options: {
          presets: ['@babel/preset-env', '@babel/preset-react']
        }
      }
    });

    return config;
  },
};
export default config;

配置完成后，像往常一样使用 npm run storybook 或 yarn storybook 启动 Storybook。此插件将自动从您的 JSDoc 注释中生成 MDX 文档。

推荐的项目结构

这是一个与此插件配合良好的项目结构示例

your-project/
├── .storybook/
│   ├── main.js          # Your Storybook configuration with the addon
│   └── preview.js
├── src/
│   ├── components/      # Your React/Vue/Angular components
│   └── code/            # Your code with JSDoc comments
│       ├── interfaces/
│       │   └── index.ts # TypeScript interfaces with JSDoc
│       ├── types/
│       │   └── index.ts # Type definitions with JSDoc
│       └── utils/
│           └── index.ts # Utility functions with JSDoc
└── package.json

当您运行 Storybook 时，此插件将

1. 扫描 folderPaths 中指定的目录
2. 从 .ts 和 .js 文件中提取 JSDoc 注释
3. 在与源文件相同的位置生成 .doc.mdx 文件
4. 这些 MDX 文件将自动显示在 Storybook 中

配置

此插件可以通过以下选项进行配置

• folderPaths：包含源文件的文件夹路径数组。
• extensions：要包含在文档生成过程中的文件扩展名数组。

特性

• 自动生成 MDX：将 JSDoc 注释转换为 Storybook 可以显示为文档的 MDX 文件。
• 支持多种文件类型：适用于 JavaScript 和 TypeScript 文件。
• 可定制路径和扩展名：您可以指定要包含的目录和文件类型。
• 支持 HTML 标签：通过自动转义 JSDoc 注释中的 HTML 标签来安全处理它们，以防止 MDX 解析错误。
• 复杂的 TypeScript 支持：正确地文档化复杂的 TypeScript 结构，包括接口、类型别名、泛型等。

高级用法

JSDoc 注释中的 HTML 标签

此插件通过自动转义来安全处理 JSDoc 注释中的 HTML 标签。这意味着您可以在文档中使用 HTML，而不会导致 MDX 解析错误

/**
 * This function accepts a <div> element and applies styles to it.
 * The <p> tags inside will be formatted according to the theme.
 * @param {HTMLElement} element - The DOM element to style
 */
function styleElement(element: HTMLElement): void {
  // Implementation...
}

TypeScript 支持

此插件为 TypeScript 语言特性提供了全面的支持

• 接口和类型
• 泛型
• 类装饰器
• 方法重载
• 可选属性
• 复杂的嵌套类型

自动重新生成

当您运行 Storybook 时，只要您的源文件发生更改，此插件就会自动重新生成文档文件。这确保了您的文档始终与您的代码保持同步。

未来计划和开发

我一直在寻求改进和扩展我的 Storybook 插件的功能。我正在考虑的一些未来开发特性包括

• 自定义文档模板：允许用户为生成的文档定义自己的模板，使他们能够更好地控制其 JS/TS 代码在 Storybook 中的呈现方式。
• AI 驱动的 JSDoc 生成：探索集成高级 AI（如大型语言模型）以自动为您的代码生成 JSDoc 注释，使文档过程更加顺畅。
• JSDoc 中的 Markdown 支持：增强对 JSDoc 注释中 Markdown 格式的支持。

故障排除

JSDoc 注释中的 HTML 标签

如果您看到此类错误

Expected a closing tag for `<div>` before the end of `paragraph`

确保您使用的是此插件的最新版本，该版本会自动转义 JSDoc 注释中的 HTML 标签。

MDX 文件未更新

如果更改源文件时 MDX 文档未更新

1. 重新启动 Storybook
2. 检查插件配置中的文件路径是否正确
3. 确保您的 JSDoc 注释遵循标准格式

Webpack 编译问题

如果您在使用 Storybook 8.x 时遇到 webpack 编译错误，请尝试在 Storybook 配置中禁用 SWC

framework: {
  name: "@storybook/react-webpack5",
  options: {
    builder: {
      useSWC: false
    },
  },
},

致谢

• 感谢 Storybook 社区持续的支持和启发。
• 特别感谢所有为改进此插件做出贡献的人。

贡献

欢迎贡献！如果您想贡献，请 fork 仓库并使用功能分支。非常欢迎拉取请求。

许可证

本项目根据 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE.md 文件。