Modern.js 模块文档开发指南：从入门到精通
前言
在现代前端开发中，良好的文档是项目成功的关键因素之一。Modern.js 提供了强大的模块文档开发能力，让开发者能够轻松构建专业级的文档站点。本文将全面介绍如何使用 Modern.js 开发模块文档，涵盖从基础配置到高级特性的完整知识体系。
为什么需要模块文档站点
- 结构化组织：文档站点能帮助我们更好地组织文档结构，形成清晰的层次关系
- 丰富展示：支持在页面中执行函数、渲染组件等交互式演示
- AI友好：为未来的AI搜索能力提供良好基础
- 专业形象：提升项目的专业度和可信度
准备工作
- 确保已通过微生成器启用文档功能
- 熟悉 Rspress 文档框架的基本概念
文档站点基础架构
Modern.js 的模块文档基于 Rspress 构建，采用标准的文件系统路由机制，自动生成导航结构。
文件路由映射规则
文档站点的路由结构直接对应文件系统的目录结构：
docs/
├── guide/
│ ├── getting-started.md → /guide/getting-started
│ └── index.md → /guide/
└── api.md → /api
侧边栏自动生成
系统会根据文档目录结构自动生成侧边栏导航，每个条目的文本由文件的一级标题或目录名决定。
自定义侧边栏
如需自定义侧边栏，可通过以下方式实现：
- 使用
_meta.json文件进行局部配置 - 在配置文件中直接定义
sidebar属性
文档编写技巧
MDX 增强语法
Modern.js 文档支持 MDX 格式，允许在 Markdown 中直接嵌入 JSX 组件：
# 组件演示
下面是一个 React 组件的实时演示：
```tsx
import React from 'react';
function Counter() {
const [count, setCount] = React.useState(0);
return (
<button onClick={() => setCount(count + 1)}>
点击次数: {count}
</button>
);
}
静态资源处理
文档中可方便地引用图片等静态资源：
组件预览功能
Modern.js 文档系统提供了强大的组件预览能力，可直接在文档中渲染 React 组件。
基础配置
- 在
tsconfig.json中配置路径别名，确保文档和实际使用方式一致 - 在
.gitignore中添加文档构建输出目录
移动端预览
支持通过 iframe 方式预览移动端组件，并可配置 iframe 的定位方式：
// modern.config.ts
export default defineConfig({
plugins: [
modulePluginDoc({
previewMode: 'iframe',
iframePosition: 'fixed'
})
]
});
代码块修饰符
可通过不同修饰符控制代码块的渲染方式：
```tsx pure
// 纯代码展示，不渲染
```
```tsx internal
// 在文档内部直接渲染
```
```tsx iframe
// 在iframe中渲染
```
API 文档生成
Modern.js 提供了自动生成 API 文档的能力，支持两种解析工具：
1. react-docgen-typescript
专为组件库设计，自动提取 Props 生成表格：
interface ButtonProps {
/**
* 按钮尺寸
* @default 'medium'
*/
size?: 'small' | 'medium' | 'large';
}
export function Button(props: ButtonProps) {
// ...
}
2. documentation
适用于工具库，解析 JSDoc 注释：
/**
* 计算两个数字的和
* @param a 第一个数字
* @param b 第二个数字
* @returns 两数之和
*/
export function add(a: number, b: number) {
return a + b;
}
在文档中使用
## API 参考
<API moduleName="Button" />
高级配置
多语言支持
Modern.js 文档支持国际化配置，可通过 locales 设置实现多语言切换：
modulePluginDoc({
doc: {
locales: [
{
lang: 'zh',
label: '中文'
},
{
lang: 'en',
label: 'English'
}
]
}
})
主题定制
可通过修改配置来自定义文档站点的主题样式：
modulePluginDoc({
doc: {
themeConfig: {
darkMode: false,
primaryColor: '#1890ff'
}
}
})
构建与部署
Modern.js 提供了简单的构建命令：
# 开发模式
pnpm run dev
# 生产构建
pnpm run build --platform
构建产物默认输出到 doc_build 目录，可直接部署到任何静态网站托管服务。
最佳实践
- 组件文档：为每个组件创建单独的文档文件，包含示例和API
- 示例代码：保持示例简洁，展示核心功能
- 版本控制：文档应与代码同步更新
- 交互体验：充分利用实时预览功能提升用户体验
总结
Modern.js 的模块文档系统为开发者提供了一站式的文档解决方案，从简单的 Markdown 编写到复杂的组件演示，都能轻松应对。通过本文的介绍，相信您已经掌握了 Modern.js 文档开发的核心要点，可以开始为您的项目构建专业级的文档站点了。
记住，好的文档是项目成功的一半，定期维护和更新文档，将为您的项目带来长期的价值。
