Usage

In supported themes

no supported themes yet.

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 Tim Vink 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:

Jane Doe, John Doe

In theme customizations

MkDocs offers possibilities to customize an existing theme. See two examples below:

mkdocs-material theme

If you use the mkdocs-material theme 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 Tim Vink to insert a summary of the authors.

Authors: Tim Vink