Skip to content

Contribs

The contribs extension provides a plugin to display information about contributors and last commit time for each page. It works using the git CLI to obtain information from the same repository where the MkDocs site is built. It doesn't require any communication with third party services, but it requires running in a Git repository.

Git support only

This plugin works only with Git repositories, and since it obtains information from the git repository that contains the MkDocs site, it is designed for scenarios in which the documentation is built in CI/CD jobs.

This plugin doesn't require any markup code: it modifies each page to include contributors' list and last commit time affecting the file, and it doesn't require integration with any external API.

How to use

Install using pip install neoteroi-mkdocs. Edit your mkdocs.yml file to include the extra CSS file from Neoteroi mkdocs-plugins and the neoteroi.contribs plugin for MkDocs:

extra_css:
  - css/neoteroi-mkdocs.css
  ...

plugins:
  - search
  - neoteroi.contribs

Information

The plugin displays the last modified time for each file (the last time a file was modified in the Git repository), and the list of contributors, sorted by commits count.

Contribs example

Options

Name Description Type Default
contributors_label The label text for contributors list. str "Contributors"
last_modified_label The label text for last modified time. str "Last modified on"
show_last_modified_time Whether to display the last modified time for each page. bool True
show_contributors_title Whether to display an element with the "contributors_label" and the count of contributors. bool False
time_format Format to be used for dates. str "%Y-%m-%d %H:%M:%S"
contributors Information about contributors, use to configure images for contributors. list of contributor objects []

The plugin by default displays dots with the first two initials of each committer's name, displaying pictures requires explicit configuration, described below.

Contributor object

The following table describes the objects that can be used to provide more information about contributors.

Property Description Type Default
email Email address used to match a contributor. str n/a
image URL to be used as image for the contributor. str ""
merge_with If provided, lets merge together contributions from two different accounts. str or None None
ignore Hides contributions from a certain account, by email address. bool False

The merge_with option lets merge the contributions from two different accounts, for scenarios in which the same person commits using more than one email address. In the following example, foo-alt@example.org is not displayed, but its contributions count is added to the entry for foo@example.org:

contributors:
    - email: foo@example.org
    - email: foo-alt@example.org
      merge_with: foo@example.org

Including contributors' pictures

To configure images for contributors, use the contributors option like in the following example:

  - neoteroi.contribs:
      contributors:
        - email: roberto.prevato@gmail.com
          image: https://avatars.githubusercontent.com/u/2576032?s=400&u=d8d880e8ed05bb170877dd3d561d8301c4beeeed&v=4

Contributors are matched by email address, and the image is used if configured.

Under the hood

This plugin works by using the following git commands, to obtain contributors and the last modified time of a file:

git shortlog --summary --numbered --email "README.md"

git log -1 --pretty="format:%ci" "README.md"
Last modified on: 2022-10-01 10:15:52