2016-02-09 23:59:37 +03:00
|
|
|
|
# Getting started
|
|
|
|
|
|
2023-07-20 11:42:52 +03:00
|
|
|
|
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.
|
2020-07-16 23:31:39 +03:00
|
|
|
|
|
2021-10-10 23:32:32 +03:00
|
|
|
|
[MkDocs]: https://www.mkdocs.org
|
|
|
|
|
[pip]: #with-pip
|
|
|
|
|
[docker]: #with-docker
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2020-05-31 16:40:41 +03:00
|
|
|
|
## Installation
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2021-10-10 22:04:22 +03:00
|
|
|
|
### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }
|
2016-12-29 19:55:08 +03:00
|
|
|
|
|
2022-04-02 14:47:15 +03:00
|
|
|
|
Material for MkDocs is published as a [Python package] and can be installed with
|
2022-09-11 20:25:40 +03:00
|
|
|
|
`pip`, ideally by using a [virtual environment]. Open up a terminal and install
|
|
|
|
|
Material for MkDocs with:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2021-12-27 20:10:44 +03:00
|
|
|
|
=== "Latest"
|
|
|
|
|
|
|
|
|
|
``` sh
|
|
|
|
|
pip install mkdocs-material
|
|
|
|
|
```
|
|
|
|
|
|
2023-01-01 21:08:42 +03:00
|
|
|
|
=== "9.x"
|
2021-12-27 20:10:44 +03:00
|
|
|
|
|
|
|
|
|
``` sh
|
2023-01-01 21:08:42 +03:00
|
|
|
|
pip install mkdocs-material=="9.*" # (1)!
|
2021-12-27 20:10:44 +03:00
|
|
|
|
```
|
|
|
|
|
|
2023-07-20 11:42:52 +03:00
|
|
|
|
1. Material for MkDocs uses [semantic versioning][^2], which is why it's a
|
2021-12-27 20:10:44 +03:00
|
|
|
|
good idea to limit upgrades to the current major version.
|
|
|
|
|
|
|
|
|
|
This will make sure that you don't accidentally [upgrade to the next
|
2022-09-11 20:25:40 +03:00
|
|
|
|
major version], which may include breaking changes that silently corrupt
|
2021-12-27 20:10:44 +03:00
|
|
|
|
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
|
|
|
|
|
```
|
|
|
|
|
|
2023-07-20 11:42:52 +03:00
|
|
|
|
[^2]:
|
2021-12-27 20:10:44 +03:00
|
|
|
|
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.
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2020-05-31 16:40:41 +03:00
|
|
|
|
This will automatically install compatible versions of all dependencies:
|
2021-10-10 23:32:32 +03:00
|
|
|
|
[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.
|
2017-03-11 20:01:14 +03:00
|
|
|
|
|
2022-04-02 14:47:15 +03:00
|
|
|
|
---
|
|
|
|
|
|
2023-02-21 18:37:04 +03:00
|
|
|
|
:fontawesome-brands-youtube:{ style="color: #EE0F0F" }
|
|
|
|
|
__[How to set up Material for MkDocs]__ by @james-willett – :octicons-clock-24:
|
2023-05-08 11:25:09 +03:00
|
|
|
|
15m – Learn how to create and host a documentation site using Material for
|
|
|
|
|
MkDocs on GitHub Pages in a step-by-step guide.
|
2023-02-21 18:37:04 +03:00
|
|
|
|
|
|
|
|
|
[How to set up Material for MkDocs]: https://www.youtube.com/watch?v=Q-YA_dA8C20
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
2022-04-02 14:47:15 +03:00
|
|
|
|
__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
|
2021-12-27 20:10:44 +03:00
|
|
|
|
[semantic versioning]: https://semver.org/
|
|
|
|
|
[upgrade to the next major version]: upgrade.md
|
2021-10-10 23:32:32 +03:00
|
|
|
|
[Markdown]: https://python-markdown.github.io/
|
|
|
|
|
[Pygments]: https://pygments.org/
|
|
|
|
|
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
|
2022-04-02 14:47:15 +03:00
|
|
|
|
[Using Python's pip to Manage Your Projects' Dependencies]: https://realpython.com/what-is-pip/
|
2017-03-11 20:01:14 +03:00
|
|
|
|
|
2020-05-31 16:40:41 +03:00
|
|
|
|
### with docker
|
2017-03-11 20:01:14 +03:00
|
|
|
|
|
2021-10-10 23:32:32 +03:00
|
|
|
|
The official [Docker image] is a great way to get up and running in a few
|
2022-09-11 20:25:40 +03:00
|
|
|
|
minutes, as it comes with all dependencies pre-installed. Open up a terminal
|
|
|
|
|
and pull the image with:
|
2017-11-05 16:40:30 +03:00
|
|
|
|
|
2021-12-27 20:10:44 +03:00
|
|
|
|
=== "Latest"
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
docker pull squidfunk/mkdocs-material
|
|
|
|
|
```
|
|
|
|
|
|
2023-01-01 21:08:42 +03:00
|
|
|
|
=== "9.x"
|
2021-12-27 20:10:44 +03:00
|
|
|
|
|
|
|
|
|
```
|
2023-01-01 21:08:42 +03:00
|
|
|
|
docker pull squidfunk/mkdocs-material:9
|
2021-12-27 20:10:44 +03:00
|
|
|
|
```
|
2017-11-05 16:40:30 +03:00
|
|
|
|
|
2020-05-31 16:40:41 +03:00
|
|
|
|
The `mkdocs` executable is provided as an entry point and `serve` is the
|
2020-07-26 15:46:09 +03:00
|
|
|
|
default command. If you're not familiar with Docker don't worry, we have you
|
2020-05-31 16:40:41 +03:00
|
|
|
|
covered in the following sections.
|
2020-03-09 18:48:52 +03:00
|
|
|
|
|
2020-07-27 13:41:04 +03:00
|
|
|
|
The following plugins are bundled with the Docker image:
|
|
|
|
|
|
2021-10-10 23:32:32 +03:00
|
|
|
|
- [mkdocs-minify-plugin]
|
|
|
|
|
- [mkdocs-redirects]
|
2020-12-21 19:38:58 +03:00
|
|
|
|
|
2021-10-10 23:32:32 +03:00
|
|
|
|
[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
|
2017-11-05 16:40:30 +03:00
|
|
|
|
|
2020-12-21 19:38:58 +03:00
|
|
|
|
??? question "How to add plugins to the Docker image?"
|
2020-09-16 12:30:05 +03:00
|
|
|
|
|
2021-11-07 20:23:01 +03:00
|
|
|
|
Material for MkDocs only bundles selected plugins in order to keep the size
|
2023-08-01 15:05:13 +03:00
|
|
|
|
of the official image small. If the plugin you want to use is not included,
|
|
|
|
|
you can add them easily:
|
2020-09-16 12:30:05 +03:00
|
|
|
|
|
2023-08-01 15:05:13 +03:00
|
|
|
|
=== "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
|
|
|
|
|
```
|
2020-09-16 12:30:05 +03:00
|
|
|
|
|
2023-08-01 15:05:13 +03:00
|
|
|
|
Next, build the image with the following command:
|
2020-09-16 12:30:05 +03:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
docker build -t squidfunk/mkdocs-material .
|
|
|
|
|
```
|
|
|
|
|
|
2023-06-29 17:30:33 +03:00
|
|
|
|
The new image will have additional packages installed and can be used
|
|
|
|
|
exactly like the official image.
|
2020-09-16 12:30:05 +03:00
|
|
|
|
|
2020-03-09 18:48:52 +03:00
|
|
|
|
### with git
|
|
|
|
|
|
2021-10-10 23:32:32 +03:00
|
|
|
|
Material for MkDocs can be directly used from [GitHub] by cloning the
|
2020-03-09 18:48:52 +03:00
|
|
|
|
repository into a subfolder of your project root which might be useful if you
|
|
|
|
|
want to use the very latest version:
|
|
|
|
|
|
2021-03-21 16:04:29 +03:00
|
|
|
|
```
|
|
|
|
|
git clone https://github.com/squidfunk/mkdocs-material.git
|
|
|
|
|
```
|
2020-03-09 18:48:52 +03:00
|
|
|
|
|
2022-09-11 20:25:40 +03:00
|
|
|
|
The theme will reside in the folder `mkdocs-material/material`. After cloning
|
|
|
|
|
from `git`, you must install all required dependencies with:
|
2016-02-09 23:59:37 +03:00
|
|
|
|
|
2020-07-23 15:37:20 +03:00
|
|
|
|
```
|
2021-10-10 23:32:32 +03:00
|
|
|
|
pip install -e mkdocs-material
|
2016-02-09 23:59:37 +03:00
|
|
|
|
```
|
|
|
|
|
|
2021-10-10 23:32:32 +03:00
|
|
|
|
[GitHub]: https://github.com/squidfunk/mkdocs-material
|