Package: mkdocs-git-committers-plugin-2
mkdocs-git-committers-plugin-2MkDocs 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 thematerial for
mkdocstheme byMartin
Donath. SeeMkdocs material
documentation.Other MkDocs plugins that use information to fetch authors:mkdocs-git-authors-pluginfor displaying user names a number of lines contributed (uses local Git information)mkdocs-git-committers-plugindisplay contributors for a page (uses local Git information, completed with REST GitHub API v3)SetupInstall the plugin using pip:pip install mkdocs-git-committers-plugin-2Activate the plugin inmkdocs.yml:For a repository hosted on GitHub:plugins:-git-committers:repository:organization/repositoryFor a repository hosted on GitLab:plugins:-git-committers:gitlab_repository:12345678token:!ENV["GH_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 inmkdocs.ymlit
will be read from theMKDOCS_GIT_COMMITTERS_APIKEYenvironment 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 atgithub.com/settings/personal-access-tokens/new,
unless you access private repositories.Configenabled- Disables plugin if set toFalsefor 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.For GitHub, token does not need any scope: uncheck everything when creating
the GitHub Token atgithub.com/settings/personal-access-tokens/new,
unless you access private repositories.For GitLab, aproject access tokenscoped toread_apiis 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 atgitlab.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 needv3).docs_path- the path to the documentation folder. Defaults todocs.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 namedpage-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/**HistoryThis is a fork from the originalmkdocs-git-committers-pluginby @byrnereese.I had to create this fork so that it could be uploaded and distributed through PyPi. The package has been renamed tomkdocs-git-committers-plugin-2.This "v2" differs from the original by:Fetch contributors directly from GitHubEliminate the need to match git commit logs with entries in GitHub, and thus GitHub API callsNo more risk of matching the incorrect contributor as the information comes directly from GitHublast_commit_date is now populated with local git infoUse a cache file to speed up following builds: authors are fetched from GitHub for a page only if that page has changed since the last buildAll of the above improves accuracy and performances.Note: the plugin configuration inmkdocs.ymlstill uses the originalgit-committerssections.LimitationsGetting the contributors relies on what is available on GitHub or GitLab.For now, Git submodule is not supported and will report no contributors.GitLab users may not be properly identified. Seeissue #50UsageYou have 2 options to use this plugin:Use Mkdocs material theme (seeMkdocs material
documentation).Use the plugin directly in your template. See below.Display Last CommitIn 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.Template Code for last commit<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">{%iflast_commit_date%}{{last_commit_date}}{%endif%}</time></li></ul>Display List of CommittersAvatarThe avatar of the contributors is provided by GitHub. It uses maximal resolution.Template Code for avatars{%blockfooter%}<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">{%-foruserincommitters-%}<li><a href="{{user.url}}" title="{{user.name}}" data-bi-name="contributorprofile" target="_blank"><img src="{{user.avatar}}" alt="{{user.name}}"></a></li>{%-endfor-%}</ul></li></ul>{%endblock%}CSS.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.contributorsli{display:inline-block;vertical-align:top;margin:0;padding:0}Javascript$('.contributors img[data-src]').each(function(){src=$(this).attr("data-src");$(this).attr('src',src);});More information about templateshere.More information about blockshere.AcknowledgementsThank you to the following contributors:Byrne Reese - original author, maintainerNathan HernandezChris NorthwoodMartin DonathPTKayGutsFir121dstockhammerthorn2N8Zbarreeeiroo