Complete mkdocs-git-revision-date-localized-plugin Error Resolution Guide¶

Target Audience

Intermediate users facing git-revision-date plugin errors in MkDocs operations

Key Points¶

Instant resolution of plugin configuration errors
Proper adjustment of datetime display formats
Root cause resolution of git history issues

Why This Problem is Critical Now¶

The mkdocs-git-revision-date-localized-plugin is essential for automatic article timestamp management, but frequently causes build errors due to configuration mistakes and git environment differences. Particularly in CI/CD environments, shallow clone-related history insufficiency cases are rapidly increasing.

Solution Steps Overview¶

Step	Content	Success Metric
1	Plugin configuration normalization	Build errors resolved
2	Proper git history retrieval	Accurate datetime display
3	Timezone and locale configuration	Display in expected format

Step 1: Plugin Configuration Normalization¶

Fix the most frequent configuration errors.

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

Important: fallback_to_build_date: true ensures fallback for insufficient git history, enabled: !ENV allows conditional disabling in CI environments.

Step 2: Proper Git History Retrieval¶

Resolve history insufficiency caused by shallow clone in CI/CD.

# .github/workflows/deploy.yml (example)
- uses: actions/checkout@v4
  with:
    fetch-depth: 0  # Full history retrieval

- name: Check git history
  run: |
    git log --oneline -5
    git config --global --add safe.directory /github/workspace

Diagnostic Command: Run git log --oneline docs/your-file.md locally to check file history.

Step 3: Timezone and Locale Configuration¶

Properly adjust datetime display format.

plugins:
  - git-revision-date-localized:
      type: date          # 2025-09-01
      # type: datetime    # 2025-09-01 10:30:00
      # type: timeago     # 2 days ago
      timezone: UTC
      locale: en

Common Pitfalls and Solutions¶

Symptom	Cause	Instant Solution
`GitCommandError`	shallow clone	Set `fetch-depth: 0`
English display only	locale not set	Add `locale: en`
Very slow builds	Processing many files	Temporarily disable with `enabled: false`

Advanced Configuration (Performance Optimization)

### Performance Optimization

plugins:
  - git-revision-date-localized:
      exclude:
        - archive/*
        - drafts/*
      custom_format: "%Y-%m-%d"
      strict: false  # Continue on errors

### Custom Format Examples - ISO format: `"%Y-%m-%dT%H:%M:%S%z"` - US format: `"%B %d, %Y"`