MkDocs plugin for displaying a list of committers associated with a file in mkdocs. The plugin uses GitHub or GitLab API to fetch the list of contributors for each page.
🥳 NEW! Works with GitLab too!
For ease of use, this plugin is integrated in the material for mkdocs theme by Martin Donath. See Mkdocs material documentation.
Other MkDocs plugins that use information to fetch authors:
mkdocs-git-authors-plugin for displaying user names a number of lines contributed (uses local Git information)mkdocs-git-committers-plugin display contributors for a page (uses local Git information, completed with REST GitHub API v3)Install the plugin using pip:
pip install mkdocs-git-committers-plugin-2
Activate the plugin in mkdocs.yml:
For a repository hosted on GitHub:
plugins:
- git-committers:
repository: organization/repositoryFor a repository hosted on GitLab:
plugins:
- git-committers:
gitlab_repository: 12345678
token: !ENV ["CI_JOB_TOKEN"]For a repository hosted on GitLab, you need to provide a token so that the
plugin can access the GitLab API. If the token is not set in mkdocs.yml it
will be read from the MKDOCS_GIT_COMMITTERS_APIKEY environment variable.
For a repository hosted on GitHub, you can provide a token to increase the rate limit and go beyond the default 60 requests per hour per IP address. The plugin will make one request per mkdocs document. The token does not need any scope: uncheck everything when creating the GitHub Token at github.com/settings/personal-access-tokens/new, unless you access private repositories.
For private GitHub repositories, you only need to allow read-only access to Contents and Metadata on the target repository. This could be done by setting Read-only access of Permissions > Repository permissions > Contents.
enabled - Disables plugin if set to False for e.g. local builds (default: True)repository - For GitHub, the name of the repository, e.g.
'ojacques/mkdocs-git-committers-plugin-2'gitlab_repository - For GitLab, the project ID, e.g. '12345678'branch - The name of the branch to get contributors from. Example: 'master'
(default)token - A GitHub or GitLab personal access token for REST API calls.
read_api is expected to work. That way, the token is limited to
the project and has access to read the repository. You could use a personal
access token at
gitlab.com/-/profile/personal_access_tokens,
but it will grant access to more repositories than you want.enterprise_hostname - For GitHub enterprise: the GitHub enterprise hostname.gitlab_hostname - For GitLab: the GitLab hostname if different from
gitlab.com (self-hosted).api_version - For GitHub and GitLab self-hosted, the API version part that needs to be appended to the URL.
Defaults to v4 for GitLab, and nothing for GitHub Enterprise (you may need v3).docs_path - the path to the documentation folder. Defaults to docs/.cache_dir - The path which holds the authors cache file to speed up
documentation builds. Defaults to .cache/plugin/git-committers/. The cache
file is named page-authors.json.exclude - Specify a list of page source paths (one per line) that should not
have author(s) or last commit date included (excluded from processing by this
plugin). Default is empty. Examples:
# mkdocs.yml
plugins:
- git-committers:
repository: organization/repository
exclude:
- README.md
- subfolder/page.md
- another_page.md
- all_files_inside_folder/*
- folder_and_subfolders/**This is a fork from the original mkdocs-git-committers-plugin by @byrnereese.
I had to create this fork so that it could be uploaded and distributed through PyPi. The package has been renamed to mkdocs-git-committers-plugin-2.
This "v2" differs from the original by:
All of the above improves accuracy and performances.
Note: the plugin configuration in mkdocs.yml still uses the original git-committers sections.
You have 2 options to use this plugin:
In addition to displaying a list of committers for a file, you can also access the last commit date for a page if you want to display the date the file was last updated.
<ul class="metadata page-metadata" data-bi-name="page info" lang="en-us" dir="ltr">
<li class="last-updated-holder displayDate loading">
<span class="last-updated-text">Last updated:</span>
<time role="presentation" datetime="2018-10-25T00:00:00.000Z" data-article-date-source="ms.date">{% if last_commit_date %}{{ last_commit_date }}{% endif %}</time>
</li>
</ul>The avatar of the contributors is provided by GitHub. It uses maximal resolution.
{% block footer %}
<ul class="metadata page-metadata" data-bi-name="page info" lang="en-us" dir="ltr">
<li class="contributors-holder">
<span class="contributors-text">Contributors</span>
<ul class="contributors" data-bi-name="contributors">
{%- for user in committers -%}
<li><a href="https://github.com/ojacques/mkdocs-git-committers-plugin-2/blob/master/{{ user.url }}" title="{{ user.name }}" data-bi-name="contributorprofile" target="_blank"><img src="https://github.com/ojacques/mkdocs-git-committers-plugin-2/raw/master/{{ user.avatar }}" alt="{{ user.name }}"></a></li>
{%- endfor -%}
</ul>
</li>
</ul>
{% endblock %}.metadata{
list-style:none;
padding:0;
margin:0;
margin-bottom: 15px;
color: #999;
font-size:0.85em;
}
.metadata.page-metadata .contributors-text{
margin-right:5px
}
body[dir=rtl] .metadata.page-metadata .contributors-text{
margin-right:0;
margin-left:5px
}
.page-metadata .contributors{
display:inline-block;
list-style:none;
margin:0!important;
padding:0!important
}
.page-metadata .contributors li{
display:inline-block;
vertical-align:top;
margin:0;
padding:0
} $( '.contributors img[data-src]' ).each( function() {
src = $(this).attr("data-src");
$(this).attr('src',src);
});More information about templates here.
More information about blocks here.
Thank you to the following contributors: