mkdocs-git-committers-plugin-2

2.5.0 verified Mon Apr 27 auth: no python

An MkDocs plugin to create a list of contributors on the page. The plugin seeds the template context with a list of GitHub or GitLab committers and other useful GIT info such as last modified date. Current version is 2.5.0, with regular releases.

pip install mkdocs-git-committers-plugin-2

Common errors

error KeyError: 'api_version' ↓

cause Missing 'api_version' config option when using self-hosted GitHub/GitLab

fix

Add 'api_version: v3' (for GitHub) or 'api_version: v4' (for GitLab) to your mkdocs.yml under the plugin settings.

error UnboundLocalError: local variable 'user' referenced before assignment ↓

cause Bug in version 2.4.0 when using GitHub or GitLab without proper token/rate limit handling

fix

Upgrade to version 2.4.1 or later.

Warnings

gotcha The plugin requires an API token for GitLab in all cases; for GitHub, unauthenticated requests are allowed but rate-limited to 60 calls/hour. You must provide a token for private repos or higher rate limits. ↓

fix Set an environment variable (e.g. GH_TOKEN or GITLAB_TOKEN) and reference it in mkdocs.yml via !ENV or !!python/name.

breaking From version 2.1.0, the plugin switched from GraphQL API back to REST API for both GitHub and GitLab. This may affect users who were relying on GraphQL-specific behavior. ↓

fix No code change required; the plugin automatically uses REST API. Ensure your token has appropriate REST API permissions.

deprecated The configuration option 'docs_path' is deprecated; the plugin now automatically searches parent directories for the Git repository. ↓

fix Remove 'docs_path' from your mkdocs.yml.

Quickstart

Add the plugin to your MkDocs config. The 'repository' field is required, and a token is recommended for GitHub to avoid rate limiting.

# In mkdocs.yml:
# plugins:
#   - git-committers:
#       repository: owner/repo
#       branch: main
#       token: !!python/name:os.environ.get('GH_TOKEN','')