We are excited to announce that you can now partially or completely override build steps using the build.jobs configuration in your .readthedocs.yaml configuration file. This allows you to customize the build process to suit your project's specific requirements. Find more details and examples in our documentation.

Previously, you could only extend the build process by using any of the pre_ and post_ build jobs, we have now extended this functionality to allow you to override the build process completely. The following build steps are available for you to override:

• create_environment
• install
• build.html
• build.pdf
• build.epub
• build.htmlzip

If you are using Sphinx or MkDocs, but you want to have more control over how a specific step is executed, you can override only that step. For example, to use the normal build process for HTML and EPUB when building a Sphinx project, but use rinohtype for PDF output, you can use the following configuration:

version: 2

formats:
  - pdf
  - epub

sphinx:
  configuration: docs/conf.py

python:
  install:
    - requirements: docs/requirements.txt

build:
  os: ubuntu-24.04
  tools:
    python: "3.13"
  jobs:
    build:
      pdf:
        - sphinx-build -b rinoh docs _build/pdf/
        - mkdir --parents $READTHEDOCS_OUTPUT/pdf/
        - mv _build/pdf/*.pdf $READTHEDOCS_OUTPUT/pdf/

If you are using another tool, or you want complete control over the build process, you can use a similar configuration without specifying a sphinx or mkdocs configuration to have full control over the build process. For example, to build using Markdoc you can use the following configuration:

version: 2

build:
  os: ubuntu-24.04
  tools:
    nodejs: "22"
  jobs:
    install:
      - cd docs/ && npm install
    build:
      html:
        - cd docs/ && npm run build
        - mkdir --parents $READTHEDOCS_OUTPUT/html/
        - cp --recursive docs/out/* $READTHEDOCS_OUTPUT/html/

You can check our docs for a working example.

We recommend using build.jobs over build.commands, as it offers the same functionality as build.commands, but in a more structured way that allows you to define different commands for each format, while also supporting installing system dependencies via build.apt_packages.