The Turing Way项目本地构建指南更新要点解析

背景与现状

The Turing Way作为开源知识管理项目，其文档构建系统已从Jupyter Book 1升级至2.x版本。原社区手册中关于本地构建的说明存在两个关键问题：

1. 构建输出路径描述与新版工具链不符
2. 未明确说明动态内容（如pathways）的特殊构建要求

新版构建流程详解

核心变更点

• 构建产物目录结构调整为_build/html（原路径可能因版本不同存在差异）
• 新增make serve命令实现开发时实时预览：

  make serve  # 启动本地服务器并监听文件变更
  

  该命令会自动检测内容修改并触发增量构建，适合持续写作场景。

特殊内容构建说明

项目中的pathways（学习路径）内容需要特别注意：

1. 这些文件不会在常规构建过程中生成
2. 完整重建需执行：

   make clean && make build
   

3. 开发时建议配合make serve使用以获得完整预览

最佳实践建议

1. 日常开发：优先使用make serve获得带热重载的预览环境
2. 完整验证：发布前执行完整构建流程
3. 路径处理：所有文件路径引用需基于_build/html目录
4. 缓存管理：遇到显示异常时先执行清理构建

技术原理延伸

Jupyter Book 2.x的架构改进带来了更规范的构建输出结构，其底层基于Sphinx构建系统。了解这些变更有助于：

• 正确配置CI/CD流程
• 处理自定义主题时的路径引用
• 优化本地开发体验

项目维护者应及时更新相关文档，避免开发者因版本差异产生困惑。对于复杂文档项目，建立清晰的构建说明能显著降低协作门槛。