Configuration file reference (original) (raw)

Read the Docs supports configuring your documentation builds with a configuration file. This file is named .readthedocs.yaml and should be placed in the top level of your Git repository.

The .readthedocs.yaml file can contain a number of settings that are not accessible through the Read the Docs website.

Because the file is stored in Git, the configuration will apply to the exact version that is being built.This allows you to store different configurations for different versions of your documentation.

Supported settings

Read the Docs validates every configuration file. Any configuration option that isn’t supported will make the build fail. This is to avoid typos and provide feedback on invalid configurations.

Warning

When using a v2 configuration file, the local settings from the web interface are ignored.

version

Required:

true

Example:

formats

Additional formats of the documentation to be built, apart from the default HTML.

Type:

list

Options:

htmlzip, pdf, epub, all

Default:

[]

Example:

version: 2

Default

formats: []

version: 2

Build PDF & ePub

formats:

Note

You can use the all keyword to indicate all formats.

version: 2

Build all formats

formats: all

Warning

At the moment, only Sphinx supports additional formats.pdf, epub, and htmlzip output is not yet supported when using MkDocs.

With builds from pull requests, only HTML formats are generated. Other formats are resource intensive and will be built after merging.

python

Configuration of the Python environment to be used.

version: 2

python: install: - requirements: docs/requirements.txt - method: pip path: . extra_requirements: - docs - method: pip path: another/package

python.install

Read the Docs uses pip by default to install your Python packages, however if you are using a Conda environment to manage your build, you’ll need to use the Conda environment file instead. If you have a commercial plan you can also install private dependencies.

List of installation methods of packages and requirements. You can have several of the following methods.

Type:

list

Default:

[]

Requirements file

Install packages from a requirements file.

The path to the requirements file, relative to the root of the project.

Key:

requirements

Type:

path

Required:

false

Example:

version: 2

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

Packages

Install the project using pip install. The use of python setup.py install is deprecated.

The path to the package, relative to the root of the project.

Key:

path

Type:

path

Required:

false

The installation method.

Key:

method

Options:

pip, setuptools (deprecated)

Default:

pip

Extra requirements section to install in addition to the package dependencies.

Key:

extra_requirements

Type:

list

Default:

[]

For example, to run pip install .[docs]:

version: 2

python: install: - method: pip path: . extra_requirements: - docs

conda

Configuration for Conda support.

version: 2

build: os: "ubuntu-24.04" tools: python: "mambaforge-22.9"

conda: environment: environment.yml

conda.environment

The path to the Conda environment file, relative to the root of the project.

Type:

path

Required:

false

Note

When using Conda, it’s required to specify build.tools.python to tell Read the Docs to use whether Conda or Mamba to create the environment.

build

Configuration for the documentation build process. This allows you to specify the base Read the Docs image used to build the documentation, and control the versions of several tools: Python, Node.js, Rust, and Go.

version: 2

build: os: ubuntu-24.04 tools: python: "3.13" nodejs: "22" rust: "1.82" golang: "1.23"

build.os

The Docker image used for building the docs. Image names refer to the operating system Read the Docs uses to build them.

Note

Arbitrary Docker images are not supported.

Type:

string

Options:

ubuntu-20.04, ubuntu-22.04, ubuntu-24.04, ubuntu-lts-latest

Required:

true

Note

The ubuntu-lts-latest option refers to the latest Ubuntu LTS version of Ubuntu available on Read the Docs, which may not match the latest Ubuntu LTS officially released.

Warning

Using ubuntu-lts-latest may break your builds unexpectedly if your project isn’t compatible with the newest Ubuntu LTS version when it’s updated by Read the Docs.

build.tools

Version specifiers for each tool. It must contain at least one tool.

Type:

dict

Options:

python, nodejs, ruby, rust, golang

Required:

true

Note

Each tool has a latest option available, which refers to the latest version available on Read the Docs, which may not match the latest version officially released. Versions and the latest option are updated at least once every six months to keep up with the latest releases.

Warning

Using latest may break your builds unexpectedly if your project isn’t compatible with the newest version of the tool when it’s updated by Read the Docs.

build.tools.python

Python version to use. You can use several interpreters and versions, from CPython, Miniconda, and Mamba.

Type:

string

Options:

build.tools.nodejs

Node.js version to use.

Type:

string

Options:

build.tools.ruby

Ruby version to use.

Type:

string

Options:

build.tools.rust

Rust version to use.

Type:

string

Options:

build.tools.golang

Go version to use.

Type:

string

Options:

build.apt_packages

List of APT packages to install. Our build servers run various Ubuntu LTS versions with the default set of package repositories installed. We don’t currently support PPA’s or other custom repositories.

Type:

list

Default:

[]

version: 2

build: apt_packages: - libclang - cmake

Warning

Currently, it’s not possible to use this option when using build.commands.

build.jobs

Commands to be run before or after a Read the Docs pre-defined build jobs, or to override a specific job. This allows you to run custom commands at a particular moment in the build process. See Build process customization for more details.

version: 2

build: os: ubuntu-24.04 tools: python: "3.13" jobs: pre_create_environment: - echo "Command run at 'pre_create_environment' step" post_build: - echo "Command run at 'post_build' step" - echo date

Note

Each build step consists of a list of commands to be executed.build.os and build.tools are also required to use build.jobs.

Note

If the sphinx or mkdocs keys are present in the configuration file, the default steps for each tool will be executed for the create_environment, install, and build steps. You can override any of these steps, but be aware that some steps may depend on others, for example, the default install and build steps depend on the create_environment step creating the Python virtual environment in a specific directory.

If neither of the sphinx or mkdocs keys are present in the configuration file, only the specified build.tools and build.apt_packages will be installed, you will in charge of generating the documentation in the $READTHEDOCS_OUTPUT directory.

Type:

dict

Allowed keys:

post_checkout, pre_system_dependencies, post_system_dependencies,pre_create_environment, create_environment, post_create_environment, pre_install, post_install,pre_build, build, post_build

Required:

false

Default:

{}

build.jobs.build

Commands to override the default build process. When running builds from pull requests, only the html step will be executed.

version: 2

formats: [pdf, epub] build: os: ubuntu-24.04 tools: python: "3.13" jobs: create_environment: - echo "Preparing environment" install: - echo "Installing dependencies" build: html: - echo "Building HTML" - mkdir -p $READTHEDOCS_OUTPUT/html/ - echo "Hello world!" > $READTHEDOCS_OUTPUT/html/index.html pdf: - echo "Building PDF" - mkdir -p $READTHEDOCS_OUTPUT/pdf/ - echo "Hello world!" > $READTHEDOCS_OUTPUT/pdf/index.pdf epub: - echo "Building ePub" - mkdir -p $READTHEDOCS_OUTPUT/epub/ - echo "Hello world!" > $READTHEDOCS_OUTPUT/epub/index.epub

Type:

dict

Allowed keys:

html, pdf, epub, htmlzip

Required:

false

Default:

{}

Note

If any of the pdf, epub, or htmlzip steps are overridden, they should be included in the formats list.

build.commands

Specify a list of commands that Read the Docs will run on the build process. When build.commands is used, none of the pre-defined build jobs will be executed.

version: 2

build: os: ubuntu-24.04 tools: python: "3.13" commands: - pip install pelican - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

But we recommend using build.jobs instead:

.readthedocs.yaml

version: 2 build: os: "ubuntu-22.04" tools: python: "3.10" jobs: install: - pip install pelican build: html: - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

build.jobs 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. See Build process customization for more details.

Note

build.os and build.tools are also required when using build.commands.

Type:

list

Required:

false

Default:

[]

sphinx

Configuration for Sphinx documentation.

version: 2

sphinx: builder: html configuration: conf.py fail_on_warning: true

sphinx.builder

The builder type for the Sphinx documentation.

Type:

string

Options:

html, dirhtml, singlehtml

Default:

html

Note

The htmldir builder option was renamed to dirhtml to use the same name as sphinx. Configurations using the old name will continue working.

sphinx.configuration

The path to the conf.py file, relative to the root of the project.

Type:

path

Required:

true

sphinx.fail_on_warning

Turn warnings into errors (-W and --keep-going options). This means the build fails if there is a warning and exits with exit status 1.

Type:

bool

Default:

false

mkdocs

Configuration for MkDocs documentation.

version: 2

mkdocs: configuration: mkdocs.yml fail_on_warning: false

mkdocs.configuration

The path to the mkdocs.yml file, relative to the root of the project.

Type:

path

Required:

true

mkdocs.fail_on_warning

Turn warnings into errors. This means that the build stops at the first warning and exits with exit status 1.

Type:

bool

Default:

false

submodules

VCS submodules configuration.

Note

Only Git is supported at the moment.

Warning

You can’t use include and exclude settings for submodules at the same time.

version: 2

submodules: include: - one - two recursive: true

submodules.include

List of submodules to be included.

Type:

list

Default:

[]

Note

You can use the all keyword to include all submodules.

version: 2

submodules: include: all

submodules.exclude

List of submodules to be excluded.

Type:

list

Default:

[]

Note

You can use the all keyword to exclude all submodules. This is the same as include: [].

version: 2

submodules: exclude: all

submodules.recursive

Do a recursive clone of the submodules.

Type:

bool

Default:

false

Note

This is ignored if there aren’t submodules to clone.

search

Settings for more control over Server side search.

version: 2

search: ranking: api/v1/: -1 api/v2/: 4 ignore: - 404.html

search.ranking

Set a custom search rank over pages matching a pattern.

Type:

map of patterns to ranks

Default:

{}

Patterns are matched against the relative paths of the HTML files produced by the build, you should try to match index.html, not docs/index.rst, nor /en/latest/index.html. Patterns can include one or more of the following special characters:

The rank can be an integer number between -10 and 10 (inclusive). Pages with a rank closer to -10 will appear further down the list of results, and pages with a rank closer to 10 will appear higher in the list of results. Note that 0 means normal rank, not no rank.

If you are looking to completely ignore a page, check search.ignore.

version: 2

search: ranking: # Match a single file tutorial.html: 2

# Match all files under the api/v1 directory
api/v1/*: -5

# Match all files named guides.html,
# two patterns are needed to match both the root and nested files.
'guides.html': 3
'*/guides.html': 3

Note

The final rank will be the last pattern to match the page.

Tip

Is better to decrease the rank of pages you want to deprecate, rather than increasing the rank of the other pages.

search.ignore

List of paths to ignore and exclude from the search index. Paths matched will not be included in search results.

Type:

list of patterns

Default:

['search.html', 'search/index.html', '404.html', '404/index.html']

Patterns are matched against the relative paths of the HTML files produced by the build, you should try to match index.html, not docs/index.rst, nor /en/latest/index.html. Patterns can include one or more of the following special characters:

version: 2

search: ignore: # Ignore a single file in the root of the output directory - 404.html

 # Ignore all files under the search/ directory
 - search/*

 # Ignore all files named ref.html,
 # two patterns are needed to match both the root and nested files.
 - 'ref.html'
 - '*/ref.html'

version: 2

search: ignore: # Custom files to ignore - file.html - api/v1/*

 # Defaults
 - search.html
 - search/index.html
 - 404.html
 - 404/index.html

Note

Since Read the Docs fallbacks to the original search engine when no results are found, you may still see search results from ignored pages.