

Getting started

Installation

Set up Material using Docker

The official Docker image for Material comes with all dependencies pre-installed and ready-to-use with the latest version published on PyPI, packaged in a very small image (23MB compressed).

Installing MkDocs

Before installing [MkDocs][2], you need to make sure you have Python and pip – the Python package manager – up and running. You can verify if you're already good to go with the following commands:

Installation on macOS Make sure Brew is installed
brew install pip
this is the recommended approach as opposed to trying to use the built in python

python --version
# Python 2.7.13
pip --version
# pip 9.0.1

Installing and verifying MkDocs is as simple as:

pip install mkdocs && mkdocs --version
# mkdocs, version 0.16.3

Installing Material Components

using pip

Material can be installed with pip:

pip install mkdocs-material-components

Troubleshooting

Installation on macOS

When you're running the pre-installed version of Python on macOS, pip tries to install packages in a folder for which your user might not have the adequate permissions. There are two possible solutions for this:

1. Installing in user space (recommended): Provide the --user flag to the install command and pip will install the package in a user-site location. This is the recommended way.

2. Switching to a homebrewed Python: Upgrade your Python installation to a self-contained solution by installing Python with Homebrew. This should eliminate a lot of problems you may be having with pip.

Error: unrecognized theme 'material'

If you run into this error, the most common reason is that you installed MkDocs through some package manager (e.g. Homebrew or apt-get) and the Material theme through pip, so both packages end up in different locations. MkDocs only checks it's install location for themes.

ImportError: Failed loading extension 'markdown_include.include' from 'markdown_include.include'...

If you run into this error, you just need to install "markdown-include" extension

pip install markdown-include

Usage

In order to enable the theme just add one of the following lines to your project's mkdocs.yml. If you installed Material using pip:

Here is the full yml config used for these docs mkdocs.yml provides a good starting point to get all the good extensions used here

theme: 'material-components'

If you cloned Material from GitHub:

theme_dir: 'mkdocs-material-components/material'

MkDocs includes a development server, so you can review your changes as you go. The development server can be started with the following command:

mkdocs serve

Now you can point your browser to http://localhost:8000 and the Material theme should be visible. From here on, you can start writing your documentation, or read on and customize the theme through some options.

Options

The Material theme adds some extra variables for configuration via your project's mkdocs.yml. See the following sections for all available options.

Changing the color palette

A default hue is defined for every primary and accent color on Google's Material Design color palette, which makes it very easy to change the overall look of the theme. Just set the primary and accent colors using the following variables:

extra:
  palette:
    primary: 'indigo'
    accent: 'light blue'

Color names are case-insensitive, but must match the names of the Material Design color palette. Valid values are: red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey and blue grey. The last three colors can only be used as a primary color.

If the color is set via this configuration, an additional CSS file that defines the color palette is automatically included. If you want to keep things lean, clone the repository and recompile the theme with your custom colors set. See the guide on customization for more information.

Primary colors

Click on a tile to change the primary color of the theme:

Red Pink Purple Deep Purple Indigo Blue Light Blue Cyan Teal Green Light Green Lime Yellow Amber Orange Deep Orange Brown Grey Blue Grey

Accent colors

Click on a tile to change the accent color of the theme:

Red Pink Purple Deep Purple Indigo Blue Light Blue Cyan Teal Green Light Green Lime Yellow Amber Orange Deep Orange

Changing the font family

By default the Roboto font family is included with the theme, specifically the regular sans-serif type for text and the monospaced type for code. Both fonts are loaded from Google Fonts and can be changed to other fonts, like for example the Ubuntu font family:

extra:
  font:
    text: 'Ubuntu'
    code: 'Ubuntu Mono'

The text font will be loaded in weights 400 and 700, the monospaced font in regular weight. If you want to load fonts from other destinations or don't want to use the Google Fonts loading magic, just set font to false:

extra:
  font: false

Adding a source repository

To include a link to the repository of your project within your documentation, set the following variables via your project's mkdocs.yml:

repo_name: 'my-github-handle/my-project'
repo_url: 'https://github.com/my-github-handle/my-project'

The name of the repository will be rendered next to the search bar on big screens and as part of the main navigation drawer on smaller screen sizes. Furthermore, if repo_url points to a GitHub, BitBucket or GitLab repository, the respective service logo will be shown next to the name of the repository. Additionally, for GitHub, the number of stars and forks is shown.

If the repository is hosted in a private environment, the service logo can be set explicitly by setting extra.repo_icon to github, gitlab or bitbucket.

Why is there an edit button at the top of every article?

If the repo_url is set to a GitHub or BitBucket repository, and the repo_name is set to GitHub or BitBucket (implied by default), an edit button will appear at the top of every article. This is the automatic behavior that MkDocs implements. See the MkDocs documentation on more guidance regarding the edit_uri attribute, which defines whether the edit button is shown or not.

Adding a favicon

A favicon can be added by setting the site_favicon variable to an .ico or image file:

site_favicon: 'images/favicon.ico'

Adding a logo

Your logo should have rectangular shape with a minimum resolution of 128x128, leave some room towards the edges and be composed of high contrast areas on a transparent ground, as it will be placed on the colored header bar and drawer. Simply create the folder docs/images, add your logo and embed it with:

extra:
  logo: 'images/logo.svg'

Additionally, the default icon can be changed by setting an arbitrary ligature (or Unicode code point) from the Material Design icon font, e.g.

extra:
  logo:
    icon: 'cloud'

Adding social links

Social accounts can be linked in the footer of the documentation using the automatically included FontAwesome webfont. The type must denote the name of the social service, e.g. github, twitter or linkedin and the link must contain the URL you want to link to:

extra:
  social:
    - type: 'github'
      link: 'https://github.com/squidfunk'
    - type: 'twitter'
      link: 'https://twitter.com/squidfunk'
    - type: 'linkedin'
      link: 'https://linkedin.com/in/squidfunk'

The links are generated in order and the type of the links must match the name of the FontAwesome glyph. The fa is automatically added, so github will result in fa fa-github.

Google Analytics integration

MkDocs makes it easy to integrate site tracking with Google Analytics. Besides basic tracking, clicks on all outgoing links can be tracked as well as how site search is used. Tracking can be activated in your project's mkdocs.yml:

google_analytics:
  - 'UA-XXXXXXXX-X'
  - 'auto'

Disqus integation

Material for MkDocs is integrated with Disqus, so if you want to add a comments section to your documentation set the shortname of your Disqus project in your mkdocs.yml:

extra:
  disqus: 'your-disqus-shortname'

The comments section is inserted in every page, except the index page. Additionally, a new entry at the bottom of the table of contents is generated that is linking to the comments section. The necessary JavaScript is automatically included.

Requirements

site_url value must be set in mkdocs.yml for the Disqus integration to load properly.

Localization

Translations

Material for MkDocs supports internationalization (i18n). In order to translate the labels (e.g. Previous and Next in the footer), you can override the file partials/language.html and provide your own translations inside the macro t:

{% macro t(key) %}{{ {
  "language": "en",
  "edit.link.title": "Edit this page",
  "footer.previous": "Previous",
  "footer.next": "Next",
  "meta.comments": "Comments",
  "meta.source": "Source",
  "search.languages": "",
  "search.placeholder": "Search",
  "search.result.placeholder": "Type to start searching",
  "search.result.none": "No matching documents",
  "search.result.one": "1 matching document",
  "search.result.other": "# matching documents",
  "search.tokenizer": "[\s\-]+",
  "source.link.title": "Go to repository",
  "toc.title": "Table of contents"
}[key] }}{% endmacro %}

Just copy the file from the original theme and make your adjustments. See the section on overriding partials and the general guide on theme extension in the customization guide. Furthermore, see the example configuration for a head start.

Site search

Site search is implemented using lunr.js, which includes stemmers for the English language by default, while stemmers for other languages are included with lunr-languages, both of which are integrated with this theme. Support for other languages and even multilingual search can be activated by setting the key search.languages to a comma-separated list of supported 2-letter language codes, e.g.:

{% macro t(key) %}{{ {
  ...
  "search.languages": "en, de, ru",
  ...
}[key] }}{% endmacro %}

This will automatically load the stemmers for the specified languages and set them up with site search, nothing else to be done.

At the time of writing, the following languages are supported: English en, French fr, Spanish es, Italian it, Japanese jp, Dutch du, Danish da, Portguese pt, Finnish fi, Romanian ro, Hungarian hu, Russian ru, Norwegian no, Swedish sv and Turkish tr.

Only specify the languages you really need

Be aware that including suppport for other languages increases the general JavaScript payload by around 20kb (without gzip) and by another 15-30kb per language.

The separator for tokenization can also be customized, which makes it possible to index parts of words that are separated by - or . for example:

{% macro t(key) %}{{ {
  ...
  "search.tokenizer": "[\s\-\.]+",
  ...
}[key] }}{% endmacro %}

Tabs

From version 1.1.0 on, Material supports another layer on top of the main navigation for larger screens in the form of tabs. This is especially useful for larger documentation projects with only few top-level sections. Tabs can be enabled by setting the respective feature flag to true:

extra:
  feature:
    tabs: true

More advanced customization

If you want to change the general appearance of the Material theme, see this article for more information on advanced customization.

Extensions

MkDocs supports several Markdown extensions. The following extensions are not enabled by default (see the link for which are enabled by default) but highly recommended, so they should be switched on at all times:

markdown_extensions:
  - admonition
  - codehilite(guess_lang=false)
  - toc(permalink=true)

For more information, see the following list of extensions supported by the Material theme including more information regarding installation and usage:

• Admonition
• Codehilite
• Footnotes
• Metadata
• Permalinks
• PyMdown Extensions

Full example

Below is a full example configuration for a mkdocs.yml:

# Project information
site_name: 'My Project'
site_description: 'A short description of my project'
site_author: 'John Doe'
site_url: 'https://john-doe.github.io/my-project'

# Repository
repo_name: 'my-github-handle/my-project'
repo_url: 'https://github.com/john-doe/my-project'

# Copyright
copyright: 'Copyright © 2016 - 2017 John Doe'

# Documentation and theme
theme: 'material'

# Options
extra:
  logo: 'images/logo.svg'
  palette:
    primary: 'indigo'
    accent: 'indigo'
  font:
    text: 'Roboto'
    code: 'Roboto Mono'
  social:
    - type: 'github'
      link: 'https://github.com/john-doe'
    - type: 'twitter'
      link: 'https://twitter.com/john-doe'
    - type: 'linkedin'
      link: 'https://linkedin.com/in/john-doe'

# Google Analytics
google_analytics:
  - 'UA-XXXXXXXX-X'
  - 'auto'

# Extensions
markdown_extensions:
  - admonition
  - codehilite(guess_lang=false)
  - toc(permalink=true)