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によるフォーマットも可能です。
冒頭で説明したように、表記のフォーマットも可能です。
現時点(2022年2月10日)では当該プラグインの最新バージョン(0.3.1)には不具合があり1、as_datetime が利用できないため、このオプションを利用する場合は 0.3.0 を利用するようにしてください。
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 とほぼ同様です。
オプションでタイムゾーンや表示形式を指定できます。
詳細は以下公式ドキュメントが参考になります。