升级Jupyter Book至v2时MyST构建站点遇URI malformed错误求助

• 检查内部链接格式
  重点排查所有Markdown和Notebook里的内部链接，Jupyter Book v2对URI格式校验更严格：

  • 替换路径里的空格为%20或下划线，避免空格直接出现在路径中
  • 统一使用正斜杠/作为路径分隔符，不要用反斜杠\
  • 锚点链接（如#section-title）里的特殊字符（中文、括号等）要转义，或者直接改用纯英文标题

• 排查Notebook中的隐藏链接
  有些Notebook的输出单元格或元数据里可能藏有异常链接，用命令扫描定位：

  grep -r "http\|https\|#" ./your-notebook-dir --include="*.ipynb"
  

  找到可疑链接后手动修正，或清理不必要的输出单元格。

• 验证myst.yaml配置
  检查myst.yaml里的链接相关配置，比如external_links、intersphinx项，确认URL没有缺失协议（http:///https://）、括号不匹配等格式问题。

• 启用详细日志定位问题
  构建时开启 verbose 模式，获取具体错误位置：

  jupyter-book build --verbose 2 ./your-book-folder
  

  详细日志会明确指出触发错误的文件和行号，精准定位问题点。

• 临时禁用URI校验（应急方案）
  如果以上方法都无效，可在myst.yaml中临时关闭严格校验（不推荐长期使用）：

  myst:
    url_schemes: [http, https, mailto, local]
    strict_uri: false
  

  构建成功后再逐步排查并恢复校验。

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