Configuration file tutorial
As part of the initial set up for your Read the Docs site,
you need to create a configuration file called
The configuration file tells Read the Docs what specific settings to use for your project.
This tutorial covers:
Where to put your configuration file.
What to put in the configuration file.
How to customize the configuration for your project.
- Read the Docs tutorial.
Following the steps in our tutorial will help you setup your first documentation project.
Where to put your configuration file
.readthedocs.yaml file should be placed in the top-most directory of your project’s repository.
We will get to the contents of the file in the next steps.
When you have changed the configuration file, you need to commit and push the changes to your Git repository. Read the Docs will then automatically find and use the configuration to build your project.
Getting started with a template
Here are some configuration file examples to help you get started.
Pick an example based on the tool that your project is using,
copy its contents to
.readthedocs.yaml and add the file to your Git repository.
If your project uses Sphinx, we offer a special builder optimized for Sphinx projects.
1# Read the Docs configuration file for Sphinx projects 2# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 3 4# Required 5version: 2 6 7# Set the OS, Python version and other tools you might need 8build: 9 os: ubuntu-22.04 10 tools: 11 python: "3.11" 12 # You can also specify other tool versions: 13 # nodejs: "20" 14 # rust: "1.70" 15 # golang: "1.20" 16 17# Build documentation in the "docs/" directory with Sphinx 18sphinx: 19 configuration: docs/conf.py 20 # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs 21 # builder: "dirhtml" 22 # Fail on all warnings to avoid broken references 23 # fail_on_warning: true 24 25# Optionally build your docs in additional formats such as PDF and ePub 26# formats: 27# - pdf 28# - epub 29 30# Optional but recommended, declare the Python requirements required 31# to build your documentation 32# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html 33# python: 34# install: 35# - requirements: docs/requirements.txt
If your project uses MkDocs, we offer a special builder optimized for MkDocs projects.
1# Read the Docs configuration file for MkDocs projects 2# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details 3 4# Required 5version: 2 6 7# Set the version of Python and other tools you might need 8build: 9 os: ubuntu-22.04 10 tools: 11 python: "3.11" 12 13mkdocs: 14 configuration: mkdocs.yml 15 16# Optionally declare the Python requirements required to build your docs 17python: 18 install: 19 - requirements: docs/requirements.txt
Editing the template
Now that you have a
.readthedocs.yaml file added to your Git repository,
you should see Read the Docs trying to build your project with the configuration file.
The configuration file probably needs some adjustments to accommodate exactly your project setup.
If you added the configuration file in a separate branch, you may have to activate a version for that branch.
If you have added the file in a pull request, you should enable pull request builds.
Skip: file header and comments
There are some parts of the templates that you can leave in place:
We added comments that explain the configuration options and optional features. These lines begin with a
- Commented out features
We use the
#in front of some popular configuration options. They are there as examples, which you can choose to enable, delete or save for later.
The version key tells the system how to read the rest of the configuration file. The current and only supported version is version 2.
In our examples, we are using Read the Docs’ custom image based on the latest Ubuntu release. Package versions in these images will not change drastically, though will receive periodic security updates.
You should pay attention to this field if your project needs to build on an older version of Ubuntu, or in the future when you need features from a newer Ubuntu.
Configuration file reference with all values possible for
Adjust: Python configuration
If you are using Python in your builds,
you should define the Python version in
python key contains a list of sub-keys,
specifying the requirements to install.
python.install.packageto install the project itself as a Python package using pip
python.install.requirementsto install packages from a requirements file
build.jobsto install packages using Poetry or PDM
Adjust: Sphinx and MkDocs version
If you are using either the
then Sphinx or MkDocs will be installed automatically in its latest version.
But we recommend that you specify the version that your documentation project uses.
requirements key is a file path that points to a text (
that lists the Python packages you want Read the Docs to install.
There are more configuration options that the ones mentioned in this guide.
After you add a configuration file your Git repository, and you can see that Read the Docs is building your documentation using the file, you should have a look at the complete configuration file reference for options that might apply to your project.
- Configuration file v2 (.readthedocs.yaml).
The complete list of all possible
.readthedocs.yamlsettings, including the optional settings not covered in on this page.
- Build process customization
Are familiar with running a command line? Perhaps there are special commands that you know you want Read the Docs to run. Read this guide and learn more about how you add your own commands to