Commit df441033 authored by Alexander Martinez's avatar Alexander Martinez
Browse files


parent 24f647d5
Pipeline #1182 failed with stages
in 1 minute and 45 seconds
template: overrides/main.html
title: Getting started
# Getting started
Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
towards (technical) project documentation. If you're familiar with Python, you
can install Material for MkDocs with [`pip`][2], the Python package manager.
If not, we recommended using [`docker`][3].
In case you're running into problems, consult the [troubleshooting][4] section.
[2]: #with-pip
[3]: #with-docker
## Installation
### with pip
Material for MkDocs can be installed with `pip`:
pip install mkdocs-material
This will automatically install compatible versions of all dependencies:
[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7].
Material for MkDocs always strives to support the latest versions, so there's
no need to install those packages separately.
### with docker
The official [Docker image][8] is a great way to get up and running in a few
minutes, as it comes with all dependencies pre-installed. Pull the image for the
`latest` version with:
docker pull squidfunk/mkdocs-material
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][9]
- [mkdocs-redirects][10]
??? question "How to add plugins to the Docker image?"
Material for MkDocs bundles useful and common plugins while trying not to
blow up the size of the official image. If the plugin you want to use is
not included, create a new `Dockerfile` and extend the official Docker image
with your custom installation routine:
``` Dockerfile
FROM squidfunk/mkdocs-material
RUN pip install ...
Next, you can build the image with the following command:
docker build -t squidfunk/mkdocs-material .
The new image can be used exactly like the official image.
### with git
Material for MkDocs can be directly used from [GitHub][11] 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
The theme will reside in the folder `mkdocs-material/material`. When cloning
from `git`, you must install all required dependencies yourself:
pip install -r mkdocs-material/requirements.txt
template: overrides/home.html
title: Material for MkDocs
template: overrides/main.html
# Changelog
## Material for MkDocs Insiders
### 2.6.0 <small>_ April 11, 2021</small>
- Stay on page when switching versions
### 2.5.0 <small>_ March 28, 2021</small>
- Added support for version warning
### 2.4.0 <small>_ March 20, 2021</small>
- Added support for custom admonition icons
- Fixed #2444: Code block annotations with extra comments have wrong index
### 2.3.1 <small>_ March 14, 2021</small>
- Fixed anchor offset for permalinks when using sticky navigation tabs
### 2.3.0 <small>_ March 13, 2021</small>
- Added support for back-to-top button
### 2.2.1 <small>_ March 4, 2021</small>
- Fixed #2382: Repository stats failing when no release tag is present
### 2.2.0 <small>_ February 28, 2021</small>
- Added support for code block annotations
### 2.1.0 <small>_ February 26, 2021</small>
- Added support for anchor tracking
### 2.0.0 <small>_ February 24, 2021</small>
- Migrated Insiders to the new architecture
- Swapped color palette toggle configuration
### 1.17.0 <small>_ January 31, 2021</small>
- Added support for section index pages
### 1.16.1 <small>_ January 26, 2021</small>
- Fixed #2249: Instant loading + sticky tabs result in invalid links
- Fixed #2248: Search highlighting URL parameter always added
- Fixed #2235: Version selector doesn't select current version for aliases
### 1.16.0 <small>_ January 7, 2021</small>
- Added latest release to repository info (GitHub)
- Slight facelift of repository info (lighter fonts, spacing and icons)
### 1.15.0 <small>_ January 2, 2021</small>
- Added support for native Mermaid.js integration
### 1.14.0 <small>_ December 30, 2020</small>
- Added support for sharing searches
### 1.13.2 <small>_ December 22, 2020</small>
- Fixed version selector + sticky tabs navigation rendering issues
- Fixed version selector wrapping
### 1.13.1 <small>_ December 20, 2020</small>
- Removed horizontal scrollbars on language and version selector
- Fixed type conversion in JavaScript config
### 1.13.0 <small>_ December 13, 2020</small>
- Refactored navigation tabs to simplify grouping behavior
- Added support for sticky navigation tabs
- Added support for arbitrary links in navigation tabs
- Fixed #2098: Subsequent active subsection not highlighted correctly
### 1.12.1 <small>_ December 8, 2020</small>
- Fixed empty language selector being shown
### 1.12.0 <small>_ December 6, 2020</small>
- Added support for adding a language selector
### 1.11.2 <small>_ November 29, 2020</small>
- Fixed #2068: Search highlight interprets code blocks as JavaScript
### 1.11.1 <small>_ November 29, 2020</small>
- Refactored styling to be more stable and easier to adjust
- Fixed some styling regressions from latest features
### 1.11.0 <small>_ November 22, 2020</small>
- Added support for rendering admonitions as inline blocks
### 1.10.0 <small>_ November 15, 2020</small>
- Added support for integrating table of contents into navigation
### 1.9.0 <small>_ November 7, 2020</small>
- Added support for hiding navigation and table of contents on any page
- Removed autohiding table of contents when empty
### 1.8.0 <small>_ November 1, 2020</small>
- Added support for navigation sections
- Fixed appearance of inactive search suggestions
### 1.7.0 <small>_ October 25, 2020</small>
- Added support for deploying multiple versions
- Fixed alignment of sidebar when content area is too small
### 1.6.0 <small>_ October 11, 2020</small>
- Added support for search suggestions to save keystrokes
- Added support for removing __Made with Material for MkDocs__ from footer
- Fixed #1915: search should go to first result by pressing ++enter++
### 1.5.1 <small>_ September 21, 2020</small>
- Fixed content area stretching to whole width for long code blocks
### 1.5.0 <small>_ September 19, 2020</small>
- Added support for autohiding table of contents when empty
### 1.4.1 <small>_ September 6, 2020</small>
- Improved typeahead and search result relevance and scoring
### 1.4.0 <small>_ August 30, 2020</small>
- Added support for autohiding header on scroll
### 1.3.0 <small>_ August 26, 2020</small>
- Added support for user-selectable color palettes
### 1.2.0 <small>_ August 11, 2020</small>
- Added feature to expand navigation by default
### 1.1.0 <small>_ August 3, 2020</small>
- Added highlighting of search results
### 1.0.0 <small>_ July 14, 2020</small>
- Added grouping of search results
- Added missing query terms to search result
- Improved search result relevance and scoring
template: overrides/main.html
title: Switching to Insiders
# Switching to Insiders
Material for MkDocs Insiders is a fully compatible drop-in replacement for
Material for MkDocs, and can be installed similar to the public version using
[`pip`][1], [`docker`][2] or [`git`][3]. When you sponsor @squidfunk, your
account is added to the list of collaborators of the private Insiders
[1]: #with-pip
[2]: #with-docker
[3]: #with-git
## Requirements
In order to access the Insiders repository programmatically (from the command
line or GitHub Actions workflows), you need to create a [personal access
1. Go to
2. Click on [Generate a new token][5]
3. Enter a name and select the [`repo`][6] scope
4. Generate the token and store it in a safe place
## Installation
### with pip
Material for MkDocs Insiders can be installed with `pip`:
``` sh
pip install git+https://${GH_TOKEN}
The `GH_TOKEN` environment variable must be set to the value of the personal
access token you generated in the previous step. Note that the personal access
token must be kept secret at all times, as it allows the owner to access your
private repositories.
### with docker
In case you want to use Material for MkDocs Insiders from within Docker, some additional steps are necessary. While we cannot provide a hosted Docker image
for Insiders[^1], [GitHub Container Registry][7] allows for simple and
comfortable self-hosting:
1. [Fork the Insiders repository][8]
2. Enable [GitHub Actions][9] on your fork[^2]
3. Create a new personal access token[^3]
1. Go to
2. Click on [Generate a new token][5]
3. Enter a name and select the [`write:packages`][10] scope
4. Generate the token and store it in a safe place
4. Add a [GitHub Actions secret][11] on your fork
1. Set the name to `GHCR_TOKEN`
2. Set the value to the personal access token created in the previous step
5. [Create a new release][12] to build and publish the Docker image
6. Install [Pull App][13] on your fork to stay in-sync with upstream
The [`publish`][14] workflow[^4] is automatically run when a new tag (release)
is created. When a new Insiders version is released on the upstream repository,
the [Pull App][13] will create a pull request with the changes and pull in the
new tag, which is picked up by the [`publish`][14] workflow that builds and
publishes the Docker image automatically to your private registry.
Now, you should be able to pull the Docker image from your private registry:
docker login -u ${GH_USERNAME} -p ${GHCR_TOKEN}
docker pull${GH_USERNAME}/mkdocs-material-insiders
Earlier, Insiders provided a dedicated Docker image which was available to
all sponsors. On March 21, 2021, the image was deprecated for the reasons
outlined and discussed in #2442. It will be removed on June 1, 2021.
When forking a repository, GitHub will disables all workflows. While this
is a reasonable default setting, you need to enable GitHub Actions to be
able to automatically build and publish a Docker image on
[GitHub Container Registry][7].
While you could just add the `write:packages` scope to the personal access
token created to access the Insiders repository, it's safer to create a
dedicated token which you'll only use for publishing the Docker image.
The Insiders repository contains three GitHub Actions workflows:
- `build.yml` – Build and lint the project (disabled on forks)
- `documentation.yml` – Build and deploy the documentation (disabled on forks)
- `publish.yml` – Build and publish the Docker image
### with git
Of course, you can use Material for MkDocs Insiders directly from `git`:
git clone mkdocs-material
The theme will reside in the folder `mkdocs-material/material`. When cloning
from `git`, you must install all required dependencies yourself:
pip install -r mkdocs-material/requirements.txt
template: overrides/main.html
title: Insiders
# Insiders
Material for MkDocs follows the _sponsorware_ release strategy, which means
that _new features are first exclusively released to sponsors_ as part of
__Insiders__. Read on to learn [how sponsorship works][1], and how easy it is
to [get access to Insiders][2].
<figure class="mdx-video" markdown="1">
<div class="mdx-video__inner">
<iframe src="" allowfullscreen></iframe>
<figcaption markdown="1">
A demo is worth a thousand words — check it out at
[1]: #how-sponsorship-works
[2]: #how-to-become-a-sponsor
## How sponsorship works
New features first land in Insiders, which means that _sponsors will have access
immediately_. Every feature is tied to a funding goal in monthly subscriptions.
When a funding goal is hit, the features that are tied to it are merged back
into Material for MkDocs and released for general availability. Bugfixes are
always released simultaneously in both editions.[^1]
You may ask yourself why you should pay for something that is Open Source.
Doesn't that contradict the ethos of Open Source software? Yes and no. Yes,
some features are locked behind a monthly subscription, which means they are
only accessible when paying a small amount of money. No, the features are
only exclusive for a short time until specific funding goals are hit. Making
an Open Source project sustainable is exceptionally hard: maintainers burn
out, projects are abandoned. That's not great and very unpredictable. The
sponsorware model ensures that if you decide to use Material for MkDocs,
you can be sure that bugs are fixed quickly and new features are added
_Don't want to sponsor? No problem, Material for MkDocs already has tons of
features available, so chances are that most of your requirements are already
satisfied. See the [list of exclusive features][4] to learn which features are
currently only available to sponsors._
[4]: #exclusive-features
## How to become a sponsor
You can become a sponsor using your individual or organization's GitHub account.
Just visit __[squidfunk's sponsor profile][5]__, pick any tier __from
$10/month__, and complete the checkout. Then, after a few hours, @squidfunk will
add you as a collaborator to the super-secret private GitHub repositority
containing the Insiders edition, which contains all [brand new and exclusive
__Important__: If you're sponsoring @squidfunk through a GitHub organization,
please send a short email to with the name of your
organization and the account that should be added as a collaborator.[^2]
It's currently not possible to grant access to each member of an
organization, as GitHub only allows for adding users. Thus, after
sponsoring, please send an email to, stating which
account should become a collaborator of the Insiders repository. We're
working on a solution which will make access to organizations much simpler.
To ensure that access is not tied to a particular individual GitHub account,
create a bot account (i.e. a GitHub account that is not tied to a specific
individual), and use this account for the sponsoring. After being added to
the list of collaborators, the bot account can create a private fork of the
private Insiders GitHub repository, and grant access to all members of the
You can cancel your sponsorship anytime.[^3]
If you cancel your sponsorship, GitHub schedules a cancellation request
which will become effective at the end of the billing cycle, which ends at
the 22nd of a month for monthly sponsorships. This means that even though
you cancel your sponsorship, you will keep your access to Insiders as long
as your cancellation isn't effective. All charges are processed by GitHub
through Stripe. As we don't receive any information regarding your payment,
and GitHub doesn't offer refunds, sponsorships are non-refundable.
[:octicons-heart-fill-24:{ .mdx-heart } &nbsp; Join our <span class="mdx-sponsorship-count" data-mdx-component="sponsorship-count"></span> awesome sponsors][5]{ .md-button .md-button--primary .mdx-sponsorship-button }
<div class="mdx-sponsorship" data-mdx-component="sponsorship" hidden>
<div class="mdx-sponsorship__list"></div>
If you sponsor publicly, you're automatically added here with a link to
your profile and avatar to show your support for Material for MkDocs.
Alternatively, if you wish to keep your sponsorship private, you'll be a
silent +1. You can select visibility during checkout and change it
## Exclusive features
The following features are currently exclusively available to sponsors:
<div class="mdx-columns" markdown="1">
- [x] [Stay on page when switching versions :material-new-box:][28]
- [x] [Version warning :material-new-box:][26]
- [x] [Custom admonition icons :material-new-box:][28]
- [x] [Code block annotations][25]
- [x] [Anchor tracking ][24]
- [x] [Section index pages][22]
- [x] [Sticky navigation tabs][21]
- [x] [Mermaid.js integration][27]
- [x] [Search suggestions][18]
- [x] [Search highlighting][19]
- [x] [Search sharing][20]
- [x] [Remove generator notice][23]
_New features are added to this list every few weeks, so be sure to come back
from time to time to learn about what's new, or follow [@squidfunk on
:fontawesome-brands-twitter:{ .twitter } Twitter][6] to stay updated._
## Funding <span class="mdx-sponsorship-total" data-mdx-component="sponsorship-total"></span>
### Goals
Following is a list of funding goals. When a funding goal is hit, the features
that are tied to it are merged back into Material for MkDocs and released to
the public for general availability.
#### $ 2,500 – Biquinho Vermelho
- [x] [Search suggestions][18]
- [x] [Search highlighting][19]
- [x] [Search sharing][20]
[18]: ../setup/
[19]: ../setup/
[20]: ../setup/
#### $ 3,000 – Caribbean Red
- [x] [Sticky navigation tabs][21]
- [x] [Section index pages][22]
- [x] [Remove generator notice][23]
[21]: ../setup/
[22]: ../setup/
[23]: ../setup/
#### $ 4,000 – Ghost Pepper
- [x] [Anchor tracking][24]
- [x] [Code block annotations][25]
- [x] [Version warning][26]
[24]: ../setup/
[25]: ../reference/
[26]: ../setup/setting-up-versioning#version-warning
#### $ 5,000 – Aji Panca
- [x] [Mermaid.js integration][27]
- [x] [Stay on page when switching versions][28]
- [ ] List of last searches
[27]: ../reference/
[28]: ../setup/setting-up-versioning#stay-on-page
#### $ 6,000 – Trinidad Scorpion
- [ ] Improved search result summaries
- [ ] Table of contents shows which sections have search results
- [ ] Stay on page when switching languages
#### $ 7,000 – Royal Gold
- [ ] Table of contents auto-collapse
- [ ] Table of contents follows active anchor
- [ ] Native lightbox integration
#### $ 8,000 – Scotch Bonnet
- [x] [Custom admonition icons][29]
- [ ] TBA
- [ ] TBA
[29]: ../reference/
#### Future
- [ ] [Material for MkDocs Live Edit][30]
- [ ] New layouts and styles
- [ ] Code block palette toggle
### Goals completed
#### $ 2,000 – Black Pearl
- [x] Latest release tag
- [x] [Color palette toggle][16]
- [x] [Back-to-top button][17]
[16]: ../setup/
[17]: ../setup/
#### $ 1,500 – Bhut Jolokia
- [x] [Admonition inline blocks][12]
- [x] [Site language selection][13]
- [x] [Versioning][14]
[12]: ../reference/
[13]: ../setup/
[14]: ../setup/
#### $ 1,000 – Prairie Fire
- [x] [Navigation sections][7]