Getting started with Insiders¤

MkDocs Pygments Insiders is a compatible drop-in replacement for MkDocs Pygments, and can be installed similarly using pip or git. Note that in order to access the Insiders repository, you need to become an eligible sponsor of @pawamoy on GitHub.

Installation¤

with PyPI Insiders¤

PyPI Insiders is a tool that helps you keep up-to-date versions of Insiders projects in the PyPI index of your choice (self-hosted, Google registry, Artifactory, etc.).

See how to install it and how to use it.

with pip (ssh/https)¤

MkDocs Pygments Insiders can be installed with pip using SSH:

pip install git+ssh://git@github.com/pawamoy-insiders/mkdocs-pygments.git

Or using HTTPS:

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

How to get a GitHub personal access token

The GH_TOKEN environment variable is a GitHub token. It can be obtained by creating a personal access token for your GitHub account. It will give you access to 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

Note that the personal access token must be kept secret at all times, as it allows the owner to access your private repositories.

with pip (self-hosted)¤

Self-hosting the Insiders package makes it possible to depend on MkDocs Pygments normally, while transparently downloading and installing the Insiders version locally. It means that you can specify your dependencies normally, and your contributors without access to Insiders will get the public version, while you get the Insiders version on your machine.

Limitation

With this method, there is no way to force the installation of an Insiders version rather than a public version. If there is a public version that is more recent than your self-hosted Insiders version, the public version will take precedence. Remember to regularly update your self-hosted versions by uploading latest distributions.

You can build the distributions for Insiders yourself, by cloning the repository and using build to build the distributions, or you can download them from our GitHub Releases. You can upload these distributions to a private PyPI-like registry (Artifactory, Google Cloud, pypiserver, etc.) with Twine:

# download distributions in ~/dists, then upload with:
twine upload --repository-url https://your-private-index.com ~/dists/*

You might also need to provide a username and password/token to authenticate against the registry. Please check Twine's documentation.

You can then configure pip (or other tools) to look for packages into your package index. For example, with pip:

pip config set global.extra-index-url https://your-private-index.com/simple

Note that the URL might differ depending on whether your are uploading a package (with Twine) or installing a package (with pip), and depending on the registry you are using (Artifactory, Google Cloud, etc.). Please check the documentation of your registry to learn how to configure your environment.

We kindly ask that you do not upload the distributions to public registries, as it is against our Terms of use.

Full example with pypiserver

In this example we use pypiserver to serve a local PyPI index.

pip install --user pypiserver
# or pipx install pypiserver

# create a packages directory
mkdir -p ~/.local/pypiserver/packages

# run the pypi server without authentication
pypi-server run -p 8080 -a . -P . ~/.local/pypiserver/packages &

We can configure the credentials to access the server in ~/.pypirc:

.pypirc

[distutils]
index-servers =
    local

[local]
repository: http://localhost:8080
username:
password:

We then clone the Insiders repository, build distributions and upload them to our local server:

# clone the repository
git clone git@github.com:pawamoy-insiders/mkdocs-pygments
cd mkdocs-pygments

# install build
pip install --user build
# or pipx install build

# checkout latest tag
git checkout $(git describe --tags --abbrev=0)

# build the distributions
pyproject-build

# upload them to our local server
twine upload -r local dist/* --skip-existing

Finally, we configure pip, and for example PDM, to use our local index to find packages:

pip config set global.extra-index-url http://localhost:8080/simple
pdm config pypi.extra.url http://localhost:8080/simple

Now when running pip install mkdocs-pygments, or resolving dependencies with PDM, both tools will look into our local index and find the Insiders version. Remember to update your local index regularly!

with git¤

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

git clone git@github.com:pawamoy-insiders/mkdocs-pygments

When cloning from git, the package must be installed:

pip install -e mkdocs-pygments

Upgrading¤

When upgrading Insiders, you should always check the version of MkDocs Pygments which makes up the first part of the version qualifier. For example, a version like 8.x.x.4.x.x means that Insiders 4.x.x is currently based on 8.x.x.

If the major version increased, it's a good idea to consult the changelog and go through the steps to ensure your configuration is up to date and all necessary changes have been made.