mkdocs-git-revision-date-localized-plugin エラー完全解決ガイド¶

この記事の対象者

MkDocs運用でgit-revision-dateプラグインエラーに直面している中級者

この記事のポイント¶

プラグイン設定エラーの即時解決
日時表示形式の適切な調整
git履歴問題の根本対処

なぜこの問題が今重要か¶

mkdocs-git-revision-date-localized-pluginは記事の更新日時を自動管理する必須プラグインですが、設定ミスやgit環境の差異で頻繁にビルドエラーが発生します。特に CI/CD環境では shallow clone による履歴不足が原因となるケースが急増しています。

解決ステップ概要¶

ステップ	内容	到達指標
1	プラグイン設定の正規化	ビルドエラー解消
2	git履歴の適切な取得	正確な日時表示
3	timezone・locale設定	期待する書式で表示

ステップ1: プラグイン設定の正規化¶

最も頻発する設定エラーを修正します。

# mkdocs.yml
plugins:
  - git-revision-date-localized:
      enable_creation_date: true
      type: timeago
      timezone: Asia/Tokyo
      locale: ja
      fallback_to_build_date: true
      enabled: !ENV [ENABLE_GIT_REVISION, true]

重要: fallback_to_build_date: true でgit履歴不足時のフォールバック確保、enabled: !ENV でCI環境での条件付き無効化が可能。

ステップ2: git履歴の適切な取得¶

CI/CDでのshallow cloneが原因となる履歴不足を解決します。

# .github/workflows/deploy.yml（例）
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 完全履歴取得

- name: Git履歴確認
  run: |
    git log --oneline -5
    git config --global --add safe.directory /github/workspace

診断コマンド: ローカルで git log --oneline docs/your-file.md でファイル履歴を確認。

ステップ3: timezone・locale設定¶

日時表示の書式を適切に調整します。

plugins:
  - git-revision-date-localized:
      type: date          # 2025-09-01
      # type: datetime    # 2025-09-01 10:30:00
      # type: timeago     # 2 days ago
      timezone: Asia/Tokyo
      locale: ja

よくある落とし穴と対処¶

症状	原因	即時対処
`GitCommandError`	shallow clone	`fetch-depth: 0` 設定
英語表示される	locale未設定	`locale: ja` 追加
ビルドが非常に遅い	大量ファイル処理	`enabled: false` で一時無効

詳細設定（高度最適化）

### パフォーマンス最適化

plugins:
  - git-revision-date-localized:
      exclude:
        - archive/*
        - drafts/*
      custom_format: "%Y年%m月%d日"
      strict: false  # エラー時も継続

### カスタム書式例 - ISO形式: `"%Y-%m-%dT%H:%M:%S%z"` - 和暦対応: `"%Y年%-m月%-d日"`