mkdocs-git-revision-date-plugin で MkDocs のページに更新日を表示する

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

# mkdocs-git-revision-date-plugin とは

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

https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin

# 使い方

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

https://qiita.com/ajitator/items/aec49127f542eac31ffe

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

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

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

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

```yaml:mkdocs.yml
plugins:
- git-revision-date
```

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

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

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

```diff
  docs/
  img/
+ custom/
  mkdocs.yml
```

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

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

```html
{% 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` に以下のように記載します。

```diff:mkdocs.yml
 theme:
   name: mkdocs
+  custom_dir: custom/
```

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

![Screen Shot 2021-07-21 at 4.00.22 PM.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/66988/0846f115-5db9-7776-c4a6-2f59c02897ff.png)

## フォーマットする

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

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

:::note warn
現時点(2022年2月10日)では当該プラグインの最新バージョン(`0.3.1`)には不具合があり[^1]、`as_datetime` が利用できないため、このオプションを利用する場合は `0.3.0` を利用するようにしてください。
:::

### `as_datetime` を有効にする

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

```yaml:mkdocs.yml
plugins:
- git-revision-date:
    as_datetime: true
```

### 日付をフォーマットする

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

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

![Screen Shot 2021-07-21 at 4.10.59 PM.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/66988/24eaccdf-0a9f-2379-8e6b-03a725b865ff.png)

### ほか有用なプラグイン

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

https://github.com/timvink/mkdocs-git-revision-date-localized-plugin

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

https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/options/


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