Merge pull request #66 from timvink/19-add-site-last-update

Add new variables for site revision date

Author: timvink

.github/workflows/pythonpublish.yml

@@ -9,6 +9,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
+      with:
+        fetch_depth: '0'
     - name: Set up Python
       uses: actions/setup-python@v2
       with:
@@ -35,4 +37,5 @@ jobs:
 
     - name: Deploy mkdocs site
       run: | 
+        pip install mkdocs-git-authors-plugin
         mkdocs gh-deploy --force

README.md

@@ -37,7 +37,7 @@ plugins:
 
 > 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.
 
-If you use the [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) theme, you should already see the last revision on the bottom of your pages.
+The [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) theme has built in support for `git-revision-date-localized` and you should already see the last revision date on the bottom of your pages. See the [documentation](https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/index.html) on how to fine-tune the appearance and the date format.
 
 ### Note when using build environments
 

docs/available-variables.md

@@ -0,0 +1,47 @@
+# Available variables
+
+This plugin offers the following variables:
+
+| timestamp | description |
+|:-----------|:------------|
+| `git-revision-date-localized` | Last git commit that touched a file. Enabled by default. |
+| `git-creation-date-localized` | First git commit that touched a file. Enable in [options](options.md). |
+| `git_site_revision_date_localized` | Last git commit that touched any file in the `docs/` folder. Enabled by default. |
+
+You can use these variables wrapped in curly brackets (`{{` and `}}`) anywhere in a markdown file, like so:
+
+<pre id="__code_42"><span></span><button class="md-clipboard md-icon" title="Copy to clipboard" data-clipboard-target="#__code_42 > code"></button><code>This page was last updated: *&#123;{ git_revision_date_localized }}*
+</code></pre>
+
+Example output: This page was last updated *{{ git_revision_date_localized }}*.
+
+Changing the `type`, `timezone` and/or `locale` in the [options](options.md) will effect the output of these variables. To change the styling see [Applying custom styling](howto/custom-styling.md).
+
+## Variables for overriding themes
+
+If you do not want to include revision dates manually in each markdown file, or if you would like more control on the formatting, you can [override a theme](howto/override-a-theme.md). You can use the same three variables but with a `page.meta.` prefix:
+
+- `page.meta.git-revision-date-localized`
+- `page.meta.git-creation-date-localized`
+- `page.meta.git_revision_date_localized_raw_date`
+
+To allow for more flexibility when overriding a theme there are also variables for each different `type` available (regardless of the setting for `type` in [options](options.md)), where the output is also not wrapped in `<span>` elements (so you can do the CSS styling yourself): 
+
+- `page.meta.git_revision_date_localized_raw_date`
+- `page.meta.git_revision_date_localized_raw_datetime`
+- `page.meta.git_revision_date_localized_raw_iso_date`
+- `page.meta.git_revision_date_localized_raw_iso_datetime`
+- `page.meta.git_revision_date_localized_raw_timeago`
+- `page.meta.git_site_revision_date_localized_raw_datetime`
+- `page.meta.git_site_revision_date_localized_raw_iso_date`
+- `page.meta.git_site_revision_date_localized_raw_date`
+- `page.meta.git_site_revision_date_localized_raw_iso_datetime`
+- `page.meta.git_site_revision_date_localized_raw_timeago`
+
+And if you've enable creation date in the config:
+
+- `page.meta.git_creation_date_localized_raw_date`
+- `page.meta.git_creation_date_localized_raw_datetime`
+- `page.meta.git_creation_date_localized_raw_iso_date`
+- `page.meta.git_creation_date_localized_raw_iso_datetime`
+- `page.meta.git_creation_date_localized_raw_timeago`

docs/getting-started.md

@@ -1,21 +1,37 @@
 # Apply custom styling
 
-You might want to change the appearance of the dates in your theme. You can style the output using CSS, for example by [including extra css](https://www.mkdocs.org/user-guide/configuration/#extra_css) to your mkdocs site. 
+You can change the appearance of the revision dates by [including extra CSS](https://www.mkdocs.org/user-guide/configuration/#extra_css) to your mkdocs site. 
 
-The date outputs are always wrapped in `span` elements with the classes `git-revision-date-localized-plugin` and `git-revision-date-localized-plugin-{type}` (where `{type}` is replaced with the `type` option set in the plugin).
+## CSS Classes
 
-Here's an example:
+To allow for easier styling date outputs are wrapped in `<span>` elements with the classes `git-revision-date-localized-plugin` and `git-revision-date-localized-plugin-{type}`, where `{type}` is replaced with the `type` set in the plugin settings (see [options](../options.md)).
 
-=== "mkdocs.yml"
+For example when `type: datetime` is set, using the following in a markdown file:
 
-    ```yaml
-    extra_css:
-        css/extra.css
-    ```
+<pre id="__code_42"><span></span><button class="md-clipboard md-icon" title="Copy to clipboard" data-clipboard-target="#__code_42 > code"></button><code>Last update: {{ git_revision_date_localized }&#125;
+</code></pre>
+
+Could output the following HTML:
+
+```django
+Last update: 
+<span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime">28 November, 2019 13:57:28</span>
+```
+
+## Customizing a class
 
-=== "docs/css/extra.css"
+Making all revision dates red is as easy as:
+
+=== ":octicons-file-code-16: docs/css/extra.css"
 
     ```css
     .git-revision-date-localized-plugin { color: red; }
     ```
 
+=== ":octicons-file-code-16: mkdocs.yml"
+
+    ```yaml
+    extra_css:
+        css/extra.css
+    ```
+

docs/howto/custom-styling.md

@@ -1,21 +1,21 @@
 # Customize a theme
 
-You can [customize an existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme) by overriding blocks or partials. You might want to do this because your theme is not natively supported, or you would like more control on the formatting. Below are some examples to get you started.
+You can [customize an existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme) by overriding blocks or partials. You might want to do this because your theme is not natively supported, or you would like more control on the formatting. Below are two examples to help get you started.
 
 ## Example: default `mkdocs` theme
 
 To add a revision date to the default `mkdocs` theme, add a `overrides/partials` folder to your `docs` folder and update your `mkdocs.yml` file. 
 Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides/content.html`:
 
-=== "mkdocs.yml"
+=== ":octicons-file-code-16: mkdocs.yml"
 
-    ```yml
+    ```yaml
     theme:
         name: mkdocs
         custom_dir: docs/overrides
     ```
 
-=== "docs/overrides/content.html"
+=== ":octicons-file-code-16: docs/overrides/content.html"
 
     ```html
     <!-- Overwrites content.html base mkdocs theme, taken from 
@@ -31,6 +31,7 @@ Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides
 
     {{ page.content }}
 
+    <!-- This section adds support for localized revision dates -->
     {% if page.meta.git_revision_date_localized %}
         <small>Last update: {{ page.meta.git_revision_date_localized }}</small>
     {% endif %}
@@ -41,17 +42,19 @@ Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides
 
 ## Example: `mkdocs-material` theme
 
-[mkdocs-material](https://squidfunk.github.io/mkdocs-material/) has native support for `git_revision_date_localized` and `git_created_date_localized`. If you want, you can customize further by [extending the mkdocs-material theme](https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme) and overriding the [`source-file.html`](https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-file.html) partial as follows:
+[mkdocs-material](https://squidfunk.github.io/mkdocs-material/) has built-in support for `git_revision_date_localized` and `git_created_date_localized`. You can see that when viewing their [`source-file.html`](https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-file.html) partial. 
 
-=== "mkdocs.yml"
+If you want, you can customize further by [extending the mkdocs-material theme](https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme) and overriding the `source-file.html` partial as follows:
 
-    ```yml
+=== ":octicons-file-code-16: mkdocs.yml"
+
+    ```yaml
     theme:
         name: 'material'
-        custom_dir: docs/overrides_material_theme
+        custom_dir: docs/overrides
     ```
 
-=== "docs/overrides/partials/source-file.html"
+=== ":octicons-file-code-16: docs/overrides/partials/source-file.html"
 
     ```html
     {% import "partials/language.html" as lang with context %}
@@ -69,55 +72,7 @@ Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides
         {% if page.meta.git_creation_date_localized %}
             <br />{{ lang.t("source.file.date.created") }}: {{ page.meta.git_creation_date_localized }} 
         {% endif %}
-
-        <!-- mkdocs-git-revision-date-plugin -->
-        {% elif page.meta.revision_date %}
-        {{ label }}: {{ page.meta.revision_date }}
-        {% endif %}
     </small>
     </div>
     ```
 
-## Available variables
-
-When customizing or [writing your own themes](https://www.mkdocs.org/user-guide/custom-themes/) `mkdocs-revision-date-localized-plugin` will make available the following jinja variables:
-
-- `page.meta.git_revision_date_localized`
-- `page.meta.git_creation_date_localized`
-
-To insert these variables in a partial/block/template, use the jinja2 bracks `{{` and `}}`. The values of these variables depend on the plugin options specified, and are wrapped in `<span>` elements. For example, when using `type: timeago` (see [options](../options.md)):
-
-=== "input"
-
-    ```django
-    {% if page.meta.git_revision_date_localized %}
-    Last update: {{ page.meta.git_revision_date_localized }}
-    {% endif %}
-    ```
-
-=== "output"
-
-    ```django
-    Last update: <span class="timeago" datetime="2021-11-03T12:25:03+01:00" locale="en" timeago-id="5"></span>
-    ```
-
-!!! info "Note"
-
-    When `type: timeago` option is used, `mkdocs-revision-date-localized-plugin` adds [timeago.js](https://timeago.org/) to your mkdocs website, which dynamically inserts a value between the `<span>` elements like `2 weeks ago`.
-
-
-As a developer you might want access to multiple 'raw' date types. These variables also do not have the `<span>` elements. You can use:
-
-- `page.meta.git_revision_date_localized_raw_date`
-- `page.meta.git_revision_date_localized_raw_datetime`
-- `page.meta.git_revision_date_localized_raw_iso_date`
-- `page.meta.git_revision_date_localized_raw_iso_datetime`
-- `page.meta.git_revision_date_localized_raw_timeago`
-
-And if you've enable creation date in the config:
-
-- `page.meta.git_creation_date_localized_raw_date`
-- `page.meta.git_creation_date_localized_raw_datetime`
-- `page.meta.git_creation_date_localized_raw_iso_date`
-- `page.meta.git_creation_date_localized_raw_iso_datetime`
-- `page.meta.git_creation_date_localized_raw_timeago`

docs/howto/override-a-theme.md

@@ -2,24 +2,26 @@
 
 You can customize the plugin by setting options in `mkdocs.yml`. For example:
 
-```yaml
-plugins:
-  - git-revision-date-localized:
-      type: timeago
-      timezone: Europe/Amsterdam
-      locale: en
-      fallback_to_build_date: false
-      enable_creation_date: true
-      exclude:
-          - index.md
-      enabled: true
-```
+=== ":octicons-file-code-16: mkdocs.yml"
+
+  ```yaml
+  plugins:
+    - git-revision-date-localized:
+        type: timeago
+        timezone: Europe/Amsterdam
+        locale: en
+        fallback_to_build_date: false
+        enable_creation_date: true
+        exclude:
+            - index.md
+        enabled: true
+  ```
 
 ## `type`
 
 Default is `date`. The format of the date to be displayed. Valid values are `date`, `datetime`, `iso_date`, `iso_datetime` and `timeago`. Example outputs:
 
-```
+```yaml
 28 November, 2019           # type: date (default)
 28 November, 2019 13:57:28  # type: datetime
 2019-11-28                  # type: iso_date
@@ -41,7 +43,7 @@ Default is `None`. Specify a two letter [ISO639](https://en.wikipedia.org/wiki/L
 
 Example outputs:
 
-```
+```yaml
 27 April, 2021                # `locale: en` with `type: date` (default)
 27 April, 2021 13:11:28       # `locale: en` with `type: datetime`
 2 weeks ago                   # `locale: en` with `type: timeago`
@@ -56,33 +58,35 @@ Default is `false`. Enables falling back to the time when `mkdocs build` was exe
 
 ## `enable_creation_date`
 
-Default is `false`. Enables adding a *Created* date at the bottom of each page on [supported themes](getting-started.md#supported-themes). Also enables use of <code>\{\{ git_creation_date_localized }}</code> in markdown files and `page.meta.git_creation_date_localized` in page templates.
+Default is `false` (because it has a small effect on build time). Enables adding a *Created* date at the bottom of each page on [supported themes](getting-started.md#supported-themes). Also enables use of <code>\{\{ git_creation_date_localized }}</code> in markdown files and `page.meta.git_creation_date_localized` in page templates.
 
 ## `exclude`
 
 Default is empty. Specify a list of page source paths (one per line) that should not have a revision date included (excluded from processing by this plugin). This can be useful for example to remove the revision date from the front page. The source path of a page is relative to your `docs/` folder. You can also use [globs](https://docs.python.org/3/library/glob.html) instead of full source paths. To exclude `docs/subfolder/page.md` specify in your `mkdocs.yml` a line under `exclude:` with `- subfolder/page.md`. Some examples:
 
-```yaml
-# mkdocs.yml
-plugins:
-  - git-revision-date-localized:
-      exclude:
-        - index.md
-        - subfolder/page.md
-        - another_page.md
-        - folder/*
-```
+=== ":octicons-file-code-16: mkdocs.yml"
+
+  ```yaml
+  plugins:
+    - git-revision-date-localized:
+        exclude:
+          - index.md
+          - subfolder/page.md
+          - another_page.md
+          - folder/*
+  ```
 
 ## `enabled`
 
 Default is `true`. Enables you to deactivate this plugin. A possible use case is local development where you might want faster build times and/or do not have git available. It's recommended to use this option with an environment variable together with a default fallback (introduced in `mkdocs` v1.2.1, see [docs](https://www.mkdocs.org/user-guide/configuration/#environment-variables)). Example:
 
-```yaml
-# mkdocs.yml
-plugins:
-  - git-revision-date-localized:
-      enabled: !ENV [ENABLED_GIT_REVISION_DATE, True]
-```
+=== ":octicons-file-code-16: mkdocs.yml"
+
+  ```yaml
+  plugins:
+    - git-revision-date-localized:
+        enabled: !ENV [ENABLED_GIT_REVISION_DATE, True]
+  ```
 
 Which enables you do disable the plugin locally using:
 

docs/options.md

@@ -0,0 +1,13 @@
+{% 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 %}