如何在不使用MyST的情况下构建支持HTML和PDF的Jupyter Book v1？

核心原因 #

你遇到的问题是因为新版Jupyter Book（v1.x+）默认采用MyST格式，而目标示例使用的是**旧版Jupyter Book（v0.10.x）**的结构与构建流程，因此需要针对性安装旧版本并遵循旧版命令。

步骤1：安装旧版Jupyter Book（macOS Silicon） #

1. 创建并激活虚拟环境（避免系统依赖冲突）：

   python3 -m venv jb-old-env
   source jb-old-env/bin/activate
   

2. 安装指定旧版本的Jupyter Book：

   pip install jupyter-book==0.10.3
   

3. 安装PDF构建依赖：
   • 安装Pandoc：

     brew install pandoc
     

   • 安装TeX环境（可选BasicTeX减小体积）：

     brew install --cask basictex
     # 安装额外TeX包解决PDF构建依赖缺失问题
     sudo tlmgr install adjustbox enumitem etoolbox fancyhdr float footmisc footnotebackref framed geometry hyperref lastpage listings mdwtools needspace tabu ucs url varwidth wrapfig
     

步骤2：创建旧版结构的书籍 #

执行旧版创建命令，生成与目标示例结构一致的项目：

jupyter-book create my-course-book

生成的结构包含_chapters/目录、index.rst主入口、_config.yml配置文件等，与参考课程仓库结构匹配。

步骤3：配置书籍与构建输出 #

1. 编辑_config.yml，启用HTML和PDF输出相关配置：

   title: "你的课程名称"
   author: "你的名字"
   logo: logo.png
   exclude_patterns: ["_build", "Thumbs.db", ".DS_Store"]
   sphinx:
     config:
       latex_documents:
         - targetname: book.tex
           title: "你的课程名称"
           author: "你的名字"
           theme: howto
   

2. 构建HTML版本：

   jupyter-book build my-course-book
   

   输出文件在my-course-book/_build/html目录。
3. 构建PDF版本：

   jupyter-book build my-course-book --builder latexpdf
   

   输出PDF在my-course-book/_build/latex目录。

步骤4：部署到GitHub Pages #

1. 安装ghp-import工具：

   pip install ghp-import
   

2. 将构建好的HTML目录推送到GitHub的gh-pages分支：

   ghp-import -n -p -f my-course-book/_build/html
   

3. 登录GitHub仓库，在「Settings」→「Pages」中设置源为gh-pages分支的/root目录，等待部署完成。

额外提示 #

• 逆向分析现有旧版仓库时，可查看其requirements.txt或environment.yml文件，确认依赖的Jupyter Book版本，确保环境一致。
• 若需参考旧版官方文档，可在GitHub搜索jupyter-book的tags，找到v0.10.3对应的归档文档。

内容的提问来源于stack exchange，提问作者dareen