MkDocs

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 the Material 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: 2

 build:
   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.html
   jobs:
     pre_install:
       - pip install mkdocs-material

 mkdocs:
   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 your mkdocs.yml file, set the theme to material:

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

You can use our MkDocs example project as a reference to create a new MkDocs project.
If you have an existing MkDocs project you want to host on Read the Docs, check out our Adding a documentation project guide.
If you’re new to MkDocs, check out the official Getting Started guide.

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

A canonical URL allows you to specify the preferred version of a web page to prevent duplicated content.

Set your MkDocs site URL to your Read the Docs canonical URL using a Read the Docs environment variable:

mkdocs.yml

site_url: !ENV READTHEDOCS_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 use Read the Docs search instead of the default search:

Add the following block of JavaScript:

javascript/readthedocs.js

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

Include javascript/readthedocs.js in your MkDocs configuration:
mkdocs.yml
extra_javascript: - javascript/readthedocs.js

Integrate the Read the Docs version menu into your site navigation

To integrate the Addons flyout menu version menu into your site navigation:

Override the main.html template to include the data in the meta attribute:

overrides/main.html

{% extends "base.html" %}

{% block site_meta %}
{{ super() }}
<meta name="readthedocs-addons-api-version" content="1" />
{% endblock %}

Parse the version data into a dropdown menu using JS in javascript/readthedocs.js: