mkdocs-material/docs/getting-started.md

556 lines
17 KiB
Markdown
Raw Normal View History

2016-02-09 23:59:37 +03:00
# Getting started
## Installation
!!! tip "Set up Material using Docker"
The official [Docker image][1] for Material comes with all dependencies
pre-installed and ready-to-use with the latest version published on PyPI,
2017-10-20 10:37:18 +03:00
packaged in a very small image (35MB compressed).
[1]: https://hub.docker.com/r/squidfunk/mkdocs-material/
2016-02-09 23:59:37 +03:00
### Installing MkDocs
2017-01-12 22:15:30 +03:00
Before installing [MkDocs][2], you need to make sure you have Python and `pip`
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
# Python 2.7.13
2016-02-09 23:59:37 +03:00
pip --version
# 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
# mkdocs, version 0.16.0
2016-02-09 23:59:37 +03:00
```
2017-01-15 13:24:32 +03:00
!!! warning "MkDocs version requirements"
Material requires MkDocs >= 0.16.
2017-01-12 22:15:30 +03:00
[2]: http://www.mkdocs.org
2016-02-09 23:59:37 +03:00
### Installing Material
#### using pip
Material can be installed with `pip`:
2016-02-09 23:59:37 +03:00
``` sh
pip install mkdocs-material
```
#### using choco
2017-06-21 11:25:00 +03:00
If you're on Windows you can use [Chocolatey][3] to install [Material][4]:
``` dos
choco install mkdocs-material
```
2017-06-21 11:25:00 +03:00
This will install all required dependencies like [Python][5] and [MkDocs][6].
2017-06-21 11:25:00 +03:00
[3]: https://chocolatey.org
[4]: https://chocolatey.org/packages/mkdocs-material
[5]: https://chocolatey.org/packages/python
[6]: https://chocolatey.org/packages/mkdocs
#### cloning from GitHub
2017-01-12 22:15:30 +03:00
Material can also be used without a system-wide installation by cloning the
repository into a subfolder of your project's root directory:
2016-02-09 23:59:37 +03:00
``` sh
git clone https://github.com/squidfunk/mkdocs-material.git
2016-02-09 23:59:37 +03:00
```
2017-06-21 11:25:00 +03:00
This is especially useful if you want to [extend the theme][7] and
[override some parts][8] of the theme. The theme will reside in the folder
`mkdocs-material/material`.
2017-06-21 11:25:00 +03:00
[7]: customization.md#extending-the-theme
[8]: 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
2017-03-11 20:36:34 +03:00
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'"
2017-03-11 20:36:34 +03:00
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
2017-08-29 09:17:26 +03:00
locations. MkDocs only checks its install location for themes.
## Usage
2017-06-21 11:25:00 +03:00
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:
2016-02-09 23:59:37 +03:00
``` yaml
theme: 'material'
```
2017-01-12 22:15:30 +03:00
If you cloned Material from GitHub:
2016-02-09 23:59:37 +03:00
``` yaml
theme_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,
or read on and customize the theme through some options.
[9]: http://localhost:8000
2016-02-09 23:59:37 +03:00
## Options
The Material theme adds some extra variables for configuration via your
2017-03-11 20:36:34 +03:00
project's `mkdocs.yml`. See the following sections for all available options.
2016-02-09 23:59:37 +03:00
2016-02-24 19:31:01 +03:00
### Changing the color palette
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
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
extra:
palette:
primary: 'indigo'
accent: 'light blue'
```
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`,
`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
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.
[10]: http://www.materialui.co/colors
[11]: customization.md
#### Primary colors
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>
<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
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
2016-02-17 20:08:11 +03:00
### Changing the font family
2016-02-09 23:59:37 +03:00
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
extra:
2016-02-17 20:08:11 +03:00
font:
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
extra:
2017-03-11 20:36:34 +03:00
font: false
2016-02-09 23:59:37 +03:00
```
[12]: https://fonts.google.com/specimen/Roboto
2017-02-25 00:53:12 +03:00
[13]: https://fonts.google.com
[14]: https://fonts.google.com/specimen/Ubuntu
### 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: 'my-github-handle/my-project'
repo_url: 'https://github.com/my-github-handle/my-project'
```
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.
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.
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`.
2017-10-13 16:32:28 +03:00
!!! 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
2017-03-11 20:36:34 +03:00
`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][15] on more
guidance regarding the `edit_uri` attribute, which defines whether the edit
button is shown or not.
[15]: http://www.mkdocs.org/user-guide/configuration/#edit_uri
### Adding a favicon
2017-06-21 11:25:00 +03:00
A favicon can be added by setting the `site_favicon` variable to an `.ico` or
image file:
``` yaml
site_favicon: 'images/favicon.ico'
```
### Adding a logo
2016-02-24 19:31:01 +03:00
2017-06-21 11:25:00 +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:
2016-02-24 19:31:01 +03:00
``` yaml
extra:
logo: 'images/logo.svg'
2016-02-24 19:31:01 +03:00
```
Additionally, the default icon can be changed by setting an arbitrary ligature
(or Unicode code point) from the [Material Design icon font][16], e.g.
``` yaml
extra:
logo:
icon: 'cloud'
```
[16]: https://material.io/icons/
### 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
automatically included [FontAwesome][17] 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:
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`.
[17]: http://fontawesome.io/icons/
### 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`:
``` yaml
google_analytics:
- 'UA-XXXXXXXX-X'
- 'auto'
```
2017-02-25 00:53:12 +03:00
### Disqus integation
Material for MkDocs is integrated with [Disqus][18], 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:
disqus: 'your-disqus-shortname'
```
The comments section is inserted in *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.
2017-02-25 00:53:12 +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
load properly.
[18]: https://disqus.com
2017-02-25 00:53:12 +03:00
### Localization
2017-01-07 20:54:03 +03:00
#### Translations
Material for MkDocs supports internationalization (i18n) and provides
2017-10-20 05:44:15 +03:00
translations for all template variables and labels in English `en`, Danish `da`
and German `de`. Specify the language with:
2017-01-07 20:54:03 +03:00
``` yaml
extra:
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][19] and adjust
all translations:
``` sh
cp partials/language/en.html partials/language/jp.html
2017-01-07 20:54:03 +03:00
```
Feel free to contribute your localization to Material for MkDocs by opening a
Pull Request.
2017-06-21 11:25:00 +03:00
[19]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
#### Site search
Site search is implemented using [lunr.js][20], which includes stemmers for the
2017-06-21 11:25:00 +03:00
English language by default, while stemmers for other languages are included
with [lunr-languages][21], both of which are integrated with this theme. Support
for other languages and even multilingual search can be activated in your
project's `mkdocs.yml`:
``` yaml
extra:
language:
- 'en'
- 'de'
- 'ru'
```
The first language specified is used as the document language as described in
the section above. All other languages are used only for stemming. This will
automatically load the stemmers for the specified languages and set them up
with site search.
At the time of writing, the following languages are supported: English `en`,
French `fr`, German `de`, Spanish `es`, Italian `it`, Japanese `jp`, Dutch `du`,
Danish `da`, Portguese `pt`, Finnish `fi`, Romanian `ro`, Hungarian `hu`,
Russian `ru`, Norwegian `no`, Swedish `sv` and Turkish `tr`.
!!! warning "Only specify the languages you really need"
2017-10-18 19:14:09 +03:00
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 `.`. This can be done by
overriding `partials/language.html`:
2017-08-02 15:31:23 +03:00
``` jinja
{% macro t(key) %}{{ {
...
"search.tokenizer": "[\s\-\.]+",
...
}[key] or lang.t(key) }}{% endmacro %}
2017-08-02 15:31:23 +03:00
```
[20]: https://lunrjs.com
[21]: https://github.com/MihaiValentin/lunr-languages
2017-01-07 20:54:03 +03:00
### Tabs
From version 1.1.0 on, Material supports another layer on top of the main
navigation for larger screens in the form of tabs. This is especially useful
2017-06-21 11:25:00 +03:00
for larger documentation projects with only few top-level sections. Tabs can be
enabled by setting the respective feature flag to true:
``` yaml
extra:
feature:
tabs: true
```
2016-02-09 23:59:37 +03:00
### More advanced customization
2016-02-24 19:31:01 +03:00
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
2016-02-09 23:59:37 +03:00
## Extensions
MkDocs supports several [Markdown extensions][23]. 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:
2016-02-09 23:59:37 +03:00
``` yaml
markdown_extensions:
- admonition
- codehilite:
guess_lang: false
- toc:
permalink: true
2016-02-09 23:59:37 +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
* [Admonition][24]
* [Codehilite][25]
* [Footnotes][26]
* [Metadata][27]
* [Permalinks][28]
* [PyMdown Extensions][29]
[23]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
[24]: extensions/admonition.md
[25]: extensions/codehilite.md
[26]: extensions/footnotes.md
[27]: extensions/metadata.md
[28]: extensions/permalinks.md
[29]: 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
site_name: 'My Project'
site_description: 'A short description of my project'
site_author: 'John Doe'
2017-06-21 11:25:00 +03:00
site_url: 'https://john-doe.github.io/my-project'
2016-02-09 23:59:37 +03:00
# Repository
repo_name: 'my-github-handle/my-project'
2017-06-21 11:25:00 +03:00
repo_url: 'https://github.com/john-doe/my-project'
2016-02-09 23:59:37 +03:00
# Copyright
2017-02-25 00:53:12 +03:00
copyright: 'Copyright &copy; 2016 - 2017 John Doe'
2016-02-09 23:59:37 +03:00
# Documentation and theme
theme: 'material'
# Options
extra:
language: 'en'
logo: 'images/logo.svg'
2016-02-24 19:31:01 +03:00
palette:
primary: 'indigo'
accent: 'indigo'
2016-02-17 20:08:11 +03:00
font:
text: 'Roboto'
code: 'Roboto Mono'
social:
- type: 'github'
2017-02-25 00:53:12 +03:00
link: 'https://github.com/john-doe'
- type: 'twitter'
2017-06-21 11:25:00 +03:00
link: 'https://twitter.com/john-doe'
- type: 'linkedin'
2017-07-20 15:32:02 +03:00
link: 'https://linkedin.com/in/john-doe'
2016-02-09 23:59:37 +03:00
# Google Analytics
google_analytics:
- 'UA-XXXXXXXX-X'
- 'auto'
2016-02-09 23:59:37 +03:00
# Extensions
markdown_extensions:
- admonition
- codehilite:
guess_lang: false
- toc:
permalink: true
2016-02-09 23:59:37 +03:00
```