Skip to content

Mkdocs の設定を一新した

#mkdocs

1年振りくらいに Mkdocs (このページで利用している documentation tool) の設定を更新した記録.

依存管理を Poetry で行う

Plugin を試すためにインストールしたりアンインストールしたりすることがあって, pip と requirements.txt だけだとキツかったので Poetry で依存管理するようにした.

pyproject.toml
[tool.poetry]
name = "..."
version = "0.1.0"
description = "..."
authors = ["..."]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.10"
mkdocs-material = "^8.5.11"
mkdocs-git-revision-date-localized-plugin = "^1.1.0"
mkdocs-exclude-search = "^0.6.4"
mkdocs-blogging-plugin = "^2.2.2"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

GitHub Actions にデプロイさせる

ローカルから mkdocs gh-deploy するのが面倒なので, GitHub Actions workflow を設定した.

公式ページの例を参考に設定する. https://squidfunk.github.io/mkdocs-material/publishing-your-site/

.github/workflows/publish.yaml
name: publish

on:
  push:
    branches:
      - develop

permissions:
  contents: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - run: pip install poetry
      - run: |
          poetry --version
          poetry install
      - run: poetry run mkdocs gh-deploy --force --verbose
        env:
          TZ: 'Asia/Tokyo'

Footer をカスタマイズするために, overrides/partials/source-file.html を下のようにする.

overrides/partials/source-file.html
<!-- Source file information -->
<hr />
<div class="md-source-file">
  <small>

    <!-- git_creation_date_localized ではなく, 自前の変数を利用 -->
    {% if page.meta.posted_date %}
    Posted: {{ page.meta.posted_date }}
    {% endif %}
    <br />
    <!-- mkdocs-git-revision-date-localized-plugin -->
    {% if page.meta.git_revision_date_localized %}
    Last update: {{ page.meta.git_revision_date_localized }}
    {% endif %}
  </small>
</div>

Last update:
mkdocs-git-revision-date-localized-plugin がセットしてくれる git_revision_date_localized 変数を参照している.

Posted:
mkdocs-git-revision-date-localized-plugin の git_creation_date_localized をあえて使わずに, 自分で書いた日付を表示している.

利用できる変数は mkdocs-git-revision-date-localized-plugin: Available variables を参照.

OGP, Twitter カードのための設定

Mkdocs の Overriding blocks 機能を利用して, extrahead block を上書きしている.

overrides/main.html
{% extends "base.html" %}

{% block extrahead %}

{% set description = config.site_description %}
{% if page and page.meta.description %}
{% set description = page.meta.description %}
{% endif %}

{% set image = config.site_url ~ 'img/site.jpeg' %}
{% if page and page.meta.image %}
{% set image = config.site_url ~ page.meta.image %}
{% endif %}

<meta name="twitter:title" content="{{ page.title }}">
<meta name="twitter:description" content="{{ description }}">
<meta name="twitter:image" content="{{ image }}">
<meta name="twitter:card" content="summary">
<meta name="twitter:site" content="@...">
<meta name="twitter:creator" content="@...">

<meta property="og:title" content="{{ page.title }}">
<meta property="og:description" content="{{ description }}">
<meta property="og:image" content="{{ image }}">
<meta property="og:type" content="article">
<meta property="og:url" content="{{ page.canonical_url }}">
<meta property="og:locale" content="ja_JP">
{% endblock %}

(画像は docs/img/site.jpeg に置いてる)

mkdocs-blogging-plugin の利用

mkdocs-blogging-plugin を入れてみた. 設定は, 下のように.

mkdocs.yml
plugins:
  - blogging:
      dirs:
        - blog       # <-- Blog 化したいドキュメントを置いているディレクトリ.
      size: 20       # <-- 1ページに表示する数. (Default: 10)  
      locale: ja_JP  # <-- 時刻表示が locale に依存するので, 明示しておく.
      features:
        tags:
          insert: top
          index_page: tags.md

Mkdocs Materials にも tag 機能が実装されているが, 表示のカスタマイズがあまりできなそうなので利用していない.
日付も表示してくれるので, mkdocs-blogging-plugin の方が好みだった.

Posted: 2022-12-30
Last update: 2022-12-30