Skip to content

# Customize a theme

You can customize an existing theme by overriding blocks or partials. You might want to do this because your theme is not natively supported, or you would like more control on the formatting. Below are some examples to help get you started.

## Example: default `mkdocs` theme

To add a revision date to the default `mkdocs` theme, add a `overrides/partials` folder to your `docs` folder and update your `mkdocs.yml` file. Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides/content.html`:

mkdocs.yml
docs/overrides/content.html

    theme:
        name: mkdocs
        custom_dir: docs/overrides

    <!-- Overwrites content.html base mkdocs theme, taken from
    https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/mkdocs/content.html -->

    {% if page.meta.source %}
        <div class="source-links">
        {% for filename in page.meta.source %}
            <span class="label label-primary">{{ filename }}</span>
        {% endfor %}
        </div>
    {% endif %}

    {{ page.content }}

    <!-- This section adds support for localized revision dates -->
    {% if page and page.meta.git_revision_date_localized %}
        <small>Last update: {{ page.meta.git_revision_date_localized }}</small>
    {% endif %}
    {% if page and page.meta.git_created_date_localized %}
        <small>Created: {{ page.meta.git_created_date_localized }}</small>
    {% endif %}

## Example: `mkdocs-material` theme

mkdocs-material has built-in support for `git_revision_date_localized` and `git_created_date_localized`. You can see that when viewing their `source-file.html` partial.

If you want, you can customize further by extending the mkdocs-material theme and overriding the `source-file.html` partial as follows:

mkdocs.yml
docs/overrides/partials/source-file.html

    theme:
        name: 'material'
        custom_dir: docs/overrides

    {% import "partials/language.html" as lang with context %}

    <!-- taken from
    https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-file.html -->

    <hr />
    <div class="md-source-file">
    <small>

        <!-- mkdocs-git-revision-date-localized-plugin -->
        {% if page.meta.git_revision_date_localized %}
        {{ lang.t("source.file.date.updated") }}:
        {{ page.meta.git_revision_date_localized }}
        {% if page.meta.git_creation_date_localized %}
            <br />
            {{ lang.t("source.file.date.created") }}:
            {{ page.meta.git_creation_date_localized }}
        {% endif %}

        <!-- mkdocs-git-revision-date-plugin -->
        {% elif page.meta.revision_date %}
        {{ lang.t("source.file.date.updated") }}:
        {{ page.meta.revision_date }}
        {% endif %}
    </small>
    </div>

mkdocs-material also supports custom translations that you can use to specify alternative translations for `source.file.date.updated` ("Last updated") and `source.file.date.created` ("Created").

## Example: List last updated pages

Let's say we want to insert a list of the last 10 updated pages into our home page.

We can use the mkdocs template variables together with jinja2 filters to extend the mkdocs-material theme. @simbo provided this example that overrides `main.html`:

mkdocs.yml
docs/overrides/main.html

    theme:
        name: 'material'
        custom_dir: docs/overrides

    {% extends "base.html" %}
    {% block site_nav %}
    {{ super() }}
    {% if page and page.file and page.file.src_path == "index.md" %}
        <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="navigation">
        <div class="md-sidebar__scrollwrap">
            <div class="md-sidebar__inner">
            <nav class="md-nav md-nav--secondary md-nav--integrated" aria-label="Recently updated" data-md-level="0">
                <div class="md-nav__title">Recently updated</div>
                <ul class="md-nav__list" data-md-scrollfix>
                {% for file in (
                    pages
                    | selectattr("page.meta.git_revision_date_localized_raw_iso_datetime")
                    | selectattr("page.meta.git_creation_date_localized_raw_iso_datetime")
                    | sort(attribute="page.title")
                    | sort(attribute="page.meta.git_creation_date_localized_raw_iso_datetime", reverse=true)
                    | sort(attribute="page.meta.git_revision_date_localized_raw_iso_datetime", reverse=true)
                    )[:10]
                %}
                    <li class="md-nav__item">
                    <a class="md-nav__link" href="{{ file.url }}" style="display:block">
                        {{ file.page.title }}
                        <br/>
                        <small>
                        <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-timeago">
                            <span class="timeago" datetime="{{ file.page.meta.git_revision_date_localized_raw_iso_datetime }}" locale="en"></span>
                        </span>
                        </small>
                    </a>
                    </li>
                {% endfor %}
                </ul>
            </nav>
            </div>
        </div>
        </div>
    {% endif %}
    {% endblock %}

## Example: Populate `sitemap.xml`

Having a correct lastmod in your `sitemap.xml` is important for SEO, as it indicates to Search engines when to re-index pages, see this blog from Bing.

`@thesuperzapper` shared this override in mkdocs-git-revision-date-localized-plugin#120:

    <?xml version="1.0" encoding="UTF-8"?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    {%- for file in pages -%}
        {% if not file.page.is_link and (file.page.abs_url or file.page.canonical_url) %}
        <url>
            <loc>{% if file.page.canonical_url %}{{ file.page.canonical_url|e }}{% else %}{{ file.page.abs_url|e }}{% endif %}</loc>
            {#- NOTE: we exclude `lastmod` for pages using a template, as their update time is not correctly detected #}
            {%- if not file.page.meta.template and file.page.meta.git_revision_date_localized_raw_iso_datetime %}
            <lastmod>{{ (file.page.meta.git_revision_date_localized_raw_iso_datetime + "+00:00") | replace(" ", "T") }}</lastmod>
            {%- endif %}
            <changefreq>daily</changefreq>
            {#- NOTE: You can add a priority to the front matter (meta) for a page. #}
            {#- Valid values range from 0.0 to 1.0, if no value is set the default is 0.5. #}
            {#- reference: https://www.sitemaps.org/protocol.html #}
            {%- if file.page.meta.priority %}
            <priority>{{ file.page.meta.priority }}</priority>
            {%- endif %}
        </url>
        {%- endif -%}
    {% endfor %}
    </urlset>