Plutus项目文档系统从ReadTheDocs向Docusaurus的完整迁移实践

迁移背景与决策考量

Plutus作为智能合约开发平台，其文档系统的易用性和可维护性直接影响开发者体验。传统的ReadTheDocs（RTD）方案虽然成熟，但在交互体验和本地开发友好性上存在局限。团队最终选择迁移至Docusaurus主要基于以下技术优势：

1. 现代化UI框架：基于React的界面支持更丰富的交互组件
2. Markdown优先：降低内容维护门槛，支持MDX扩展
3. 版本控制集成：原生支持多版本文档管理
4. 本地开发体验：实时热重载和更快的构建速度

迁移实施关键步骤

1. 旧系统清理与结构重组

• 保留doc/read-the-docs-site目录下的README作为迁移记录
• 将Docusaurus项目目录整合至标准doc目录结构
• 建立清晰的文档版本映射关系

2. 持续交付流水线改造

• 重构GitHub Actions工作流，分离Haddock文档和Docusaurus站点的发布流程
• 实现自动化版本触发机制，确保文档与代码版本同步
• 优化构建缓存策略，缩短CI/CD流水线执行时间

3. 访问路由切换

• 移除RTD的Webhook集成
• 配置RTD域名的301永久重定向
• 设计新旧URL映射方案，保证外部链接可用性

4. 基础设施清理

• 清除Nix构建系统中与RTD相关的残留配置
• 统一文档构建工具链，消除技术栈冲突
• 更新开发环境配置指南

技术挑战与解决方案

Haddock集成问题： 通过建立独立的发布流程，将Haddock生成的API文档作为静态资源嵌入Docusaurus架构。采用符号链接保持文档结构一致性，同时维护版本化访问路径。

样式统一化处理：

• 定制Docusaurus主题色系匹配Plutus品牌规范
• 开发专用组件包装Haddock输出内容
• 实现响应式布局适配移动端访问

搜索体验优化：

• 配置Algolia DocSearch爬虫规则
• 设计混合搜索策略，同时覆盖手动文档和API参考
• 添加搜索关键词高亮支持

迁移后的改进效果

1. 构建性能提升：文档构建时间从平均12分钟降至3分钟
2. 内容贡献简化：非技术人员可通过纯Markdown提交修改
3. 交互能力增强：新增嵌入式REPL演示和合约示例交互面板
4. 多语言支持：为国际化预留了结构化内容框架

维护规范建议

对于开源项目维护者：

• 版本发布时同步执行yarn deploy推送文档更新
• API文档生成需在发布前验证类型签名变更
• 定期检查第三方服务（如Algolia）的索引状态

对于内容贡献者：

• 使用约定式提交规范更新文档
• 复杂组件需提供开发模式预览说明
• 跨版本修改需确认版本标签作用域

该迁移案例为区块链项目的文档工程实践提供了完整范例，其技术选型过程和实施方案值得同类项目参考。未来可进一步探索文档测试自动化、智能代码片段注入等进阶特性。