Skip to content
A mkdocs plugin for displaying the last commit and a list of a file's contributors.
Python Shell
Branch: master
Clone or download
Latest commit 26bd5ec Apr 28, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
mkdocs_git_committers_plugin Fix repos link issue Apr 27, 2019
.gitignore initial add Dec 15, 2018
LICENSE Added license Dec 15, 2018
README.md Updated readme to add new contributor Apr 26, 2019
deploy.sh Added deploy.sh helper script Dec 19, 2018
requirements.txt Added PyGithub to requirements Dec 15, 2018
setup.py Incremented version Apr 28, 2019

README.md

mkdocs-git-committers-plugin

MkDocs plugin for displaying a list of committers associated with a file in mkdocs.

Setup

Install the plugin using pip:

pip install mkdocs-git-committers-plugin

Activate the plugin in mkdocs.yml:

plugins:
  - search
  - git-committers

Note: If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.

More information about plugins in the MkDocs documentation.

Config

  • enterprise_hostname - The enterprise hostname of your github account (Github Enterprise customers only).
  • repository - The name of the repository, e.g. 'byrnereese/mkdocs-git-committers-plugin'
  • branch - The name of the branch to pull commits from, e.g. 'master' (default)
  • token - A github Personal Access Token to avoid github rate limits

Tip: You can specify the GitHub token via an environment variable in the following way:

plugins:
  - git-committers:
      repository: johndoe/my-docs
      branch: master
      token: !!python/object/apply:os.getenv ["MKDOCS_GIT_COMMITTERS_APIKEY"]

If the token is not set in mkdocs.yml it will be read from the MKDOCS_GIT_COMMITTERS_APIKEY environment variable.

If no token is present, the plugin will be disabled automatically. This can be helpful as when actively working on documentation, the git-committers plugin can dramatically slow down page rendering times.

Usage

Display Last Commit

In addition to displaying a list of committers for a file, you can also access all the information relating to the last commit of the file. This is useful for example if you want to display the date the file was last updated.

Template Code

<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 %}{{ last_commit.commit.committer.dat\
e.strftime('%Y-%m-%d') }}{% endif %}</time>
  </li>
</ul>

Display List of Committers

Template Code

{% 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="{{ user.repos }}" title="{{ user.name }}" data-bi-name="contributorprofile"><img src="../img/contributor.svg" data-src="{{ user.avatar }}?size=32" 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 .contributors li{
    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 templates here.

More information about blocks here.

Acknowledgements

Thank you to the following contributors:

  • Nathan Hernandez
  • Chris Northwood
You can’t perform that action at this time.