mkdocs-material/docs/insiders/getting-started.md

template	title
overrides/main.html	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, docker or git. When you sponsor @squidfunk, your account is added to the list of collaborators of the private Insiders repository.

Requirements

In order to access the Insiders repository programmatically (from the command line or GitHub Actions workflows), you need to create a personal access token:

1. Go to https://github.com/settings/tokens
2. Click on Generate a new token
3. Enter a name and select the repo scope
4. Generate the token and store it in a safe place

Installation

with pip

Material for MkDocs Insiders can be installed with pip:

pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git

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¹, GitHub Container Registry allows for simple and comfortable self-hosting:

1. Fork the Insiders repository
2. Enable GitHub Actions on your fork²
3. Create a new personal access token³
   1. Go to https://github.com/settings/tokens
   2. Click on Generate a new token
   3. Enter a name and select the write:packages scope
   4. Generate the token and store it in a safe place
4. Add a GitHub Actions secret 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 to build and publish the Docker image
6. Install Pull App on your fork to stay in-sync with upstream

The publish 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 publish 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

with git

Of course, you can use Material for MkDocs Insiders directly from git:

git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material

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:

pip install -e mkdocs-material

---

1. 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. ↩︎

2. 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. ↩︎

3. 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. ↩︎

4. 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
   ↩︎