mkdocs-material/docs/customization.md

template
overrides/main.html

Customization

Project documentation is as diverse as the projects themselves and Material for MkDocs is a great starting point for making it look beautiful. However, as you write your documentation, you may reach a point where small adjustments are necessary to preserve your brand's style.

Adding assets

MkDocs provides several ways to customize a theme. In order to make a few tweaks to Material for MkDocs, you can just add your stylesheets and JavaScript files to the docs directory.

Additional CSS

If you want to tweak some colors or change the spacing of certain elements, you can do this in a separate stylesheet. The easiest way is by creating a new stylesheet file in the docs directory:

.
├─ docs/
│  └─ stylesheets/
│     └─ extra.css
└─ mkdocs.yml

Then, add the following line to mkdocs.yml:

extra_css:
  - stylesheets/extra.css

Spin up the live preview server and start typing your changes in your additional stylesheet file – you should see them almost instantly after saving.

Additional JavaScript

The same is true for additional JavaScript. If you want to integrate another syntax highlighter or add some custom logic to your theme, create a new JavaScript file in the docs directory:

.
├─ docs/
│  └─ javascripts/
│     └─ extra.js
└─ mkdocs.yml

Then, add the following line to mkdocs.yml:

extra_javascript:
  - javascripts/extra.js

Further assistance can be found in the MkDocs documentation.

Extending the theme

If you want to alter the HTML source (e.g. add or remove some parts), you can extend the theme. MkDocs supports theme extension, an easy way to override parts of Material for MkDocs without forking from git. This ensures that you can update to the latest version more easily.

Setup and theme structure

Enable Material for MkDocs as usual in mkdocs.yml, and create a new folder for overrides which you then reference using the custom_dir key:

theme:
  name: material
  custom_dir: overrides

!!! warning "Theme extension prerequisites"

As the `custom_dir` variable is used for the theme extension process,
Material for MkDocs needs to be installed via `pip` and referenced with the
`name` parameter in `mkdocs.yml`. It will not work when cloning from `git`.

The structure in the overrides directory must mirror the directory structure of the original theme, as any file in the overrides directory will replace the file with the same name which is part of the original theme. Besides, further assets may also be put in the overrides directory.

The directory layout of the theme is as follows:

.
├─ .icons/                             # Bundled icon sets
├─ assets/
│  ├─ images/                          # Images and icons
│  ├─ javascripts/                     # JavaScript
│  └─ stylesheets/                     # Stylesheets
├─ partials/
│  ├─ integrations/                    # Third-party integrations
│  │  ├─ analytics.html                # - Google Analytics
│  │  └─ disqus.html                   # - Disqus
│  ├─ languages/                       # Localized languages
│  ├─ footer.html                      # Footer bar
│  ├─ header.html                      # Header bar
│  ├─ language.html                    # Localized labels
│  ├─ logo.html                        # Logo in header and sidebar
│  ├─ nav.html                         # Main navigation
│  ├─ nav-item.html                    # Main navigation item
│  ├─ palette.html                     # Color palette
│  ├─ search.html                      # Search box
│  ├─ social.html                      # Social links
│  ├─ source.html                      # Repository information
│  ├─ source-date.html                 # Last updated date
│  ├─ source-link.html                 # Link to source file
│  ├─ tabs.html                        # Tabs navigation
│  ├─ tabs-item.html                   # Tabs navigation item
│  ├─ toc.html                         # Table of contents
│  └─ toc-item.html                    # Table of contents item
├─ 404.html                            # 404 error page
├─ base.html                           # Base template
└─ main.html                           # Default page

Overriding partials

In order to override a partial, we can replace it with a file of the same name and location in the overrides directory. For example, to replace the original footer.html, create a footer.html file in the overrides/partials directory:

.
├─ overrides/
│  └─ partials/
│     └─ footer.html
└─ mkdocs.yml

MkDocs will now use the new partial when rendering the theme. This can be done with any file.

Overriding blocks

Besides overriding partials, it's also possible to override (and extend) template blocks, which are defined inside the templates and wrap specific features. To override a block, create a main.html file inside the overrides directory:

.
├─ overrides/
│  └─ main.html
└─ mkdocs.yml

Then, e.g. to override the site title, add the following line to main.html:

{% extends "base.html" %}

{% block htmltitle %}
  <title>Lorem ipsum dolor sit amet</title>
{% endblock %}

Material for MkDocs provides the following template blocks:

Block name	Wrapped contents
analytics	Wraps the Google Analytics integration
announce	Wraps the announcement bar
config	Wraps the JavaScript application config
content	Wraps the main content
disqus	Wraps the Disqus integration
extrahead	Empty block to add custom meta tags
fonts	Wraps the font definitions
footer	Wraps the footer with navigation and copyright
header	Wraps the fixed header bar
hero	Wraps the hero teaser (if available)
htmltitle	Wraps the <title> tag
libs	Wraps the JavaScript libraries (header)
scripts	Wraps the JavaScript application (footer)
source	Wraps the linked source files
site_meta	Wraps the meta tags in the document head
site_nav	Wraps the site navigation and table of contents
styles	Wraps the stylesheets (also extra sources)
tabs	Wraps the tabs navigation (if available)

For more on this topic refer to the MkDocs documentation.

Theme development

Material for MkDocs uses ESBuild as a build tool to leverage modern web technologies like TypeScript and SASS. If you want to make more fundamental changes, it may be necessary to make the adjustments directly in the source of the theme and recompile it.

Environment setup

In order to start development on Material for MkDocs, a Node.js version of at least 12 is required. First, clone the repository:

git clone https://github.com/squidfunk/mkdocs-material

Next, all dependencies need to be installed, which is done with:

cd mkdocs-material
pip install -r requirements.txt
pip install mkdocs-minify-plugin
pip install mkdocs-redirects
npm install

Development mode

Start the watcher with:

npm start

Then, in a second session, start the MkDocs server with:

mkdocs serve

Point your browser to localhost:8000 and you should see this documentation in front of you.

!!! warning "Automatically generated files"

Never make any changes in the `material` directory, as the contents of this
directory are automatically generated from the `src` directory and will be
overridden when the theme is built.

Building the theme

When you're finished making your changes, you can build the theme by invoking:

npm run build

This triggers the production-level compilation and minification of all stylesheets and JavaScript sources. When the command exits, the final files are located in the material directory. Add the theme_dir variable pointing to the aforementioned directory in the original mkdocs.yml.

Now you can run mkdocs build and you should see your documentation with your changes to the original theme.