storybook-addon-jsdoc-to-mdx
Storybook 插件,可根据 TypeScript 和 JavaScript 文件中的 JSDoc 注释自动生成 MDX 文档。支持注释中的 HTML 标签、复杂的 TypeScript 类型,并与 Storybook 7.x 和 8.x 无缝集成。
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 中显示如下
目录
要求
- 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 时,此插件将
- 扫描
folderPaths
中指定的目录 - 从
.ts
和.js
文件中提取 JSDoc 注释 - 在与源文件相同的位置生成
.doc.mdx
文件 - 这些 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 文档未更新
- 重新启动 Storybook
- 检查插件配置中的文件路径是否正确
- 确保您的 JSDoc 注释遵循标准格式
Webpack 编译问题
如果您在使用 Storybook 8.x 时遇到 webpack 编译错误,请尝试在 Storybook 配置中禁用 SWC
framework: {
name: "@storybook/react-webpack5",
options: {
builder: {
useSWC: false
},
},
},
致谢
- 感谢 Storybook 社区持续的支持和启发。
- 特别感谢所有为改进此插件做出贡献的人。
贡献
欢迎贡献!如果您想贡献,请 fork 仓库并使用功能分支。非常欢迎拉取请求。
许可证
本项目根据 MIT 许可证授权 - 有关详细信息,请参阅 LICENSE.md 文件。