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.
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" |
last_modified_time |
Whether to display the last modified time for each page. | bool |
True |
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 |
"" |
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.
Adding information with txt files¶
In some cases contributors information cannot be obtained from Git history:
for example following a history rewrite, or because contributors for a page
are not competent in Git, and contributed in ways that are not visible in the
commit history. For these situations, the contribs plugin supports adding more
information using *.contribs.txt
files, with a structure like the following:
# Comment
Charlie Brown <charlie.brown@peanuts.com> (3)
Sally Brown <sally.brown@peanuts.com> (1)
Roberto Prevato <roberto.prevato@gmail.com> (10)
The name of the .txt files must match the name of the page:
example.md
example.contribs.txt
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: 2025-04-17 07:04:37