Deploying MkDocs on Read the Docs

MkDocs is a fast, simple static site generator that’s geared towards building project documentation.MkDocs is written in Python, and supports documentation written in Markdown.When using MkDocs, we recommend using theMaterial for MkDocs theme,and this guide is mostly focused on the integration required to make it work well on Read the Docs.

Minimal configuration is required to build an existing MkDocs project on Read the Docs:

.readthedocs.yaml
version:2build:os:"ubuntu-24.04"tools:python:"3"# We recommend using a requirements file for reproducible builds.# This is just a quick example to get started.# https://docs.readthedocs.io/page/guides/reproducible-builds.htmljobs:pre_install:-pip install mkdocs-materialmkdocs:configuration:mkdocs.yml

Configuring Material for MkDocs on Read the Docs

In order to use the Material for MkDocs theme on Read the Docs,you need to install and configure it.In yourmkdocs.yml file, set the theme tomaterial:

mkdocs.yml
theme:name:material

With these changes, your MkDocs project will use the Material for MkDocs theme when built on Read the Docs,and should work with the configuration file shown above.

Quick start

Configuring MkDocs and Read the Docs Addons

There are some additional steps you can take to configure your MkDocs project to work better with Read the Docs,and these apply to all MkDocs projects.

Set the canonical URL

Acanonical URL allows you to specify the preferred version of a web pageto prevent duplicated content.

Set your MkDocssite URL to your Read the Docs canonical URL using aRead the Docs environment variable:

mkdocs.yml
site_url:!ENVREADTHEDOCS_CANONICAL_URL

Configuring Material for MkDocs and Read the Docs Addons

Material for MkDocs is a powerful documentation theme on top of MkDocs.The following steps are specific to integrating Material for MkDocs and Read the Docs.

Configure Read the Docs search

To configure your site to useRead the Docs search instead of the default search:

  1. Add the following block of #"#id4" title="Link to this code">

document.addEventListener("DOMContentLoaded",function(event){// Trigger Read the Docs' search addon instead of Material MkDocs defaultdocument.querySelector(".md-search__input").addEventListener("focus",(e)=>{constevent=newCustomEvent("readthedocs-search-show");document.dispatchEvent(event);});});