MkDocs は Python のプラグインを利用することで様々な拡張ができます。
この記事では、mkdocs-git-revision-date-plugin を使って、Git のコミット日をドキュメントに挿入する方法について説明します。

mkdocs-git-revision-date-plugin とは

Git のコミット日を表示する MkDocs プラグインです。
as_datetime オプションを有効にすることで、Python の datetime 型で受けることができ、strftime によるフォーマットも可能です。

使い方

Python, MkDocs はインストール済のものとして説明します。
MkDocs の利用法は以下の記事が参考になります。

mkdocs-git-revision-date-plugin のインストール

pip install mkdocs-git-revision-date-plugin を実行します。

mkdocs.yml でプラグインを有効にする

mkdocs.yml ファイルの plugins に以下のように記載します。

plugins:
- git-revision-date

ページに更新日を挿入する

MkDocs の template override を利用して、全てのページで更新日が表示されるようにします。
この例では、フッタ部を override します。

まず、以下の構成で custom/ フォルダを作成します。
すでに Template override を利用している場合は、既存のファイルに追記する形になります。

  docs/
  img/
+ custom/
  mkdocs.yml

次に、このフォルダ内に main.html を作成し、以下のように記載します。
Template override の詳細は公式ドキュメントを参照してください。

revision-date-plugin にて取得された各ページの更新日は、page.meta.revision_date で参照できます。
ここでは、デフォルトテーマのフッタブロックに対して、page.meta.revision_date を表示する節を追記しています。

{% extends "base.html" %}

{% block footer %}
<hr>
{%- if config.copyright %}
<p>{{ config.copyright }}</p>
{%- endif %}
<p>{% trans mkdocs_link='<a href="https://www.mkdocs.org/">MkDocs</a>' %}Documentation built with {{ mkdocs_link }}.{% endtrans %}</p>
{% if page.meta.revision_date %}
<small><br><i>Updated {{ page.meta.revision_date }}</i></small>
{% endif %}
{% endblock %}

最後に、override を有効にするため、mkdocs.yml に以下のように記載します。

 theme:
   name: mkdocs
+  custom_dir: custom/

あとは mkdocs build や mkdocs serve でアウトプットを確認します。
フッタ部に更新日が表示されていることが確認できます。

フォーマットする

as_datetime オプションを有効にすることで、Python の datetime 型で受けることができ、strftime によるフォーマットも可能です。

冒頭で説明したように、表記のフォーマットも可能です。

as_datetime を有効にする

mkdocs.yml の plugins の記述を以下の通り変更します。

plugins:
- git-revision-date:
    as_datetime: true

日付をフォーマットする

as_datetime を設定することで、page.meta.revision_date が datetime 型で返ってきます。
ですので、以下のように strftime を呼び出してお好きな形にフォーマットしましょう。

<small><br><i>Updated {{ page.meta.revision_date.strftime("%Y年%m月%d日") }}</i></small>

ほか有用なプラグイン

単に日付をローカライズしたい場合は、mkdocs-git-revision-date-plugin をフォークした mkdocs-git-revision-date-localized-plugin が便利です。
利用方法は　mkdocs-git-revision-date-plugin とほぼ同様です。

オプションでタイムゾーンや表示形式を指定できます。
詳細は以下公式ドキュメントが参考になります。

1. https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin/issues/18 ↩