Usage
In supported themes
- mkdocs-material: offers deep integration for this plugin within when using the Insiders version. No additional setup is required, and styling is taken care of also. Sponsoring Mkdocs Material is great way to give support MkDocs and really helps the MkDocs open source ecosystem.
In markdown pages
You can use the following jinja tags to insert content into your markdown pages:
{{ git_page_authors }}a summary of the authors of a page. Output wrapped in<span class='git-page-authors'>{{ git_site_authors }}a summary of all authors of all pages in your site. Output wrapped in<span class='git-site-authors'>
For example, adding could insert:
<span class='git-page-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 customizations
MkDocs offers possibilities to customize an existing theme. See two examples below:
mkdocs-material theme
The mkdocs-material theme has built-in integration for git-authors starting from version 9.5.0.
If you use mkdocs-material theme version lower than 9.5.0 you can implement git-authors by overriding a template block:
1) Create a new file main.html in docs/overrides:
{% extends "base.html" %}
{% block content %}
{{ super() }}
{% if git_page_authors %}
<div class="md-source-date">
<small>
Authors: {{ git_page_authors | default('enable mkdocs-git-authors-plugin') }}
</small>
</div>
{% endif %}
{% endblock %}
2) In mkdocs.yml make sure to specify the custom directory with the theme overrides:
theme:
name: material
custom_dir: docs/overrides
mkdocs theme
In the default MkDocs theme we can use overriding partials to add the git-authors info below the page content.
1) Create a new file content.html in docs/overrides:
<!-- Overwrites content.html base mkdocs theme, taken from
https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/mkdocs/content.html -->
{% if page.meta.source %}
<div class="source-links">
{% for filename in page.meta.source %}
<span class="label label-primary">{{ filename }}</span>
{% endfor %}
</div>
{% endif %}
{{ page.content }}
{% if git_page_authors %}
<p><small>Authors: {{ git_page_authors | default('enable mkdocs-git-authors-plugin') }}</small></p>
{% endif %}
2) In mkdocs.yml make sure to specify the custom directory with the theme overrides:
theme:
name: mkdocs
custom_dir: docs/overrides
In theme templates
To add more detailed git 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_info which contains as dict with the following structure:
{
'page_authors' : [
{
'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%'
}
],
'site_authors' : # same structure
}
Example usage in theme development
An example of how to use in your templates:
{% if git_info %}
{%- for author in git_info.get('page_authors') -%}
<a href="{{ author.email }}" title="{{ author.name }}">
{{ author.name }}
</a>,
{%- endfor -%}
{% endif %}
Alternatively, you could use the simple pre-formatted to insert a summary of the authors.