Improve docs on using partials

Author: timvink

docs/options.md

@@ -4,7 +4,7 @@ You can customize the plugin by setting options in your `mkdocs.yml` file. Here
 
 ```yml
 plugins:
-    - print-site:
+    - git-authors:
         show_contribution: true
         show_line_count: true
         count_empty_lines: true

docs/overrides/main.html

@@ -0,0 +1,13 @@
+{% extends "base.html" %}
+
+{% block content %}
+  {{ super() }}
+
+  {% if git_page_authors %}
+    <div class="md-source-date">
+      <small>
+          Authors: {{ git_page_authors }}
+      </small>
+    </div>
+  {% endif %}
+{% endblock %}

docs/theme/main.html

@@ -11,7 +11,7 @@ You can use the following jinja tags to insert content into your markdown pages:
 - <code>\{\{&nbsp;git_page_authors \}\}</code> a summary of the authors of a page. Output wrapped in `<span class='git-page-authors'>`
 - <code>\{\{&nbsp;git_site_authors \}\}</code> a summary of all authors of all pages in your site. Output wrapped in `<span class='git-site-authors'>`
 
-For example, adding <code>\{\{ git_page_authors \}\}</code> will insert:
+For example, adding <code>\{\{ git_page_authors \}\}</code> could insert:
 
 ```html
 <span class='git-page-authors'><a href='mailto:[email protected]'>Jane Doe</a><a href='mailto:[email protected]'>John Doe</a></span>
@@ -24,22 +24,27 @@ Which renders as:
 
 ## In theme customizations
 
-[MkDocs](https://www.mkdocs.org/) offers possibilities to [customize an existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme).
+[MkDocs](https://www.mkdocs.org/) offers possibilities to [customize an existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme). See two examples below:
 
-As an example, if you use [mkdocs-material](https://github.com/squidfunk/mkdocs-material) you can implement git-authors by [overriding a template block](https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks):
+### mkdocs-material theme
 
-1) Create a new file `main.html` in `docs/theme`:
+If you use the [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme you can implement git-authors by [overriding a template block](https://squidfunk.github.io/mkdocs-material/customization/#overriding-blocks):
+
+1) Create a new file `main.html` in `docs/overrides`:
 
 ```html
 {% extends "base.html" %}
 
-{% block disqus %}
+{% block content %}
+  {{ super() }}
+
+  {% if git_page_authors %}
     <div class="md-source-date">
-    <small>
-        Authors: {{ git_page_authors }}
-    </small>
-  </div>
-    {% include "partials/integrations/disqus.html" %}
+      <small>
+          Authors: {{ git_page_authors }}
+      </small>
+    </div>
+  {% endif %}
 {% endblock %}
 ```
 
@@ -48,7 +53,40 @@ As an example, if you use [mkdocs-material](https://github.com/squidfunk/mkdocs-
 ```yml
 theme:
     name: material
-    custom_dir: docs/theme/
+    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`:
+
+```html
+<!-- 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 }}</small></p>
+{% endif %}
+```
+
+2) In `mkdocs.yml` make sure to specify the custom directory with the theme overrides:
+
+```yml
+theme:
+    name: mkdocs
+    custom_dir: docs/overrides
 ```
 
 ## In theme templates

docs/usage.md

@@ -5,12 +5,15 @@ use_directory_urls: false
 # Theme
 theme:
   name: material
-  custom_dir: docs/theme/
+  custom_dir: docs/overrides
 
 # Plugins
 plugins:
   - search
-  - git-authors
+  - git-authors:
+      show_contribution: true
+      show_line_count: true
+      count_empty_lines: true
 
 nav:
   - index.md