Getting started with Insiders¶
Material for MkDocs Insiders is a compatible drop-in replacement for Material for MkDocs, and can be installed similarly using pip
, docker
or git
. Note that in order to access the Insiders repository, you need to become an eligible sponsor of @squidfunk on GitHub.
Requirements¶
After you've been added to the list of collaborators and accepted the repository invitation, the next step is to create a personal access token for your GitHub account in order to access the Insiders repository programmatically (from the command line or GitHub Actions workflows):
- Go to https://github.com/settings/tokens
- Click on Generate a new token
- Enter a name and select the
repo
scope - Generate the token and store it in a safe place
Some of the instructions below require that the GH_TOKEN
environment variable is 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.
Installation¶
with pip¶
Material for MkDocs Insiders can be installed with pip
. You will normally want to install the latest release but can also install a specific older release or even the latest development version. Make sure you have the GH_TOKEN
variable set as instructed above.
Pick the corresponding tag from the list of tags for the Insiders repository. In the pip
command below, replace the tag at the end of the URL with the one you want.
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 Insiders1, GitHub Container Registry allows for simple and comfortable self-hosting:
- Fork the Insiders repository
- Enable GitHub Actions on your fork2
- Create a new personal access token3
- Go to https://github.com/settings/tokens
- Click on Generate a new token
- Enter a name and select the
write:packages
scope - Generate the token and store it in a safe place
- Add a GitHub Actions secret on your fork
- Set the name to
GHCR_TOKEN
- Set the value to the personal access token created in the previous step
- Set the name to
- Create a new release to build and publish the Docker image
- Install Pull App on your fork to stay in-sync with upstream
The build
workflow is automatically run when a new tag (release) is created. When a new Insiders version is released on the upstream repository, the Pull App will create a pull request with the changes and pull in the new tag, which is picked up by the build
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} ghcr.io
docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders
Should you wish to add additional plugins to the insiders container image, follow the steps outlined in the Getting Started guide.
with git¶
Of course, you can use Material for MkDocs Insiders directly from git
:
The theme will reside in the folder mkdocs-material/material
. When cloning from git
, the theme must be installed, so MkDocs can find the built-in plugins:
Built-in plugins¶
When you're using built-in plugins that are solely available via Insiders, outside contributors won't be able to build your documentation project on their local machine. This is the reason why we developed the built-in group plugin that allows to conditionally load plugins:
plugins:
- search
- social
# CI=1 mkdocs build
- group:
enabled: !ENV CI
plugins:
- git-revision-date-localized
- git-committers
# INSIDERS=1 mkdocs build
- group:
enabled: !ENV INSIDERS
plugins:
- optimize
- privacy
Of course, you can also enable both groups with:
-
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 was removed on June 1, 2021. ↩
-
When forking a repository, GitHub will disable 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. ↩
-
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. ↩