Mkdocs plugin to display git authors of a page
Project description
mkdocs-git-authors-plugin
MkDocs plugin to display git authors of a page. Only considers authors of the current lines in the page ('surviving code' using git blame
).
Other MkDocs plugins that use information from git:
- mkdocs-git-committers-plugin for displaying authors' github user profiles
- mkdocs-git-revision-date-localized-plugin for displaying the last revision date
Setup
Install the plugin using pip:
pip install mkdocs-git-authors-plugin
Next, add the following lines to your mkdocs.yml
:
plugins:
- search
- git-authors
If you have no
plugins
entry in your config file yet, you'll likely also want to add thesearch
plugin. MkDocs enables it by default if there is noplugins
entry set.
Usage
In supported themes
no supported themes yet
In markdown pages
You can use {{ git_authors_summary }}
to insert a summary of the authors of a page. Authors are sorted by their name and have a mailto:
link with their email.
An example output:
<span class='git-authors'><a href='mailto:jane@abc.com'>Jane Doe</a><a href='mailto:john@abc.com'>John Doe</a></span>
Which renders as:
In theme templates
To add more detailed author information to your theme you can customize a mkdocs theme or even develop your own. When enabling this plugin, you will have access to the jinja2 variable git_authors
, which contains a list of authors dicts, like the following example:
[{
'name' : 'Jane Doe',
'email' : 'jane@abc.com',
'last_datetime' : datetime.datetime(),
'lines' : 200,
'contribution' : '40.0%'
},
{
'name' : 'John Doe',
'email' : 'john@abc.com',
'last_datetime' : datetime.datetime(),
'lines' : 300,
'contribution' : '60.0%'
}]
An example of how to use in your templates:
{% if git_authors %}
{%- for author in git_authors -%}
<a href="{{ author.email }}" title="{{ author.name }}">
{{ author.name }}
</a>,
{%- endfor -%}
{% endif %}
Alternatively, you could use the simple preformatted {{ git_authors_summary }}
to insert a summary of the authors.
Options
show_contribution
If this option is set to true
(default: false
) The contribution to a page is
printed as a percentage of (source file) lines per author. The output is
suppressed if there is only one author for a page.
Example output:
Aggregating Authors
In some repositories authors may have committed with differing name/email combinations.
In order to prevent the output being split it is possible to aggregate authors on
arbitrary elements by providing a file .mailmap
in the repository's root directory.
This is a feature of Git itself. The following example will aggregate the contributions
of Jane Doe committed under two email addresses:
# .mailmap
Jane Doe <jane.doe@company.com> <jane.doe@private-email.com>
This will map commits made with the private-email.com
to the company address. For more details
and further options (e.g. mapping between different names or misspellings etc. see the
git-blame documentation.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs-git-authors-plugin-0.2.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 007d730886e286fbe5e87ae7c368d1bc6d2c6b28b69445ba39be878006988ca3 |
|
MD5 | f328ed7945277bc2f28a767bdb1844f6 |
|
BLAKE2b-256 | f562b03d6c62ab9401985940e6d75de184e669ae8d79c4ed6d4b1b04c688dd02 |
Hashes for mkdocs_git_authors_plugin-0.2.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6f3633410fbfba9b013b0a4dc0ed4e5b665ab37e3c4643bb4ca3e236b98d9ac7 |
|
MD5 | 225866f517f8c8c5bdd288e95adb5eeb |
|
BLAKE2b-256 | af27ca194145c2aafe0275db8a1f2a54dede23aad6d30eeddc4f325e4ebf5e8d |