Getting started¶

Installation¶

While there are several ways of installing Material for MkDocs, the recommended methods are either by using pip – the Python package manager – or by pulling the official Docker image.

with pip recommended¶

Material for MkDocs can be installed with pip:

pip install mkdocs-material

Note that this will automatically install compatible versions of MkDocs, Markdown, Pygments and PyMdown Extensions. Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately.

Installation in a virtual environment

The best way to make sure that you end up with the correct versions and without any incompatibility problems between packages it to use a virtual environment. Don't know what this is or how to set it up? We recommend to start by reading a tutorial on virtual environments for Python.

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:

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.
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 could 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 Material for MkDocs through pip, so both packages end up in different locations. MkDocs only checks its install location for themes.

with docker recommended¶

The official Docker image is a great way to get up and running in a few minutes, as it comes with all dependencies pre-installed. Pull the image for the latest version with:

docker pull squidfunk/mkdocs-material

The mkdocs executable is provided as an entry point and serve is the default command. Start the development server in your project root – the folder where mkdocs.yml resides — with:

Unix

docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

Windows

docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material

with git¶

Material for MkDocs can be directly used from GitHub by cloning the repository into a subfolder of your project root which might be useful if you want to use the very latest version:

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

The theme will reside in the folder mkdocs-material/material.

Configuration¶

Depending on your installation method, you can now add the following lines to mkdocs.yml in your project root. If you installed Material for MkDocs using a package manager, add:

theme:
  name: material

If you cloned Material for MkDocs from GitHub add:

theme:
  name: null
  custom_dir: mkdocs-material/material

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

mkdocs serve

Point your browser to http://localhost:8000 and your documentation should greet you in a new look. If you're starting from scratch, the following configuration can be used as a starting point:

Example configuration

This is an excerpt from the mkdocs.yml used to render these pages:

# Project information
site_name: Material for MkDocs
site_description: A Material Design theme for MkDocs
site_author: Martin Donath
site_url: https://squidfunk.github.io/mkdocs-material/

# Repository
repo_name: squidfunk/mkdocs-material
repo_url: https://github.com/squidfunk/mkdocs-material

# Copyright
copyright: Copyright &copy; 2016 - 2020 Martin Donath

# Configuration
theme:
  name: material
  language: en
  palette:
    primary: indigo
    accent: indigo
  font:
    text: Roboto
    code: Roboto Mono

# Extras
extra:
  social:
    - icon: fontawesome/brands/github-alt
      link: https://github.com/squidfunk
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/squidfunk
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/squidfunk

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

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

Feature flags¶

These optional features are hidden behind flags and can be explicitly enabled in mkdocs.yml.

Instant loading ¶

The (still experimental) instant loading feature will intercept clicks on all internal links and dispatch them directly via XHR without a full page reload. It can be enabled from mkdocs.yml with:

theme:
  features:
    - instant

The resulting page is parsed and injected and all event handlers and components are automatically rebound. This means that Material for MkDocs behaves like a Single Page Application, which is especially useful for large documentation sites that come with a huge search index, as the search index will now remain intact in-between document switches.

Tabs¶

The tabs feature will render top-level subsections in another navigational layer below the header on big screens (but leave them untouched on mobile). It can be enabled from mkdocs.yml with:

theme:
  features:
    - tabs

Note that all top-level pages (i.e. all top-level entries that directly refer to an *.md file) defined inside the nav entry of mkdocs.yml will be grouped under the first tab which will receive the title of the first page.

This means that there will effectively be no collapsible subsections for the first tab, as each subsection is rendered as another tab. If you want more fine-grained control, i.e., collapsible subsections for the first tab, you can move all top-level pages into a subsection, so that the top-level is entirely made up of subsections. Note that tabs are only shown for larger screens, so make sure that navigation is plausible on mobile devices.

As an example, see the mkdocs.yml used to render these pages.

Language¶

Default: en

Material for MkDocs supports internationalization (i18n) and provides translations for all template variables and labels. You can set the language from mkdocs.yml with:

theme:
  language: en

The following language codes are supported:

While many languages are read ltr (left-to-right), Material for MkDocs also supports rtl (right-to-left) directionality which is inferred from the selected language, but can also be set with:

theme:
  direction: rtl

Color palette¶

The Material Design color palette comes with 20 hues, all of which are included with Material for MkDocs. Primary and accent colors can be set from the project root's mkdocs.yml:

theme:
  palette:
    primary: indigo
    accent: indigo

If the colors are set with these configuration options, an additional CSS file that includes the hues of the color palette is automatically included and linked from the template.

Custom colors with CSS variables

Material for MkDocs defines all colors as CSS variables. If you want to customize the colors beyond the palette (e.g. to use your brand's colors), you can add an additional stylesheet and override the defaults:

:root {

  /* Default color shades */
  --md-default-fg-color:               ...;
  --md-default-fg-color--light:        ...;
  --md-default-fg-color--lighter:      ...;
  --md-default-fg-color--lightest:     ...;
  --md-default-bg-color:               ...;
  --md-default-bg-color--light:        ...;
  --md-default-bg-color--lighter:      ...;
  --md-default-bg-color--lightest:     ...;

  /* Primary color shades */
  --md-primary-fg-color:               ...;
  --md-primary-fg-color--light:        ...;
  --md-primary-fg-color--dark:         ...;
  --md-primary-bg-color:               ...;
  --md-primary-bg-color--light:        ...;

  /* Accent color shades */
  --md-accent-fg-color:                ...;
  --md-accent-fg-color--transparent:   ...;
  --md-accent-bg-color:                ...;
  --md-accent-bg-color--light:         ...;

  /* Code block color shades */
  --md-code-bg-color:                  ...;
  --md-code-fg-color:                  ...;
}

Primary color¶

Default: indigo

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

Accent color¶

Default: indigo

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

Fonts¶

Default: Roboto and Roboto Mono

The Roboto font family is the default font 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 any valid webfont, like for example the Ubuntu font family:

theme:
  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 Google Fonts for data privacy reasons, just set font to false:

theme:
  font: false

Icons¶

Default: material/library and fontawesome/brands/git-alt

Material for MkDocs uses icons in several places. Currently, the following icons can be changed from mkdocs.yml: the logo icon, the repository icon and the social link icons. While the social link icons are tied to the respective entries, the other icons can be changed by referencing a valid path (without the trailing .svg) relative to the .icons folder which comes with the theme:

theme:
  icon:
    logo: material/library
    repo: fontawesome/brands/git-alt

All icons are directly inlined as *.svg files, so no further requests will be made. Icon sets which are bundled with Material for MkDocs:

Material Design icons (material): 3.8k icons
FontAwesome icons (fontawesome): 1.5k icons
GitHub's Octicons (octicons): 200 icons

You can use all those icons directly from Markdown!

Logo¶

Default: icon set through theme.icon.logo

If you want to replace the icon in the header (screen) and drawer (mobile) with your brand's logo, you can place an image file in your docs folder and use the following option in mkdocs.yml:

theme:
  logo: images/logo.svg

Ideally, the image should be a square with a minimum resolution of 96x96, 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 and drawer.

Favicon¶

Default: assets/images/favicon.png

The default favicon can be changed with:

theme:
  favicon: images/favicon.png

Extras¶

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: squidfunk/mkdocs-material
repo_url: https://github.com/squidfunk/mkdocs-material

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. Additionally, for GitHub and GitLab, the number of stars and forks is shown. Note that the repository icon can be explicitly set through theme.icon.repo.

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.

Social accounts can be linked in the footer of the documentation using the icons which are bundled with the theme. Note that each icon must point to a valid path (without the trailing .svg) relative to the .icons folder which comes with the theme:

extra:
  social:
    - icon: fontawesome/brands/github-alt
      link: https://github.com/squidfunk
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/squidfunk
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/squidfunk

Adding a Web App Manifest¶

A Web App Manifest is a simple JSON file that tells the browser about your web application and how it should behave when installed on the user's mobile device or desktop. You can specify such a manifest in mkdocs.yml:

extra:
  manifest: manifest.webmanifest

Integrations¶

Google Analytics¶

MkDocs makes it easy to integrate site tracking with Google Analytics. To enable tracking, which is disabled by default, you must add your tracking identifier to mkdocs.yml:

google_analytics:
  - UA-XXXXXXXX-X
  - auto

Besides basic page views, site search can also be tracked to better understand how people use your documentation and what they expect to find. To enable search tracking:

Go to your Google Analytics admin settings
Select the property for the respective tracking code
Go to the view settings tab.
Scroll down and enable site search settings
Set the query parameter to q.

Disqus¶

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 mkdocs.yml:

extra:
  disqus: your-shortname

The comments section is inserted on every page, except the index page. The necessary JavaScript is automatically included.

Requirements

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

Disqus can also be enabled or disabled for specific pages using Metadata.

Extensions¶

Markdown comes with several very useful extensions, the following of which are not enabled by default but highly recommended, so enabling them should definitely be a good idea:

markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
  - toc:
      permalink: true

See the following list of extensions supported by Material for MkDocs including some more information on configuration and usage:

Plugins¶

MkDocs' plugin architecture makes it possible to add pre- or post-processing steps that sit between the theme and your documentation. For more information, see the following list of plugins tested and supported by Material for MkDocs including more information regarding installation and usage:

For further reference, the MkDocs wiki contains a list of all available plugins.