Modern.js 模块文档开发指南：从零搭建组件文档站点

前言

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

为什么需要专业文档站点

1. 结构化展示：相比简单的 Markdown 文件，文档站点能更好地组织内容结构
2. 交互体验：支持在页面中直接执行函数、渲染组件，提升用户体验
3. 搜索能力：为 AI 搜索提供更好的内容基础，方便用户查找信息
4. 专业形象：提升项目的专业度和可信度

环境准备

在开始之前，请确保：

1. 已通过 Modern.js 的微生成器开启文档功能
2. 熟悉 Rspress 文档框架的基本概念

文档站点架构解析

Modern.js 的文档系统基于 Rspress 构建，整体布局包含三个核心部分：

• 导航栏：顶部全局导航区域
• 侧边栏：左侧文档目录结构
• 正文区域：包含内容主体和右侧的目录导航(TOC)

文件路由系统

Rspress 采用文件系统路由机制，文档路径与文件结构自动对应：

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

侧边栏自动生成

Modern.js 会根据文档目录结构自动生成侧边栏，每个条目的显示文本由文件的一级标题或目录名决定。如需自定义，可通过 _meta.json 文件或直接配置 sidebar 选项实现。

文档内容编写指南

基础 Markdown 编写

支持标准 Markdown 语法，包括：

• 标题层级
• 代码块
• 表格
• 列表等

高级功能

1. MDX 支持：在 Markdown 中直接使用 React 组件
2. 静态资源：轻松引用图片等静态文件
3. 自定义布局：通过 Frontmatter 控制页面布局

组件预览功能详解

Modern.js 文档系统的一大亮点是强大的组件预览能力。

基本使用

在代码块中直接编写组件代码：

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

export default () => {
  return <Button size="large">点击我</Button>;
};
```

配置技巧

1. 路径别名：在 tsconfig.json 中配置模块别名，确保开发和生产环境一致
2. 产物目录：将 doc_build/ 添加到 .gitignore 中

移动端预览方案

Modern.js 提供两种预览模式：

1. 内置模式(internal)：组件直接渲染在页面中
2. iframe 模式：通过 iframe 隔离渲染，适合移动端组件

配置示例：

modulePluginDoc({
  previewMode: 'iframe',
  iframePosition: 'fixed' // 或 'follow'
})

代码块修饰符

可针对单个代码块指定渲染方式：

```jsx internal
// 内置渲染
```

```jsx iframe
// iframe 渲染
```

```jsx pure
// 仅显示代码
```

外部 Demo 引用

对于复杂组件，建议使用外部文件：

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

API 文档自动生成

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

配置解析

1. 指定解析工具（支持 react-docgen-typescript 和 documentation）
2. 配置待解析的文件路径

modulePluginDoc({
  apiParseTool: 'react-docgen-typescript',
  entries: {
    Button: './src/button.tsx'
  }
})

组件 Props 文档

系统会自动从 TypeScript 类型定义中提取信息生成表格：

export type ButtonProps = {
  /** 是否禁用 */
  disabled?: boolean;
  /** 按钮尺寸 */
  size?: 'small' | 'medium' | 'large';
};

工具函数文档

对于工具库，可使用 documentation 工具生成 JSDoc 注释文档：

/**
 * 加法函数
 * @param a 第一个数字
 * @param b 第二个数字
 * @returns 两数之和
 */
function add(a: number, b: number) {
  return a + b;
}

在文档中使用

通过 <API> 组件展示自动生成的文档：

## API 参考

<API moduleName="Button" />

内置组件介绍

Modern.js 文档系统提供多个实用内置组件：

Overview 组件

用于创建模块概览页面，非常适合作为文档首页：

<Overview
  list={[
    {
      icon: <ButtonIcon />,
      text: "按钮组件",
      link: "/components/button",
      arrow: true
    }
  ]}
/>

进阶配置选项

多工具混合解析

可根据文件类型使用不同解析工具：

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

解析工具配置

支持为不同工具传递特定参数：

parseToolOptions: {
  'react-docgen-typescript': {
    savePropValueAsString: true
  },
  documentation: {
    shallow: true
  }
}

构建与部署

Modern.js 提供两条核心命令：

1. modern dev - 启动本地开发服务器
2. modern build --platform - 构建生产环境文档

构建产物默认输出到 doc_build 目录。

最佳实践建议

1. 组件文档：为每个组件创建独立文档，包含示例和 API
2. 示例代码：提供多种使用场景的示例
3. 类型定义：确保 Props 类型定义完整且有详细注释
4. 版本管理：文档与代码版本保持同步
5. 移动端适配：重要组件提供移动端预览

总结

Modern.js 的模块文档系统为开发者提供了一站式的文档解决方案，从基础的 Markdown 编写到高级的组件预览、API 自动生成，覆盖了文档开发的各个方面。通过本文介绍的功能和技巧，你可以为你的模块项目创建专业、易用的文档站点，显著提升开发体验和项目质量。