如何让ReadTheDocs中MkDocs生成的PDF在下载区正常可用

我使用mkdocs-with-pdf插件生成文档PDF，配置如下：

- with-pdf:
    cover_subtitle: PDF created with mkdocs-with-pdf
    # TODO: find a way to use $READTHEDOCS_OUTPUT and $READTHEDOCS_PROJECT
    # output_path: $READTHEDOCS_OUTPUT/$READTHEDOCS_PROJECT.pdf
    output_path: builds.pdf

PDF能正常生成，构建日志和后处理任务都确认文件存在，但ReadTheDocs（以下简称RTD）下载区的PDF选项点击后会跳转到无法访问的HTML页面。

试过这些操作但未解决问题：

• 按RTD文档建议编写构建后脚本，将PDF移到指定目录：

post_build:
  - mkdir -p $READTHEDOCS_OUTPUT/pdf/
  - mkdocs build
  - ls -lR
  - mv ./site/builds.pdf $READTHEDOCS_OUTPUT/pdf/

确认了文件位置但问题依旧；

• 尝试过htmlzip格式；
• 参考过mkdocs-pdf测试分支的配置，无效。

可行的解决步骤 #

1. 直接输出PDF到RTD指定目录
   修改mkdocs-with-pdf的配置，把PDF直接生成到RTD期望的路径，省去后续移动步骤：

- with-pdf:
    cover_subtitle: PDF created with mkdocs-with-pdf
    output_path: $READTHEDOCS_OUTPUT/pdf/$READTHEDOCS_PROJECT.pdf

RTD的构建环境会自动注入$READTHEDOCS_OUTPUT和$READTHEDOCS_PROJECT这两个环境变量，直接使用即可。

2. 调整RTD构建配置
   在.readthedocs.yaml里明确启用PDF格式，同时避免重复执行构建命令：

version: 2
formats:
  - htmlzip
  - pdf  # 必须明确开启PDF格式支持
build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
  jobs:
    post_build:
      - ls -l $READTHEDOCS_OUTPUT/pdf/  # 仅用来验证文件是否生成到位

注意不要在post_build里重复执行mkdocs build，RTD会自动执行这一步，重复执行反而会打乱它的默认流程，导致文件关联出错。

3. 匹配RTD的PDF命名规则
   RTD要求PDF文件名为$READTHEDOCS_PROJECT.pdf，放在$READTHEDOCS_OUTPUT/pdf/目录下，确保路径和文件名完全符合这个规则，RTD的下载系统才能正确识别并绑定到下载按钮。

4. 检查构建日志
   在RTD的构建日志里搜索$READTHEDOCS_OUTPUT/pdf和你的PDF文件名，确认文件确实生成在指定路径，没有权限问题或者移动失败的情况。只要文件存在且路径正确，RTD就能自动提供正常的下载链接。

避坑提醒 #

• 别重复执行mkdocs build：post_build里再跑一次会覆盖RTD默认生成的文件，破坏格式关联；
• 确认环境变量可用：RTD构建环境里自带$READTHEDOCS_OUTPUT和$READTHEDOCS_PROJECT，不用额外配置；
• 确保插件安装正确：在RTD的依赖配置里明确列出mkdocs-with-pdf，避免构建时找不到插件导致PDF生成失败。

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