2016-02-09 23:59:37 +03:00
|
|
|
|
# Getting started
|
|
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
|
|
### Installing MkDocs
|
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
Before installing [MkDocs][1], you need to make sure you have Python and `pip`
|
2016-12-29 19:55:08 +03:00
|
|
|
|
– the Python package manager – up and running. You can verify if you're already
|
2016-02-24 19:31:01 +03:00
|
|
|
|
good to go with the following commands:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
python --version
|
2016-12-29 19:55:08 +03:00
|
|
|
|
# Python 2.7.13
|
2016-02-09 23:59:37 +03:00
|
|
|
|
pip --version
|
2016-12-29 19:55:08 +03:00
|
|
|
|
# pip 9.0.1
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Installing and verifying MkDocs is as simple as:
|
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
pip install mkdocs && mkdocs --version
|
2017-10-31 21:42:43 +03:00
|
|
|
|
# mkdocs, version 0.17.1
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
Material requires MkDocs >= 0.17.1.
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
[1]: http://www.mkdocs.org
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
2016-02-09 23:59:37 +03:00
|
|
|
|
### Installing Material
|
|
|
|
|
|
2017-01-14 15:43:19 +03:00
|
|
|
|
#### using pip
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
|
|
|
|
Material can be installed with `pip`:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
pip install mkdocs-material
|
|
|
|
|
```
|
|
|
|
|
|
2017-01-14 15:43:19 +03:00
|
|
|
|
#### using choco
|
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
If you're on Windows you can use [Chocolatey][2] to install [Material][3]:
|
2017-01-14 15:43:19 +03:00
|
|
|
|
|
|
|
|
|
``` dos
|
|
|
|
|
choco install mkdocs-material
|
|
|
|
|
```
|
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
This will install all required dependencies like [Python][4] and [MkDocs][5].
|
2017-01-14 15:43:19 +03:00
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
[2]: https://chocolatey.org
|
|
|
|
|
[3]: https://chocolatey.org/packages/mkdocs-material
|
|
|
|
|
[4]: https://chocolatey.org/packages/python
|
|
|
|
|
[5]: https://chocolatey.org/packages/mkdocs
|
2017-01-14 15:43:19 +03:00
|
|
|
|
|
|
|
|
|
#### cloning from GitHub
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
2017-01-12 22:15:30 +03:00
|
|
|
|
Material can also be used without a system-wide installation by cloning the
|
2016-12-29 19:55:08 +03:00
|
|
|
|
repository into a subfolder of your project's root directory:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
2016-12-29 19:55:08 +03:00
|
|
|
|
git clone https://github.com/squidfunk/mkdocs-material.git
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
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
|
2017-01-07 22:07:41 +03:00
|
|
|
|
`mkdocs-material/material`.
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
[6]: customization.md#extending-the-theme
|
|
|
|
|
[7]: customization.md#overriding-partials
|
2017-06-21 11:25:00 +03:00
|
|
|
|
|
2017-03-11 20:01:14 +03:00
|
|
|
|
### 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
|
2017-03-11 20:36:34 +03:00
|
|
|
|
the adequate permissions. There are two possible solutions for this:
|
2017-03-11 20:01:14 +03:00
|
|
|
|
|
|
|
|
|
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'"
|
|
|
|
|
|
2017-03-11 20:36:34 +03:00
|
|
|
|
If you run into this error, the most common reason is that you installed
|
2017-03-11 20:01:14 +03:00
|
|
|
|
MkDocs through some package manager (e.g. Homebrew or `apt-get`) and the
|
|
|
|
|
Material theme through `pip`, so both packages end up in different
|
2017-08-29 09:17:26 +03:00
|
|
|
|
locations. MkDocs only checks its install location for themes.
|
2017-03-11 20:01:14 +03:00
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
### 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:
|
|
|
|
|
|
|
|
|
|
```
|
2018-01-13 19:19:07 +03:00
|
|
|
|
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
|
2017-11-05 16:40:30 +03:00
|
|
|
|
```
|
|
|
|
|
|
2018-01-13 19:19:07 +03:00
|
|
|
|
If you're using Windows command prompt (`cmd.exe`), substitute `${PWD}` with
|
|
|
|
|
`"%cd%"`.
|
|
|
|
|
|
2017-11-05 16:40:30 +03:00
|
|
|
|
[8]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
|
|
|
|
|
2016-12-29 19:55:08 +03:00
|
|
|
|
## Usage
|
|
|
|
|
|
2017-06-21 11:25:00 +03:00
|
|
|
|
In order to enable the theme just add one of the following lines to your
|
2018-01-18 23:19:10 +03:00
|
|
|
|
project's `mkdocs.yml`. If you installed Material using a package manager:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
2017-10-31 21:42:43 +03:00
|
|
|
|
theme:
|
|
|
|
|
name: 'material'
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-01-12 22:15:30 +03:00
|
|
|
|
If you cloned Material from GitHub:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
2017-10-31 21:42:43 +03:00
|
|
|
|
theme:
|
|
|
|
|
name: null
|
|
|
|
|
custom_dir: 'mkdocs-material/material'
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-03-11 20:36:34 +03:00
|
|
|
|
MkDocs includes a development server, so you can review your changes as you go.
|
2017-01-12 22:15:30 +03:00
|
|
|
|
The development server can be started with the following command:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
mkdocs serve
|
|
|
|
|
```
|
|
|
|
|
|
2017-06-21 11:25:00 +03:00
|
|
|
|
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,
|
2017-10-31 21:42:43 +03:00
|
|
|
|
or read on and customize the theme.
|
2017-01-07 22:07:41 +03:00
|
|
|
|
|
2017-01-14 14:42:53 +03:00
|
|
|
|
[9]: http://localhost:8000
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
## Configuration
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
### Color palette
|
2016-02-24 19:31:01 +03:00
|
|
|
|
|
2017-10-13 16:32:28 +03:00
|
|
|
|
A default hue is defined for every primary and accent color on Google's
|
2017-06-21 11:25:00 +03:00
|
|
|
|
Material Design [color palette][10], which makes it very easy to change the
|
2016-12-29 19:55:08 +03:00
|
|
|
|
overall look of the theme. Just set the primary and accent colors using the
|
2017-06-21 11:25:00 +03:00
|
|
|
|
following variables:
|
2016-02-24 19:31:01 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
2017-10-31 21:42:43 +03:00
|
|
|
|
theme:
|
2016-02-24 19:31:01 +03:00
|
|
|
|
palette:
|
|
|
|
|
primary: 'indigo'
|
2017-11-05 16:26:44 +03:00
|
|
|
|
accent: 'indigo'
|
2016-02-24 19:31:01 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-01-12 22:15:30 +03:00
|
|
|
|
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`,
|
2017-11-19 19:41:06 +03:00
|
|
|
|
`yellow`, `amber`, `orange`, `deep orange`, `brown`, `grey`, `blue grey` and
|
2017-12-09 20:13:01 +03:00
|
|
|
|
`white`. The last four colors can only be used as a primary color.
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
|
|
|
|
If the color is set via this configuration, an additional CSS file that
|
2017-06-21 11:25:00 +03:00
|
|
|
|
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.
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
2017-01-14 14:42:53 +03:00
|
|
|
|
[10]: http://www.materialui.co/colors
|
|
|
|
|
[11]: customization.md
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
|
|
|
|
#### Primary colors
|
|
|
|
|
|
2017-11-01 16:01:23 +03:00
|
|
|
|
> Default: `indigo`
|
|
|
|
|
|
2016-12-29 19:55:08 +03:00
|
|
|
|
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>
|
2017-11-19 19:41:06 +03:00
|
|
|
|
<button data-md-color-primary="white">White</button>
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
|
|
|
|
<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
|
|
|
|
|
|
2017-11-01 16:01:23 +03:00
|
|
|
|
> Default: `indigo`
|
|
|
|
|
|
2016-12-29 19:55:08 +03:00
|
|
|
|
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>
|
2016-02-24 19:31:01 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
### Font family
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-11-01 16:01:23 +03:00
|
|
|
|
> Default: `Roboto` and `Roboto Mono`
|
|
|
|
|
|
2017-06-21 11:25:00 +03:00
|
|
|
|
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]:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
2017-10-31 21:42:43 +03:00
|
|
|
|
theme:
|
2016-02-17 20:08:11 +03:00
|
|
|
|
font:
|
2016-12-29 19:55:08 +03:00
|
|
|
|
text: 'Ubuntu'
|
|
|
|
|
code: 'Ubuntu Mono'
|
2016-02-17 20:08:11 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-06-21 11:25:00 +03:00
|
|
|
|
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`:
|
2016-02-17 20:08:11 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
2017-10-31 21:42:43 +03:00
|
|
|
|
theme:
|
2017-03-11 20:36:34 +03:00
|
|
|
|
font: false
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-01-14 14:42:53 +03:00
|
|
|
|
[12]: https://fonts.google.com/specimen/Roboto
|
2017-02-25 00:53:12 +03:00
|
|
|
|
[13]: https://fonts.google.com
|
2017-01-14 14:42:53 +03:00
|
|
|
|
[14]: https://fonts.google.com/specimen/Ubuntu
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
### Logo
|
|
|
|
|
|
2017-11-01 16:01:23 +03:00
|
|
|
|
> Default icon: `school`
|
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
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
|
|
|
|
|
|
|
|
|
|
#### Localization
|
|
|
|
|
|
2017-11-01 16:01:23 +03:00
|
|
|
|
> Default: `en`
|
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
Material for MkDocs supports internationalization (i18n) and provides
|
2018-01-31 19:56:26 +03:00
|
|
|
|
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>
|
2018-02-12 23:36:01 +03:00
|
|
|
|
<td><code>ar</code> / Arabic</td>
|
2018-01-31 19:56:26 +03:00
|
|
|
|
<td><code>da</code> / Danish</td>
|
|
|
|
|
<td><code>nl</code> / Dutch</td>
|
|
|
|
|
<td><code>en</code> / English</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-12 23:36:01 +03:00
|
|
|
|
<td><code>fr</code> / French</td>
|
2018-01-31 19:56:26 +03:00
|
|
|
|
<td><code>de</code> / German</td>
|
|
|
|
|
<td><code>hu</code> / Hungarian</td>
|
|
|
|
|
<td><code>it</code> / Italian</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-12 23:36:01 +03:00
|
|
|
|
<td><code>ja</code> / Japanese</td>
|
2018-01-31 19:56:26 +03:00
|
|
|
|
<td><code>kr</code> / Korean</td>
|
|
|
|
|
<td><code>no</code> / Norwegian</td>
|
2018-02-02 01:58:39 +03:00
|
|
|
|
<td><code>fa</code> / Persian</td>
|
2018-01-31 19:56:26 +03:00
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-12 23:36:01 +03:00
|
|
|
|
<td><code>pl</code> / Polish</td>
|
2018-02-02 01:58:39 +03:00
|
|
|
|
<td><code>pt</code> / Portugese</td>
|
2018-01-31 19:56:26 +03:00
|
|
|
|
<td><code>ru</code> / Russian</td>
|
|
|
|
|
<td><code>es</code> / Spanish</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-12 23:36:01 +03:00
|
|
|
|
<td><code>sv</code> / Swedish</td>
|
2018-02-02 01:58:39 +03:00
|
|
|
|
<td><code>tr</code> / Turkish</td>
|
2018-02-19 01:31:58 +03:00
|
|
|
|
<td><code>uk</code> / Ukrainian</td>
|
|
|
|
|
<td><code>vi</code> / Vietnamese</td>
|
2018-02-12 23:36:01 +03:00
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td colspan="2">
|
|
|
|
|
<code>zh</code> / Chinese (Simplified)
|
|
|
|
|
</td>
|
|
|
|
|
<td colspan="2">
|
|
|
|
|
<code>zh-Hant</code> / Chinese (Traditional)
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td colspan="4" align="right">
|
2018-01-31 19:56:26 +03:00
|
|
|
|
<a href="http://bit.ly/2EbzFc8">Submit a new language</a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
2018-02-12 23:36:01 +03:00
|
|
|
|
</tr>
|
2018-01-31 19:56:26 +03:00
|
|
|
|
</tbody>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
Specify the language with:
|
2017-10-31 21:42:43 +03:00
|
|
|
|
|
|
|
|
|
``` 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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Feel free to contribute your localization to Material for MkDocs by opening a
|
|
|
|
|
Pull Request.
|
|
|
|
|
|
2017-11-05 16:54:00 +03:00
|
|
|
|
[16]: https://www.w3schools.com/tags/ref_language_codes.asp
|
2017-10-31 21:42:43 +03:00
|
|
|
|
|
2018-01-13 19:19:07 +03:00
|
|
|
|
#### Text direction
|
|
|
|
|
|
2018-02-02 01:47:00 +03:00
|
|
|
|
> Default: best match for given theme language, automatically set
|
2018-01-13 19:19:07 +03:00
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
2018-01-18 23:19:10 +03:00
|
|
|
|
``` yaml
|
2018-01-13 19:19:07 +03:00
|
|
|
|
theme:
|
2018-01-18 23:19:10 +03:00
|
|
|
|
direction: 'rtl'
|
2018-01-13 19:19:07 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
#### Site search
|
|
|
|
|
|
2018-01-22 00:56:54 +03:00
|
|
|
|
> Default: best match for given theme language, automatically set
|
2017-11-01 16:01:23 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
Site search is implemented using [lunr.js][17], which includes stemmers for the
|
|
|
|
|
English language by default, while stemmers for other languages are included
|
2018-01-22 00:56:54 +03:00
|
|
|
|
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):
|
2017-10-31 21:42:43 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
extra:
|
|
|
|
|
search:
|
2017-11-05 18:00:24 +03:00
|
|
|
|
language: 'en, de, ru'
|
2017-10-31 21:42:43 +03:00
|
|
|
|
```
|
|
|
|
|
|
2018-01-31 19:56:26 +03:00
|
|
|
|
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>jp</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>
|
2017-10-31 21:42:43 +03:00
|
|
|
|
|
2017-12-02 16:56:06 +03:00
|
|
|
|
!!! info "Search language support for Chinese"
|
|
|
|
|
|
|
|
|
|
[lunr-languages][18] currently doesn't include a stemmer for Chinese or
|
2018-01-22 00:56:54 +03:00
|
|
|
|
other Asian languages, but uses the Japanese stemmer, as some users
|
|
|
|
|
reported pretty decent results.
|
2017-12-02 16:56:06 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
!!! 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
|
|
|
|
|
|
2017-11-01 14:04:22 +03:00
|
|
|
|
### Favicon
|
|
|
|
|
|
2017-11-01 16:01:23 +03:00
|
|
|
|
> Default: `assets/images/favicon.png`
|
|
|
|
|
|
2017-11-01 14:04:22 +03:00
|
|
|
|
The default favicon can be changed by setting the `favicon` variable to an
|
|
|
|
|
`.ico` or image file:
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
theme:
|
2017-12-06 23:18:53 +03:00
|
|
|
|
favicon: 'assets/images/favicon.ico'
|
2017-11-01 14:04:22 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
### Features
|
|
|
|
|
|
|
|
|
|
#### Tabs
|
|
|
|
|
|
2017-11-01 16:01:23 +03:00
|
|
|
|
> Default: `false`
|
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
theme:
|
|
|
|
|
feature:
|
|
|
|
|
tabs: true
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Customization
|
|
|
|
|
|
2017-03-11 19:24:03 +03:00
|
|
|
|
### 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
|
2017-11-05 16:26:44 +03:00
|
|
|
|
repo_name: 'squidfunk/mkdocs-material'
|
|
|
|
|
repo_url: 'https://github.com/squidfunk/mkdocs-material'
|
2017-03-11 19:24:03 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-06-21 11:25:00 +03:00
|
|
|
|
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.
|
2017-03-11 19:24:03 +03:00
|
|
|
|
Furthermore, if `repo_url` points to a GitHub, BitBucket or GitLab repository,
|
2017-03-11 20:36:34 +03:00
|
|
|
|
the respective service logo will be shown next to the name of the repository.
|
2017-03-11 19:24:03 +03:00
|
|
|
|
Additionally, for GitHub, the number of stars and forks is shown.
|
|
|
|
|
|
2017-08-02 15:09:13 +03:00
|
|
|
|
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`.
|
|
|
|
|
|
2017-10-13 16:32:28 +03:00
|
|
|
|
!!! question "Why is there an edit button at the top of every article?"
|
2017-03-11 19:24:03 +03:00
|
|
|
|
|
|
|
|
|
If the `repo_url` is set to a GitHub or BitBucket repository, and the
|
2017-03-11 20:36:34 +03:00
|
|
|
|
`repo_name` is set to *GitHub* or *BitBucket* (implied by default), an
|
2017-03-11 19:24:03 +03:00
|
|
|
|
edit button will appear at the top of every article. This is the automatic
|
2017-10-31 21:42:43 +03:00
|
|
|
|
behavior that MkDocs implements. See the [MkDocs documentation][19] on more
|
2017-03-11 19:24:03 +03:00
|
|
|
|
guidance regarding the `edit_uri` attribute, which defines whether the edit
|
2017-04-28 18:04:00 +03:00
|
|
|
|
button is shown or not.
|
2017-03-11 19:24:03 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
[19]: http://www.mkdocs.org/user-guide/configuration/#edit_uri
|
2017-09-01 16:23:44 +03:00
|
|
|
|
|
2016-12-29 19:55:08 +03:00
|
|
|
|
### Adding social links
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-06-21 11:25:00 +03:00
|
|
|
|
Social accounts can be linked in the footer of the documentation using the
|
2017-10-31 21:42:43 +03:00
|
|
|
|
automatically included [FontAwesome][20] webfont. The `type` must denote the
|
2017-06-21 11:25:00 +03:00
|
|
|
|
name of the social service, e.g. `github`, `twitter` or `linkedin` and the
|
|
|
|
|
`link` must contain the URL you want to link to:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
extra:
|
2016-12-29 19:55:08 +03:00
|
|
|
|
social:
|
|
|
|
|
- type: 'github'
|
|
|
|
|
link: 'https://github.com/squidfunk'
|
|
|
|
|
- type: 'twitter'
|
|
|
|
|
link: 'https://twitter.com/squidfunk'
|
|
|
|
|
- type: 'linkedin'
|
2017-07-20 15:32:02 +03:00
|
|
|
|
link: 'https://linkedin.com/in/squidfunk'
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-01-12 22:15:30 +03:00
|
|
|
|
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`.
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
[20]: http://fontawesome.io/icons/
|
|
|
|
|
|
|
|
|
|
### More advanced customization
|
|
|
|
|
|
|
|
|
|
If you want to change the general appearance of the Material theme, see
|
|
|
|
|
[this article][21] for more information on advanced customization.
|
|
|
|
|
|
|
|
|
|
[21]: customization.md
|
|
|
|
|
|
|
|
|
|
## Integrations
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
2017-11-05 16:26:44 +03:00
|
|
|
|
### Google Analytics
|
2016-03-12 15:21:06 +03:00
|
|
|
|
|
2016-12-29 19:55:08 +03:00
|
|
|
|
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`:
|
2016-03-12 15:21:06 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
google_analytics:
|
|
|
|
|
- 'UA-XXXXXXXX-X'
|
|
|
|
|
- 'auto'
|
|
|
|
|
```
|
|
|
|
|
|
2017-11-05 16:26:44 +03:00
|
|
|
|
### Disqus
|
2017-02-25 00:53:12 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
Material for MkDocs is integrated with [Disqus][22], so if you want to add a
|
2017-02-25 00:53:12 +03:00
|
|
|
|
comments section to your documentation set the shortname of your Disqus project
|
|
|
|
|
in your `mkdocs.yml`:
|
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
extra:
|
2018-02-11 21:04:29 +03:00
|
|
|
|
disqus: 'your-shortname'
|
2017-02-25 00:53:12 +03:00
|
|
|
|
```
|
|
|
|
|
|
2017-11-03 16:25:37 +03:00
|
|
|
|
The comments section is inserted on *every page, except the index page*.
|
2017-07-25 17:24:20 +03:00
|
|
|
|
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.
|
2017-02-25 00:53:12 +03:00
|
|
|
|
|
2017-05-31 16:31:17 +03:00
|
|
|
|
!!! warning "Requirements"
|
|
|
|
|
|
2017-07-18 09:35:03 +03:00
|
|
|
|
`site_url` value must be set in `mkdocs.yml` for the Disqus integration to
|
2017-05-31 16:31:17 +03:00
|
|
|
|
load properly.
|
2017-05-20 22:19:30 +03:00
|
|
|
|
|
2018-02-11 21:18:33 +03:00
|
|
|
|
Disqus can also be enabled or disabled for specific pages using [Metadata][23].
|
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
[22]: https://disqus.com
|
2018-02-11 21:18:33 +03:00
|
|
|
|
[23]: extensions/metadata.md#disqus
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
## Extensions
|
|
|
|
|
|
2018-02-11 21:18:33 +03:00
|
|
|
|
MkDocs supports several [Markdown extensions][24]. The following extensions
|
2017-01-07 22:07:41 +03:00
|
|
|
|
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:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- admonition
|
2017-10-18 22:38:33 +03:00
|
|
|
|
- codehilite:
|
2017-10-16 20:13:05 +03:00
|
|
|
|
guess_lang: false
|
|
|
|
|
- toc:
|
|
|
|
|
permalink: true
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2016-12-29 19:55:08 +03:00
|
|
|
|
For more information, see the following list of extensions supported by the
|
|
|
|
|
Material theme including more information regarding installation and usage:
|
2016-02-21 20:30:49 +03:00
|
|
|
|
|
2018-02-11 21:18:33 +03:00
|
|
|
|
* [Admonition][25]
|
|
|
|
|
* [Codehilite][26]
|
|
|
|
|
* [Footnotes][27]
|
|
|
|
|
* [Metadata][28]
|
|
|
|
|
* [Permalinks][29]
|
|
|
|
|
* [PyMdown Extensions][30]
|
|
|
|
|
|
|
|
|
|
[24]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
|
|
|
|
|
[25]: extensions/admonition.md
|
|
|
|
|
[26]: extensions/codehilite.md
|
|
|
|
|
[27]: extensions/footnotes.md
|
|
|
|
|
[28]: extensions/metadata.md
|
|
|
|
|
[29]: extensions/permalinks.md
|
|
|
|
|
[30]: extensions/pymdown.md
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
## Full example
|
|
|
|
|
|
2016-08-07 19:01:56 +03:00
|
|
|
|
Below is a full example configuration for a `mkdocs.yml`:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
# Project information
|
2017-11-05 16:26:44 +03:00
|
|
|
|
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/'
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
# Repository
|
2017-11-05 16:26:44 +03:00
|
|
|
|
repo_name: 'squidfunk/mkdocs-material'
|
|
|
|
|
repo_url: 'https://github.com/squidfunk/mkdocs-material'
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
|
|
|
|
# Copyright
|
2017-11-05 16:26:44 +03:00
|
|
|
|
copyright: 'Copyright © 2016 - 2017 Martin Donath'
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2017-10-31 21:42:43 +03:00
|
|
|
|
# Configuration
|
|
|
|
|
theme:
|
|
|
|
|
name: 'material'
|
2017-10-19 22:01:57 +03:00
|
|
|
|
language: 'en'
|
2016-02-24 19:31:01 +03:00
|
|
|
|
palette:
|
|
|
|
|
primary: 'indigo'
|
2016-12-29 19:55:08 +03:00
|
|
|
|
accent: 'indigo'
|
2016-02-17 20:08:11 +03:00
|
|
|
|
font:
|
|
|
|
|
text: 'Roboto'
|
|
|
|
|
code: 'Roboto Mono'
|
2017-10-31 21:42:43 +03:00
|
|
|
|
|
|
|
|
|
# Customization
|
|
|
|
|
extra:
|
2016-12-29 19:55:08 +03:00
|
|
|
|
social:
|
|
|
|
|
- type: 'github'
|
2017-11-05 16:26:44 +03:00
|
|
|
|
link: 'https://github.com/squidfunk'
|
2016-12-29 19:55:08 +03:00
|
|
|
|
- type: 'twitter'
|
2017-11-05 16:26:44 +03:00
|
|
|
|
link: 'https://twitter.com/squidfunk'
|
2016-12-29 19:55:08 +03:00
|
|
|
|
- type: 'linkedin'
|
2017-11-05 16:26:44 +03:00
|
|
|
|
link: 'https://linkedin.com/in/squidfunk'
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2016-03-12 15:21:06 +03:00
|
|
|
|
# Google Analytics
|
|
|
|
|
google_analytics:
|
|
|
|
|
- 'UA-XXXXXXXX-X'
|
|
|
|
|
- 'auto'
|
|
|
|
|
|
2016-02-09 23:59:37 +03:00
|
|
|
|
# Extensions
|
|
|
|
|
markdown_extensions:
|
|
|
|
|
- admonition
|
2017-10-16 20:13:05 +03:00
|
|
|
|
- codehilite:
|
|
|
|
|
guess_lang: false
|
|
|
|
|
- toc:
|
|
|
|
|
permalink: true
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|