Skip to content

Latest commit

 

History

History
155 lines (110 loc) · 5.08 KB

mkdocs.rst

File metadata and controls

155 lines (110 loc) · 5.08 KB

Material for MkDocs on Read the Docs

MkDocs is a fast, simple static site generator that's geared towards building project documentation. Material for MkDocs is a powerful documentation framework on top of MkDocs.

Note

This page is explicitly about Material for MkDocs. We're working on a guide for plain MkDocs as well.

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3"
  # Since Read the Docs manipulates that `mkdocs.yml` and it does not support `!ENV`,
  # we use `build.commands` here because we need `!ENV` in our `mkdocs.yml`.
  #
  commands:
    # Install Material for MkDocs Insiders
    # https://squidfunk.github.io/mkdocs-material/insiders/getting-started/
    #
    # Create GH_TOKEN environment variable on Read the Docs
    # https://docs.readthedocs.io/en/stable/guides/private-python-packages.html
    - pip install mkdocs-material
    - mkdocs build --site-dir $READTHEDOCS_OUTPUT/html

Quick start

Configuring Material for MkDocs and Read the Docs addons

To get the best integration with Read the Docs, you need to make the following configuration changes to your Material for MkDocs config:

  1. Set the site URL using a :doc:`Read the Docs environment variable </reference/environment-variables>`:

    site_url: !ENV READTHEDOCS_CANONICAL_URL

  2. Configure search to use Read the Docs search instead of the default search:

    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);
    });
});

  3. Include javascript/readthedocs.js in the MkDocs build:

    extra_javascript:
    - javascript/readthedocs.js

Integrating the Read the Docs version menu into your site navigation

To integrate the version menu into your site navigation

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

    {% extends "base.html" %}

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

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

    // Use CustomEvent to generate the version selector
document.addEventListener(
        "readthedocs-addons-data-ready",
        function (event) {
        const config = event.detail.data();
        const versioning = `
<div class="md-version">
<button class="md-version__current" aria-label="Select version">
    ${config.versions.current.slug}
</button>

<ul class="md-version__list">
${ config.versions.active.map(
    (version) => `
    <li class="md-version__item">
    <a href="${ version.urls.documentation }" class="md-version__link">
        ${ version.slug }
    </a>
            </li>`).join("\n")}
</ul>
</div>`;

    document.querySelector(".md-header__topic").insertAdjacentHTML("beforeend", versioning);
});

  3. Make sure that javascript/readthedocs.js is included in the MkDocs build:

    extra_javascript:
    - javascript/readthedocs.js

Example repo and demo

Example repo::
https://github.com/readthedocs/test-builds/tree/mkdocs-material
Demo::
https://test-builds.readthedocs.io/en/mkdocs-material/

Further reading