Mkdocs Git Authors Plugin

Warnings

• breaking Python 3.7 support was dropped in version 0.8.0. Users on Python 3.7 or older must upgrade to Python 3.8+ to use this version and newer releases.
  Fix: Upgrade your Python environment to 3.8 or higher.
• gotcha For CI/CD environments (e.g., GitHub Actions, GitLab CI, Bitbucket Pipelines), you must configure your git clone/fetch depth to retrieve the full repository history (e.g., `fetch_depth: 0`, `GIT_DEPTH: 0`, `clone: depth: full`). The plugin needs the entire history to accurately determine authors.
  Fix: Adjust your CI/CD configuration for Git clone depth. Refer to the plugin's documentation for specific examples for different platforms.
• gotcha The `add_co_authors` option, introduced in v0.10.0, is disabled by default. If you wish to display git co-authors in addition to the primary commit author, you must explicitly set `add_co_authors: true` in your `mkdocs.yml`.
  Fix: Add `add_co_authors: true` under the `git-authors` plugin configuration in `mkdocs.yml`.
• gotcha When using `mkdocs-material` theme versions older than 9.5.0, deep integration requires manual template overrides to properly display and style the author information. Newer versions (>=9.5.0) have built-in support.
  Fix: Upgrade `mkdocs-material` to version 9.5.0 or higher, or follow the plugin's documentation for theme customization with template overrides.
• gotcha Previous versions (e.g., prior to v0.9.1, v0.9.3, v0.9.4) had known issues processing generated files or files located outside the `docs_dir`, potentially leading to errors or missing author information. Ensure you are on a recent version to benefit from these fixes.
  Fix: Upgrade to the latest version of `mkdocs-git-authors-plugin` (0.9.4 or higher) to resolve these issues.

Install

• pip install mkdocs-git-authors-plugin Install with pip

Imports

• GitAuthorsPlugin

  This plugin is enabled via mkdocs.yml configuration; no direct Python imports are typically used in user code. The internal entry point is 'mkdocs_git_authors_plugin.plugin:GitAuthorsPlugin'.

  MkDocs plugins are configured in mkdocs.yml and automatically loaded by the MkDocs build system.

Quickstart

To enable the plugin, add `git-authors` to the `plugins` section in your `mkdocs.yml` file. You can then use Jinja tags like `{{ git_page_authors }}` directly within your Markdown files or theme templates to display author information.

plugins:
  - search
  - git-authors:
      show_contribution: true
      show_email_address: true

# To display authors in your markdown pages (e.g., at the end of a page):
# Add {{ git_page_authors }} to your .md file or theme template.