Getting started with Insiders¶

Material for MkDocs Insiders is a compatible drop-in replacement for Material for MkDocs, and can be installed similarily 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):

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 [email protected]: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

Upgrading¶

When upgrading Insiders, you should always check the version of Material for MkDocs which makes up the first part of the version qualifier, e.g.Insiders 4.x.x is currently based on 8.x.x:

8.x.x-insiders-4.x.x

If the major version increased, it's a good idea to consult the upgrade guide and go through the steps to ensure your configuration is up to date and all necessary changes have been made. If you installed Insiders via pip, you can upgrade your installation with the following command:

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

Caveats¶

This sections describes some aspects to consider when using Insiders together with Material for MkDocs to ensure that users without access to Insiders can still build your documentation.

Built-in plugins¶

When using built-in plugins that are solely available via Insiders, it might be necessary to split the mkdocs.yml configuration into a base configuration, and one with plugin overrides. Note that this is a limitation of MkDocs, which can be mitigated by using configuration inheritance:

INHERIT: mkdocs.yml
plugins:
  - search
  - social
  - tags

# Configuration with everything except Insiders plugins

Now, when you're in an environment with access to Insiders (e.g. in your CI pipeline), you can build your documentation project with the following lines:

mkdocs build --config-file mkdocs.insiders.yml

INHERIT: mkdocs.yml
plugins:
  social: {}

# Additional configuration above
plugins:
  search: {}
  tags: {}