mkdocs-material/docs/getting-started.md

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.16.0

!!! warning "MkDocs for Material requirements"

Material requires MkDocs >= 0.16.

Furthermore, it is highly recommended to install Pygments and the PyMdown Extensions to get the most out of the Material theme:

pip install pygments
pip install pymdown-extensions

Installing Material

using pip

Material can be installed with pip:

pip install mkdocs-material

!!! 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 to 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`.

using choco

If you're on Windows you can use Chocolatey to install Material:

choco install mkdocs-material

This will also 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.

Usage

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

theme: 'material'

If you cloned Material from GitHub:

theme_dir: 'mkdocs-material/material'

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

mkdocs serve

Now you can point your browser to 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 section for all available options.

Changing the color palette

Material defines a default hue for every primary and accent color on Google's Material Design color palette. This makes it very easy to change the overall look of the theme. Just set the primary and accent colors using the following variables in your mkdocs.yml:

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 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

Material uses the Roboto font family by default, specifically the regular sans-serif type for text and the monospaced type for code. Both fonts are loaded from Google Fonts and can easily 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 font-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 'none':

extra:
  font: 'none'

Adding a logo

Material makes it easy to add your 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'

Adding social links

If you want to link your social accounts, the Material theme provides an easy way for doing this in the footer of the documentation using the automatically included FontAwesome webfont. The syntax is simple – 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://de.linkedin.com/in/martin-donath-20a95039'

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'

Localization L10N

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

{% macro t(key) %}{{ {
  "edit.link.title": "Edit this page",
  "footer.previous": "Previous",
  "footer.next": "Next",
  "search.placeholder": "Search",
  "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 in the customization guide.

!!! warning "Migrating from Material 0.2.x"

In 0.2.x localization was done within the `extra` configuration of your
`mkdocs.yml`. With 1.0.0 this is no longer possible as the configuration
will be ignored.

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

• Permalinks

• Footnotes

• 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://my-github-handle.github.io/my-project'

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

# Copyright
copyright: 'Copyright © 2016 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/squidfunk'
    - type: 'twitter'
      link: 'https://twitter.com/squidfunk'
    - type: 'linkedin'
      link: 'https://de.linkedin.com/in/martin-donath-20a95039'

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

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