Modern.js 模块文档开发指南：从零构建专业文档站点

前言

在现代前端开发中，良好的文档是项目成功的关键因素之一。Modern.js 提供了一套完整的模块文档解决方案，让开发者能够轻松为模块项目构建专业的文档站点。本文将详细介绍如何利用 Modern.js 的文档功能，从基础搭建到高级功能应用。

为什么需要文档站点

1. 结构化展示：相比零散的 Markdown 文件，文档站点能更好地组织内容结构
2. 交互体验：支持在页面中直接执行函数、渲染组件，提供更直观的体验
3. 搜索能力：为 AI 搜索提供更好的内容基础，提升文档可发现性
4. 专业形象：统一的视觉风格和导航体验，提升项目专业度

准备工作

1. 确保已通过微生成器启用文档功能
2. 熟悉 Rspress 文档框架的基本概念
3. 确保项目已配置 TypeScript（如需 API 文档自动生成）

基础站点结构

Modern.js 文档站点采用标准的三栏布局：

• 导航栏：顶部全局导航
• 侧边栏：文档目录结构
• 内容区：文档主体内容，包含 TOC（目录导航）

文件路由系统

文档站点基于 Rspress 的文件系统路由自动生成路由和侧边栏。以下是一个典型的结构示例：

docs/
├── guide/
│   ├── getting-started.md
│   └── advanced.md
├── components/
│   └── button.md
└── index.md

路由生成规则遵循直觉：

文件路径	路由路径
index.md	/
foo.md	/foo
foo/index.md	/foo/
foo/bar.md	/foo/bar

文档编写技巧

基础 Markdown 语法

支持所有标准 Markdown 语法，包括：

• 标题分级
• 代码块
• 表格
• 列表
• 链接等

高级功能

1. MDX 支持：在 Markdown 中直接使用 JSX 和 React 组件
2. 资源管理：轻松引用图片等静态资源
3. 自定义组件：扩展文档交互能力

组件预览功能

Modern.js 文档的核心特性之一是组件实时预览，让文档"活"起来。

基础示例

假设我们有一个 Button 组件：

```tsx
import React from 'react';
import { Button } from 'your-module';

export default () => {
  return <Button size="large">Click Me</Button>;
};
```

配置要点：

1. 在 tsconfig.json 中配置路径别名
2. 确保组件已构建
3. 忽略文档构建目录 .gitignore

移动端预览

支持 iframe 模式预览移动端组件：

// modern.config.ts
export default defineConfig({
  plugins: [
    modulePluginDoc({
      previewMode: 'iframe',
      iframePosition: 'fixed' // 或 'follow'
    }),
  ],
});

代码块修饰符

控制单个代码块的渲染方式：

```jsx pure   // 仅显示代码
```jsx internal // 内联渲染
```jsx iframe   // iframe 渲染

外部 Demo 引用

复杂 Demo 可单独编写后引用：

<code src="/path/to/demo.tsx" />

API 文档自动化

Modern.js 提供强大的 API 文档自动生成能力。

配置解析

// modern.config.ts
export default defineConfig({
  plugins: [
    modulePluginDoc({
      entries: {
        Button: './src/button.tsx',
      },
      apiParseTool: 'react-docgen-typescript',
    }),
  ],
});

支持两种解析工具：

1. react-docgen-typescript：专为组件库设计，解析 Props
2. documentation：通用工具库场景，解析 JSDoc

在文档中使用

<API moduleName="Button" />

类型提示

确保 React 类型可解析：

// tsconfig.json
{
  "compilerOptions": {
    "types": ["react"]
  }
}

内置组件

Overview 组件

展示模块列表，适合首页：

<Overview list={[
  {
    icon: <Icon />,
    text: "Button",
    link: "/components/button",
    arrow: true
  }
]} />

高级配置

插件选项详解

选项	类型	默认值	说明
apiParseTool	'react-docgen-typescript'|'documentation'	'react-docgen-typescript'	API 解析工具
doc	RspressConfig	-	Rspress 配置
entries	Record<string, string>	{}	模块入口配置
iframePosition	'follow'|'fixed'	'follow'	iframe 定位方式
previewMode	'iframe'|'internal'	'internal'	预览模式

多工具混合配置

entries: {
  documentation: {
    utils: './src/utils.ts'
  },
  'react-docgen-typescript': {
    Button: './src/button.tsx'
  }
}

构建与部署

常用命令

• pnpm run dev：启动开发服务器
• pnpm run build --platform：生产环境构建
• 输出目录默认为 doc_build/

最佳实践建议

1. 文档结构规划：提前设计好文档目录结构
2. 组件示例：为每个主要功能提供可交互示例
3. API 文档：保持类型定义和注释的及时更新
4. 移动适配：重要组件提供移动端预览
5. 版本控制：考虑文档与代码版本同步

总结

Modern.js 的模块文档解决方案将文档编写、组件展示和 API 文档生成融为一体，大大提升了前端模块项目的文档体验。通过本文介绍的功能和技巧，开发者可以快速构建出专业级的文档站点，有效提升项目的可维护性和用户体验。

随着项目的演进，建议进一步探索 Rspress 的高级功能，如主题定制、插件开发等，打造更加完善的文档生态系统。