Getting started
Installation
Installing MkDocs
Before installing MkDocs, 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:
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.17.1
Material requires MkDocs >= 0.17.1.
Installing Material
using pip
Material can be installed with pip
:
pip install mkdocs-material
using choco
If you're on Windows you can use Chocolatey to install Material:
choco install mkdocs-material
This will install all required dependencies like Python and MkDocs.
cloning from GitHub
Material can also be used without a system-wide installation by cloning the repository into a subfolder of your project's root directory:
git clone https://github.com/squidfunk/mkdocs-material.git
This is especially useful if you want to extend the theme and
override some parts of the theme. The theme will reside in the folder
mkdocs-material/material
.
Troubleshooting
!!! warning "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`.
!!! failure "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 its install location for themes.
Alternative: Using Docker
If you're familiar with 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. Pull it with:
docker pull squidfunk/mkdocs-material
The mkdocs
executable is provided as an entrypoint, serve
is the default
command. Start the development server in your project root with:
docker run --rm -it -p 8000:8000 -v `pwd`:/docs squidfunk/mkdocs-material
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:
theme:
name: 'material'
If you cloned Material from GitHub:
theme:
name: null
custom_dir: 'mkdocs-material/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][9] and the Material theme should be visible. From here on, you can start writing your documentation, or read on and customize the theme.
Configuration
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:
theme:
palette:
primary: 'indigo'
accent: 'indigo'
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
, blue grey
and
white
. The four 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
Default:
indigo
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 White
Accent colors
Default:
indigo
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
Font family
Default:
Roboto
andRoboto Mono
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:
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 the Google Fonts loading magic, just set font
to false
:
theme:
font: false
Logo
Default icon:
school