mkdocs-material/docs/getting-started.md

# Getting started

## Installation

### Installing MkDocs

Before installing [MkDocs][1], 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:

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

Installing and verifying MkDocs is as simple as:

``` sh
pip install mkdocs && mkdocs --version
# mkdocs, version 0.17.1
```

Material requires MkDocs >= 0.17.1.

  [1]: https://www.mkdocs.org

### Installing Material

#### using pip

Material can be installed with `pip`:

``` sh
pip install mkdocs-material
```

#### using choco

If you're on Windows you can use [Chocolatey][2] to install [Material][3]:

``` dos
choco install mkdocs-material
```

This will install all required dependencies like [Python][4] and [MkDocs][5].

  [2]: https://chocolatey.org
  [3]: https://chocolatey.org/packages/mkdocs-material
  [4]: https://chocolatey.org/packages/python
  [5]: https://chocolatey.org/packages/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:

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

This is especially useful if you want to [extend the theme][6] and
[override some parts][7] of the theme. The theme will reside in the folder
`mkdocs-material/material`.

  [6]: customization.md#extending-the-theme
  [7]: customization.md#overriding-partials

### 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][8] 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
```

If you're using Windows command prompt (`cmd.exe`), substitute `${PWD}` with
`"%cd%"`.

  [8]: https://hub.docker.com/r/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 a package manager:

``` yaml
theme:
  name: 'material'
```

If you cloned Material from GitHub:

``` yaml
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:

``` sh
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.

  [9]: http://localhost:8000

## Configuration

### Color palette

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

``` yaml
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 last four 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][11] for more information.

  [10]: http://www.materialui.co/colors
  [11]: customization.md

#### Primary colors

> Default: `indigo`

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

<button data-md-color-primary="red">Red</button>
<button data-md-color-primary="pink">Pink</button>
<button data-md-color-primary="purple">Purple</button>
<button data-md-color-primary="deep-purple">Deep Purple</button>
<button data-md-color-primary="indigo">Indigo</button>
<button data-md-color-primary="blue">Blue</button>
<button data-md-color-primary="light-blue">Light Blue</button>
<button data-md-color-primary="cyan">Cyan</button>
<button data-md-color-primary="teal">Teal</button>
<button data-md-color-primary="green">Green</button>
<button data-md-color-primary="light-green">Light Green</button>
<button data-md-color-primary="lime">Lime</button>
<button data-md-color-primary="yellow">Yellow</button>
<button data-md-color-primary="amber">Amber</button>
<button data-md-color-primary="orange">Orange</button>
<button data-md-color-primary="deep-orange">Deep Orange</button>
<button data-md-color-primary="brown">Brown</button>
<button data-md-color-primary="grey">Grey</button>
<button data-md-color-primary="blue-grey">Blue Grey</button>
<button data-md-color-primary="white">White</button>

<script>
  var buttons = document.querySelectorAll("button[data-md-color-primary]");
  Array.prototype.forEach.call(buttons, function(button) {
    button.addEventListener("click", function() {
      document.body.dataset.mdColorPrimary = this.dataset.mdColorPrimary;
    })
  })
</script>

#### Accent colors

> Default: `indigo`

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

<button data-md-color-accent="red">Red</button>
<button data-md-color-accent="pink">Pink</button>
<button data-md-color-accent="purple">Purple</button>
<button data-md-color-accent="deep-purple">Deep Purple</button>
<button data-md-color-accent="indigo">Indigo</button>
<button data-md-color-accent="blue">Blue</button>
<button data-md-color-accent="light-blue">Light Blue</button>
<button data-md-color-accent="cyan">Cyan</button>
<button data-md-color-accent="teal">Teal</button>
<button data-md-color-accent="green">Green</button>
<button data-md-color-accent="light-green">Light Green</button>
<button data-md-color-accent="lime">Lime</button>
<button data-md-color-accent="yellow">Yellow</button>
<button data-md-color-accent="amber">Amber</button>
<button data-md-color-accent="orange">Orange</button>
<button data-md-color-accent="deep-orange">Deep Orange</button>

<script>
  var buttons = document.querySelectorAll("button[data-md-color-accent]");
  Array.prototype.forEach.call(buttons, function(button) {
    button.addEventListener("click", function() {
      document.body.dataset.mdColorAccent = this.dataset.mdColorAccent;
    })
  })
</script>

### Font family

> Default: `Roboto` and `Roboto Mono`

By default the [Roboto font family][12] 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][13] and can be changed to other fonts,
like for example the [Ubuntu font family][14]:

``` yaml
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`:

``` yaml
theme:
  font: false
```

  [12]: https://fonts.google.com/specimen/Roboto
  [13]: https://fonts.google.com
  [14]: https://fonts.google.com/specimen/Ubuntu

### Logo

> Default icon: `school`

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:

``` yaml
theme:
  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][15], e.g.

``` yaml
theme:
  logo:
    icon: 'cloud'
```

  [15]: https://material.io/icons/

### Language

!!! info "Call for Contributions: Add languages/translations to Material"

    Help translate Material into more languages - it's just **one click** and
    takes approximately **2 minutes**: [click here](http://bit.ly/2EbzFc8)

#### Localization

> Default: `en`

Material for MkDocs supports internationalization (i18n) and provides
translations for all template variables and labels in the following languages:

<table style="white-space: nowrap;">
  <thead>
    <tr>
      <th colspan="4">Available languages</td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>ar</code> / Arabic</td>
      <td><code>ca</code> / Catalan</td>
      <td><code>cs</code> / Czech</td>
      <td><code>da</code> / Danish</td>
    </tr>
    <tr>
      <td><code>nl</code> / Dutch</td>
      <td><code>en</code> / English</td>
      <td><code>fi</code> / Finnish</td>
      <td><code>fr</code> / French</td>
    </tr>
    <tr>
      <td><code>gl</code> / Galician</td>
      <td><code>de</code> / German</td>
      <td><code>gr</code> / Greek</td>
      <td><code>he</code> / Hebrew</td>
    </tr>
    <tr>
      <td><code>hi</code> / Hindi</td>
      <td><code>hr</code> / Croatian</td>
      <td><code>hu</code> / Hungarian</td>
      <td><code>id</code> / Indonesian</td>
    </tr>
    <tr>
      <td><code>it</code> / Italian</td>
      <td><code>ja</code> / Japanese</td>
      <td><code>kr</code> / Korean</td>
      <td><code>no</code> / Norwegian</td>
    </tr>
    <tr>
      <td colspan="2"><code>nn</code> / Norwegian (Nynorsk)</td>
      <td><code>fa</code> / Persian</td>
      <td><code>pl</code> / Polish</td>
    </tr>
    <tr>
      <td><code>pt</code> / Portugese</td>
      <td><code>ru</code> / Russian</td>
      <td><code>sr</code> / Serbian</td>
      <td><code>sh</code> / Serbo-Croatian</td>
    </tr>
    <tr>
      <td><code>sk</code> / Slovak</td>
      <td><code>si</code> / Slovenian</td>
      <td><code>es</code> / Spanish</td>
      <td><code>sv</code> / Swedish</td>
    </tr>
    <tr>
      <td><code>tr</code> / Turkish</td>
      <td><code>uk</code> / Ukrainian</td>
      <td><code>vi</code> / Vietnamese</td>
      <td><code>zh</code> / Chinese (Simplified)</td>
    </tr>
    <tr>
      <td colspan="2">
        <code>zh-Hant</code> / Chinese (Traditional)
      </td>
      <td colspan="2"><code>zh-TW</code> / Chinese (Taiwanese)</td>
    </tr>
    <tr>
      <td colspan="4" align="right">
        <a href="http://bit.ly/2EbzFc8">Submit a new language</a>
      </td>
    </tr>
  </tbody>
</table>

Specify the language with:

``` yaml
theme:
  language: 'en'
```

If the language is not specified, Material falls back to English. To create a
translation for another language, copy the localization file of an existing
language, name the new file using the [2-letter language code][16] and adjust
all translations:

``` sh
cp partials/language/en.html partials/language/jp.html
```

  [16]: https://www.w3schools.com/tags/ref_language_codes.asp

#### Text direction

> Default: best match for given theme language, automatically set

Material supports both, left-to-right (`ltr`) and right-to-left (`rtl`) text
direction. This enables more languages like Arabic, Hebrew, Syriac and others
to be used with the theme:

``` yaml
theme:
  direction: 'rtl'
```

#### Site search

> Default: best match for given theme language, automatically set

Site search is implemented using [lunr.js][17], which includes stemmers for the
English language by default, while stemmers for other languages are included
with [lunr-languages][18], both of which are integrated with this theme.
Material selects the matching (or best-matching) stemmer for the given theme
language. Multilingual search can be activated in your project's `mkdocs.yml`
by explicitly defining the search language(s):

``` yaml
extra:
  search:
    language: 'en, de, ru'
```

At the time of writing, the following languages are supported:

<table style="white-space: nowrap;">
  <thead>
    <tr>
      <th colspan="4">Available language stemmers</td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>da</code> / Danish</td>
      <td><code>du</code> / Dutch</td>
      <td><code>en</code> / English</td>
      <td><code>fi</code> / Finnish</td>
    </tr>
    <tr>
      <td><code>fr</code> / French</td>
      <td><code>de</code> / German</td>
      <td><code>hu</code> / Hungarian</td>
      <td><code>it</code> / Italian</td>
    </tr>
    <tr>
      <td><code>ja</code> / Japanese</td>
      <td><code>no</code> / Norwegian</td>
      <td><code>pt</code> / Portugese</td>
      <td><code>ro</code> / Romanian</td>
    </tr>
    <tr>
      <td><code>ru</code> / Russian</td>
      <td><code>es</code> / Spanish</td>
      <td><code>sv</code> / Swedish</td>
      <td><code>tr</code> / Turkish</td>
    </tr>
  </tbody>
</table>

!!! warning "MkDocs 1.0 compatibility"

    While MkDocs 1.0 supports prebuilding the search index, Material currently
    doesn't support this setting as the default search behavior of the original
    theme was heavily modified for the sake of a better UX. Integration is
    possible, but a small subset of the features Material provides will not be
    portable to the prebuilt index mainly due to missing localization.

!!! warning "Only specify the languages you really need"

    Be aware that including support 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 be customized which makes it possible
to index parts of words that are separated by `-` or `.`:

``` yaml
extra:
  search:
    tokenizer: '[\s\-\.]+'
```

  [17]: https://lunrjs.com
  [18]: https://github.com/MihaiValentin/lunr-languages

### Favicon

> Default: `assets/images/favicon.png`

The default favicon can be changed by setting the `favicon` variable to an
`.ico` or image file:

``` yaml
theme:
  favicon: 'assets/images/favicon.ico'
```

### Features

#### Tabs

> Default: `false`

By default, the entire navigation is rendered on the left side using collapsible
sections (different from the default MkDocs theme which renders the top-level
sections in the header), because horizontal navigation is often problematic on
smaller screens. However, for large documentation projects it's sometimes
desirable to add another navigation layer to separate top-level sections.
Material achieves this with the tabs feature, which can be enabled by setting
the respective feature flag to `true`:

``` yaml
theme:
  feature:
    tabs: true
```

When tabs are enabled, *top-level sections* will be rendered in an additional
layer directly below the header. The navigation on the left side will only
include the pages contained within the selected section. Furthermore, *top-level
pages* defined inside your project's `mkdocs.yml` will be grouped under the
first tab which will receive the title of the first page.

## Customization

### 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`:

``` yaml
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.
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`.

!!! question "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][19] on more
    guidance regarding the `edit_uri` attribute, which defines whether the edit
    button is shown or not.

  [19]: https://www.mkdocs.org/user-guide/configuration/#edit_uri

### Adding social links

Social accounts can be linked in the footer of the documentation using the
automatically included [FontAwesome][20] 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:

``` yaml
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`.

  [20]: http://fontawesome.io/icons/

### Adding a Web App Manifest

A [Web App Manifest][21] 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 a manifest in your `mkdocs.yml`:

```yaml
extra:
  manifest: 'manifest.webmanifest'
```

  [21]: https://developers.google.com/web/fundamentals/web-app-manifest/

### More advanced customization

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

  [22]: customization.md

## Integrations

### Google Analytics

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

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

### Disqus

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

``` yaml
extra:
  disqus: 'your-shortname'
```

The comments section is inserted on *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.

!!! warning "Requirements"

    `site_url` value 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][24].

  [23]: https://disqus.com
  [24]: extensions/metadata.md#disqus

## Extensions

MkDocs supports several [Markdown extensions][25]. 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:

``` yaml
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][26]
* [Codehilite][27]
* [Footnotes][28]
* [Metadata][29]
* [Permalinks][30]
* [PyMdown Extensions][31]

  [25]: https://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
  [26]: extensions/admonition.md
  [27]: extensions/codehilite.md
  [28]: extensions/footnotes.md
  [29]: extensions/metadata.md
  [30]: extensions/permalinks.md
  [31]: extensions/pymdown.md

## Plugins

MkDocs's plugin architecture makes it possible to add pre- or post-processing
steps that sit between the theme and your documentation. A great example of a
third-party plugin is the [mkdocs-minify-plugin][32] which strips all whitespace
from the generated documentation.

Install it with `pip`:

``` sh
pip install mkdocs-minify-plugin
```

Enable it with the following lines in your `mkdocs.yml`:

``` yaml
plugins:
  - search
  - minify:
      minify_html: true
      minify_js: true
```

The MkDocs wiki contains a [list of all available plugins][33].

!!! warning "Remember to re-add the `search` plugin"

    If you have no `plugins` entry in your config file yet, you'll likely also
    want to add the `search` plugin. MkDocs enables it by default if there is
    no `plugins` entry set.

  [32]: https://github.com/byrnereese/mkdocs-minify-plugin
  [33]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins

## Full example

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

``` yaml
# 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 - 2017 Martin Donath'

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

# Customization
extra:
  manifest: 'manifest.webmanifest'
  social:
    - type: 'github'
      link: 'https://github.com/squidfunk'
    - type: 'twitter'
      link: 'https://twitter.com/squidfunk'
    - type: '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
```