The Material Theme
MkDocs ships with a handful of themes, and all of them are plain: mkdocs is a minimal readable layout and readthedocs is a slightly more structured one. Neither is wrong, but neither is what most people picture when they say “documentation site”. Material for MkDocs is the theme that changed that. It is a third-party theme distributed as a Python package, it is the default theme of the widely used container image, and it is what to install first if you have never configured a documentation site by hand.
Installing it is one package, and selecting it is one line of configuration:
python -m pip install mkdocs-material
site_name: My Project
theme:
name: material
That is the minimum. The theme reads the same mkdocs.yml that MkDocs reads, and every option it exposes is optional. What follows is the set of options worth knowing about.
The most distinctive part of Material’s configuration is theme.features, a list of toggles that switch on pieces of the interface. The list is long, and the useful habit is to enable a small number deliberately and look at the result, rather than to copy a long list from a documentation page.
theme:
name: material
features:
- navigation.tabs
- navigation.tabs.sticky
- navigation.sections
- navigation.indexes
- navigation.top
- navigation.footer
- toc.follow
- search.suggest
- search.highlight
- search.share
- content.code.copy
- content.code.annotate
A few of these change the shape of the site rather than adding a detail. navigation.tabs moves the top-level sections into a tab bar, which suits a documentation set with a few large areas and hurts one with many small ones. navigation.sections expands every sidebar section instead of showing only the active branch, which makes a long sidebar easier to scan. navigation.indexes turns a section that contains an index.md into a page you can click in the sidebar rather than a bare label. content.code.copy puts a copy button on every code block, and content.code.annotate enables the annotation syntax described below. search.suggest and search.highlight shape the search dialog, which is the part of a documentation site that readers notice most.
The palette is configured under theme.palette, and it controls both the colour scheme and the toggle that switches between them:
theme:
name: material
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
toggle:
icon: material/brightness-4
name: Switch to light mode
default is the white scheme and slate is the dark one. The primary and accent keys choose the two brand colours used for links, buttons, and highlights, and they accept any of the palette names the theme defines. The media query is optional; if you omit it, the toggle becomes a single button that flips the scheme and remembers the choice, which is the simpler behaviour and often the better one.
Material renders the standard admonition extension as a titled call-out box. The syntax is the Python-Markdown admonition syntax: a line beginning with three exclamation marks and a type, followed by content indented by four spaces.
!!! warning "Read this before upgrading"
Upgrading across two major versions requires
editing the configuration file by hand.
The available types include note, abstract, info, tip, success, question, warning, failure, danger, example, and quote. Giving a title is optional; without one the type name is used. The pymdownx.details extension adds a collapsible variant that starts closed, using the same syntax with ??? in place of !!!.
Tabs are how a single page shows the same idea in several languages or for several tools. The syntax comes from the pymdownx.tabbed extension, and each alternative is a block introduced by a line containing === and the label:
=== "Python"
```python
print("hello")
```
=== "Node.js"
```js
console.log('hello')
```
The active tab is remembered per browser session, so a reader who chooses one language does not have to choose it again on the next page.
Material can attach numbered notes to specific lines of a code block. Enabling content.code.annotate in the feature list turns a comment marker into an annotation:
```yaml
theme:
features:
- content.code.copy # (1)!
```
1. This is an annotation.
The marker is a comment containing the annotation number followed by an exclamation mark, which means the same block still works as valid code in every language where a trailing comment is legal. The numbered list under the block becomes the notes.
When the same fragment appears on several pages, duplicating it is how documentation starts to drift. The pymdownx.snippets extension includes a file by path:
--8<-- "docs/includes/install-command.md"
The path is resolved relative to the project root by default, and the included file is not itself built as a page if you keep it outside the content directory or exclude it.
Mermaid diagrams are supported by adding the pymdownx.mermaid extension to markdown_extensions and then using a fenced block with the mermaid language tag:
```mermaid
graph LR
A[Write] --> B[Build] --> C[Publish]
```
Two mechanisms cover most needs. For styling, point extra_css at your own stylesheet and override the theme’s CSS custom properties, which are the same variables the theme itself uses:
extra_css:
- stylesheets/extra.css
For structure, custom_dir points at a directory of template overrides. Files placed there replace the theme’s template of the same name, so you can change the footer or the announcement bar without forking the theme.
The search plugin is enabled by default and the theme styles its results. The search.suggest and search.highlight features tune the dialog, and a search entry under plugins lets you configure the separator characters and the language the index is built for. The social plugin, installed separately, generates images for sharing a page on social networks, and the git-revision-date-localized plugin adds the last-modified date of each page, formatted in the reader’s time zone rather than the commit author’s.
Material has a paid edition with additional features and a faster support commitment. Everything described here is available in the free, open-source package, which is the one to start with. The paid edition is worth considering only once a team has a specific requirement that the free package does not meet.
Installing the theme and naming it in the configuration is a two-line change, and it is the point at which a MkDocs project stops looking like a scaffold. The feature flags and the palette are where you will spend the next ten minutes, the Markdown extensions are what make the writing experience pleasant, and the two customisation mechanisms mean you rarely need to leave the configuration file. From here, the remaining question is how the site grows, which is what the plugin chapter is about.
