1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
# Getting started
Material for MkDocs is a powerful documentation framework on top of [MkDocs],
a static site generator for project documentation.[^1] If you're familiar with
Python, you can install Material for MkDocs with [`pip`][pip], the Python
package manager. If not, we recommend using [`docker`][docker].
[^1]:
In 2016, Material for MkDocs started out as a simple theme for MkDocs, but
over the course of several years, it's now much more than that – with the
many built-in plugins, settings, and countless customization abilities,
Material for MkDocs is now one of the simplest and most powerful frameworks
for creating documentation for your project.
[MkDocs]: https://www.mkdocs.org
[pip]: #with-pip
[docker]: #with-docker
## Installation
### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }
Material for MkDocs is published as a [Python package] and can be installed with
`pip`, ideally by using a [virtual environment]. Open up a terminal and install
Material for MkDocs with:
=== "Latest"
``` sh
pip install mkdocs-material
```
=== "9.x"
``` sh
pip install mkdocs-material=="9.*" # (1)!
```
1. Material for MkDocs uses [semantic versioning][^2], which is why it's a
good idea to limit upgrades to the current major version.
This will make sure that you don't accidentally [upgrade to the next
major version], which may include breaking changes that silently corrupt
your site. Additionally, you can use `pip freeze` to create a lockfile,
so builds are reproducible at all times:
```
pip freeze > requirements.txt
```
Now, the lockfile can be used for installation:
```
pip install -r requirements.txt
```
[^2]:
Note that improvements of existing features are sometimes released as
patch releases, like for example improved rendering of content tabs, as
they're not considered to be new features.
This will automatically install compatible versions of all dependencies:
[MkDocs], [Markdown], [Pygments] and [Python Markdown Extensions]. Material for
MkDocs always strives to support the latest versions, so there's no need to
install those packages separately.
---
:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
__[How to set up Material for MkDocs]__ by @james-willett – :octicons-clock-24:
27m – Learn how to create and host a documentation site using Material for
MkDocs on GitHub Pages in a step-by-step guide.
[How to set up Material for MkDocs]: https://www.youtube.com/watch?v=xlABhbnNrfI
---
!!! tip
If you don't have prior experience with Python, we recommend reading
[Using Python's pip to Manage Your Projects' Dependencies], which is a
really good introduction on the mechanics of Python package management and
helps you troubleshoot if you run into errors.
[Python package]: https://pypi.org/project/mkdocs-material/
[virtual environment]: https://realpython.com/what-is-pip/#using-pip-in-a-python-virtual-environment
[semantic versioning]: https://semver.org/
[upgrade to the next major version]: upgrade.md
[Markdown]: https://python-markdown.github.io/
[Pygments]: https://pygments.org/
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
[Using Python's pip to Manage Your Projects' Dependencies]: https://realpython.com/what-is-pip/
### with docker
The official [Docker image] is a great way to get up and running in a few
minutes, as it comes with all dependencies pre-installed. Open up a terminal
and pull the image with:
=== "Latest"
```
docker pull squidfunk/mkdocs-material
```
=== "9.x"
```
docker pull squidfunk/mkdocs-material:9
```
The `mkdocs` executable is provided as an entry point and `serve` is the
default command. If you're not familiar with Docker don't worry, we have you
covered in the following sections.
The following plugins are bundled with the Docker image:
- [mkdocs-minify-plugin]
- [mkdocs-redirects]
[Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin
[mkdocs-redirects]: https://github.com/datarobot/mkdocs-redirects
???+ warning
The Docker container is intended for local previewing purposes only and
is not suitable for deployment. This is because the web server used by
MkDocs for live previews is not designed for production use and may have
security vulnerabilities.
??? question "How to add plugins to the Docker image?"
Material for MkDocs only bundles selected plugins in order to keep the size
of the official image small. If the plugin you want to use is not included,
you can add them easily:
=== "Material for MkDocs"
Create a `Dockerfile` and extend the official image:
``` Dockerfile title="Dockerfile"
FROM squidfunk/mkdocs-material
RUN pip install mkdocs-macros-plugin
RUN pip install mkdocs-glightbox
```
=== "Insiders"
Clone or fork the Insiders repository, and create a file called
`user-requirements.txt` in the root of the repository. Then, add the
plugins that should be installed to the file, e.g.:
``` txt title="user-requirements.txt"
mkdocs-macros-plugin
mkdocs-glightbox
```
Next, build the image with the following command:
```
docker build -t squidfunk/mkdocs-material .
```
The new image will have additional packages installed and can be used
exactly like the official image.
### with git
Material for MkDocs can be directly used from [GitHub] by cloning the
repository into a subfolder of your project root which might be useful if you
want to use the very latest version:
```
git clone https://github.com/squidfunk/mkdocs-material.git
```
Next, install the theme and its dependencies with:
```
pip install -e mkdocs-material
```
[GitHub]: https://github.com/squidfunk/mkdocs-material
|
