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.
Below is an example YAML file which shows the most common configuration options:
Sphinx
/config-file/examples/sphinx/.readthedocs.yaml
MkDocs
/config-file/examples/mkdocs/.readthedocs.yaml
/config-file/index
Practical steps to add a configuration file to your documentation project.
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.
- Required
true
Example:
version: 2
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:
- epub
- pdf
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 </pull-requests>
, only HTML formats are generated. Other formats are resource intensive and will be built after merging.
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
List of installation methods of packages and requirements. You can have several of the following methods.
- Type
list
- Default
[]
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
Warning
If you are using a Conda <config-file/v2:conda>
environment to manage the build, this setting will not have any effect. Instead add the extra requirements to the environment
file of Conda.
Install the project using pip install
(recommended) or python setup.py install
(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.
Warning
You need to install your project with pip
to use extra_requirements
.
- Key
extra_requirements
- Type
list
- Default
[]
Example:
version: 2
python:
install:
- method: pip
path: .
extra_requirements:
- docs
With the previous settings, Read the Docs will execute the next commands:
bash $
pip install .[docs]
Configuration for Conda support.
version: 2
build:
os: "ubuntu-22.04"
tools:
python: "mambaforge-22.9"
conda:
environment: environment.yml
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.
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-22.04
tools:
python: "3.12"
nodejs: "18"
rust: "1.64"
golang: "1.19"
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-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.
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.
Python version to use. You can use several interpreters and versions, from CPython, Miniconda, and Mamba.
Note
If you use Miniconda3 or Mambaforge, you can select the Python version using the environment.yml
file. See our /guides/conda
guide for more information.
- Type
string
- Options
2.7
3
(alias for the latest 3.x version available on Read the Docs)3.6
3.7
3.8
3.9
3.10
3.11
3.12
latest
(alias for the latest version available on Read the Docs)miniconda3-4.7
miniconda-latest
(alias for the latest version available on Read the Docs)mambaforge-4.10
mambaforge-22.9
mambaforge-latest
(alias for the latest version available on Read the Docs)
Node.js version to use.
- Type
string
- Options
14
16
18
19
20
latest
(alias for the latest version available on Read the Docs)
Ruby version to use.
- Type
string
- Options
3.3
latest
(alias for the latest version available on Read the Docs)
Rust version to use.
- Type
string
- Options
1.55
1.61
1.64
1.70
1.75
latest
(alias for the latest version available on Read the Docs)
Go version to use.
- Type
string
- Options
1.17
1.18
1.19
1.20
1.21
latest
(alias for the latest version available on Read the Docs)
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
Note
When possible avoid installing Python packages using apt (python3-numpy
for example), use pip or conda instead </guides/reproducible-builds>
.
Warning
Currently, it's not possible to use this option when using config-file/v2:build.commands
.
Commands to be run before or after a Read the Docs pre-defined build jobs
. This allows you to run custom commands at a particular moment in the build process. See /build-customization
for more details.
version: 2
build:
os: ubuntu-22.04
tools:
python: "3.12"
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 key under build.jobs
must be a list of strings. build.os
and build.tools
are also required to use build.jobs
.
- Type
dict
- Allowed keys
post_checkout
,pre_system_dependencies
,post_system_dependencies
,pre_create_environment
,post_create_environment
,pre_install
,post_install
,pre_build
,post_build
- Required
false
- Default
{}
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. (see /build-customization
for more details). This allows you to run custom commands and control the build process completely. The $READTHEDOCS_OUTPUT/html
directory will be uploaded and hosted by Read the Docs.
Warning
This feature is in a beta phase and could suffer incompatible changes or even removed completely in the near feature. We are currently testing the new addons integrations we are building on projects using build.commands
configuration key. Use it under your own responsibility.
version: 2
build:
os: ubuntu-22.04
tools:
python: "3.12"
commands:
- pip install pelican
- pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/
Note
build.os
and build.tools
are also required when using build.commands
.
- Type
list
- Required
false
- Default
[]
Configuration for Sphinx documentation (this is the default documentation type).
version: 2
sphinx:
builder: html
configuration: conf.py
fail_on_warning: true
Note
If you want to pin Sphinx to a specific version, use a requirements.txt
or environment.yml
file (see config-file/v2:requirements file
and config-file/v2:conda.environment
). If you are using a metadata file to describe code dependencies like setup.py
, pyproject.toml
, or similar, you can use the extra_requirements
option (see config-file/v2:packages
). This also allows you to override the default pinning done by Read the Docs
if your project was created before October 2020 <build-default-versions:external dependencies>
.
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.
The path to the conf.py
file, relative to the root of the project.
- Type
path
- Default
null
If the value is null
, Read the Docs will try to find a conf.py
file in your project.
Turn warnings into errors (-W <sphinx:sphinx-build.-W>
and --keep-going <sphinx:sphinx-build.--keep-going>
options). This means the build fails if there is a warning and exits with exit status 1.
- Type
bool
- Default
false
Configuration for MkDocs documentation.
version: 2
mkdocs:
configuration: mkdocs.yml
fail_on_warning: false
Note
If you want to pin MkDocs to a specific version, use a requirements.txt
or environment.yml
file (see config-file/v2:requirements file
and config-file/v2:conda.environment
). If you are using a metadata file to describe code dependencies like setup.py
, pyproject.toml
, or similar, you can use the extra_requirements
option (see config-file/v2:packages
). This also allows you to override the default pinning done by Read the Docs
if your project was created before March 2021 <build-default-versions:external dependencies>
.
The path to the mkdocs.yml
file, relative to the root of the project.
- Type
path
- Default
null
If the value is null
, Read the Docs will try to find a mkdocs.yml
file in your project.
Turn warnings into errors. This means that the build stops at the first warning and exits with exit status 1.
- Type
bool
- Default
false
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
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
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
Do a recursive clone of the submodules.
- Type
bool
- Default
false
Note
This is ignored if there aren't submodules to clone.
Settings for more control over /server-side-search/index
.
version: 2
search:
ranking:
api/v1/*: -1
api/v2/*: 4
ignore:
- 404.html
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:
*
matches everything, including slashes.?
matches any single character.[seq]
matches any character inseq
.
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 config-file/v2: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.
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:
*
matches everything (including slashes).?
matches any single character.[seq]
matches any character inseq
.
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.
You can see the complete schema here. This schema is available at Schema Store, use it with your favorite editor for validation and autocompletion.