mkdocs-document-dates¶

mkdocs-document-dates, a new generation MkDocs plugin for displaying exact creation date, last updated date, authors, email of documents.

Features¶

Works in any environment (no-Git, Git environments, Docker, all CI/CD build systems, etc.)
Support list display of recently updated documents (in descending order of update date)
Support for manually specifying date and author in Front Matter
Support for multiple date formats (date, datetime, timeago)
Support for multiple author modes (avatar, text, hidden)
Support for manually configuring author's name, link, avatar, email, etc.
Flexible display position (top or bottom)
Elegant styling (fully customizable)
Multi-language support, localization support, intelligent recognition of user language, automatic adaptation
Ultimate build efficiency: O(1), no need to set the env var !ENV to distinguish runs

Build Speed Comparison: 100 md: 1000 md: Time Complexity:

git-revision-date-localized

git-authors
＞ 3 s
＞ 30 s
O(n)

document-dates ＜ 0.1 s ＜ 0.15 s O(1)

Installation¶

Install it with pip:

pip install mkdocs-document-dates

Then, add the following lines to mkdocs.yml:

plugins:
  - document-dates

Or, common configuration:

plugins:
  - document-dates:
      position: top            # Display position: top(after title) bottom(end of document), default: top
      type: date               # Date type: date datetime timeago, default: date
      exclude:                 # List of excluded files (support unix shell-style wildcards)
        - temp.md                  # Example: exclude the specified file
        - blog/*                   # Example: exclude all files in blog folder, including subfolders
        - '*/index.md'             # Example: exclude all index.md files in any subfolders

Configuration¶

The following configuration options are supported:

Option	Valid value	Default	Description
position	`top`, `bottom`	`top`	specify the display position of the plugin
type	`date`, `datetime`, `timeago`	`date`	specify the type of date to be displayed
exclude	[]	none	specify a list of excluded files
date_format		'%Y-%m-%d'	specify the date formatting string
time_format		'%H:%M:%S'	specify the time formatting string, valid only if type=datetime
show_created	`true`, `false`	`true`	specify whether to display the creation date
show_updated	`true`, `false`	`true`	specify whether to display the last updated date
show_author	`true`(avatar), `false`(hidden), `text`(text)	`true`	specify the type of author display

Settings¶

The plugin provides a wide range of customization options to meet various personalized needs.

Date & Time¶

The date data is retrieved using a combination of different methods to adapt to various runtime environments, including no-Git environments, Git, Docker containers, and all CI/CD build systems:

Uses filesystem timestamps to ensure accurate original dates in local no-Git environments
Uses Git timestamps to ensure relatively accurate dates in Git environments
Uses cache files to ensure accurate original dates in Git environments
Front Matter: Manually specify the date in Front Matter if you prefer not to use automatic dates

Why not use filesystem timestamps in Git environments?

Because files are recreated during git checkout or git clone, causing the original timestamps of branches/files to be lost after cloning or checking out.

Loading order¶

By default, the plugin will automatically load the document's "creation date" and "last updated date" in the following order.

%%{init: {'theme': 'default', 'themeVariables': {'fontSize': '12px'}}}%%
flowchart LR
    A(1.Front Matter)
    B(2.Cache File)
    C(3.Git Timestamp)
    D(4.File Timestamp)
    A -.Creation date.-> B -.-> C -.-> D
    A -.Last updated.-> C

Creation dateLast updated

Prioritize reading the custom creation date in Front Matter
Then read the creation date in the cache file
Next read the document’s first git commit date as the creation date
Finally read the file’s creation time

Prioritize reading the custom last updated date in Front Matter
Then read the document’s last git commit date as the last updated date
Finally read the file’s modification time

Customization¶

This can be specified in Front Matter using the following fields:

Creation date: created, date
Last updated: updated, modified

---
created: 2023-01-01
updated: 2025-02-23
---

Cache creation date¶

In the Git environment, the plugin reads the document's "first git commit date" as the creation date by default. However, if you need to retrieve the original creation date of the document (earlier than the first git commit), you can manually install Git hooks to use a caching mechanism to solve this issue. Navigate to the target repository directory in the terminal and execute the following command to install Git hooks:

mdd-hooks

This command installs the pre-commit hook locally in the root directory of the target repository, located at .githooks/pre-commit.

Afterwards, every time you execute git commit, the cache file containing the creation date will be automatically generated (hidden by default) in the docs directory, and this cache file will also be committed automatically.

docs/.dates_cache.jsonl, cache file
docs/.gitattributes, merge mechanism for cache file

This method is compatible with CI/CD build systems, which will automatically detect and load the cache file.

Configure git fetch depth¶

In the CI/CD system, if the "creation date" uses the "first git commit date" (i.e., no custom or cache file date), you need to configure git fetch depth in the CI system to retrieve the correct first git commit record. For example:

.github/workflows/ci.yaml

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

Github Actions: set fetch-depth to 0 (docs)
Gitlab Runners: set GIT_DEPTH to 0 (docs)
Bitbucket pipelines: set clone: depth: full (docs)
Azure Devops pipelines: set Agent.Source.Git.ShallowFetchDepth to something very high like 10e99 (docs)

Author¶

Loading order¶

The plugin will automatically loads the author information of the document in the following order, and will automatically parse the email and then do the linking.

%%{init: {'theme': 'default', 'themeVariables': {'fontSize': '12px'}}}%%
flowchart LR
    A(1.Front Matter)
    B(2.Git Author)
    C(3.site_author)
    D(4.PC Username)
    A -.-> B -.-> C -.-> D

Description

Prioritize reading custom authors in Front Matter
Then read the Git author
Next read the site_author in mkdocs.yml
Finally read the PC username

Customization¶

Can be configured in Front Matter in the following ways:

1) Configure a simple author: via field name

---
name: any-name
email: e-name@gmail.com
---

2) Configure one or more authors: via field authors

---
authors:
  - jaywhj
  - dawang
  - sunny
---

Enhanced author configuration¶

For a better user experience, you can add full configuration for all authors. To do so, create an authors.yml file in the docs/ folder using the format below:

docs/authors.yml

authors:
  jaywhj:
    name: Aaron Wang
    avatar: https://xxx.com/avatar.jpg
    url: https://jaywhj.netlify.app/
    email: junewhj@qq.com
    description: Minimalism
  user2:
    name: xxx
    avatar: assets/avatar.png
    url: https://xxx.com
    email: xxx@gmail.com
    description: xxx

When the author name in Front Matter, Git Author, site_author(mkdocs.yml) matches the key in authors, the full author information of the key will be automatically loaded.

Git author aggregation¶

Git author support account aggregation, i.e. multiple different email accounts for the same person can be aggregated to show the same author, which can be configured by providing a .mailmap file in the repository root directory, this is also a feature of Git itself, see gitmailmap for more details.

The following example unifies my other Git accounts and displays them as Aaron <junewhj@qq.com>:

.mailmap

Aaron <junewhj@qq.com> <aaron@gmail.com>
Aaron <junewhj@qq.com> <aaron@AarondeMacBook-Pro.local>
Aaron <junewhj@qq.com> aaron <aaronwqt@icloud.com>

Avatar¶

Loading order¶

The plugin will automatically loads the author avatar in the following order.

%%{init: {'theme': 'default', 'themeVariables': {'fontSize': '12px'}}}%%
flowchart LR
    A(1.Front Matter)
    B(2.Online Avatar)
    C(3.Character Avatar)
    A -.-> B -.-> C

Customization¶

Customizable via avatar field in Enhanced author configuration (supports URL paths and local file paths).

Other avatars¶

Online avatarCharacter avatar

Load from Gravatar or Weavatar based on Git's user.email

Automatically generated based on the author's name with the following rules:
1. Extract initials: English takes the combination of initials, other languages take the first character
2. Generate dynamic background color: Generate HSL color based on the hash of the name

Structure and Style¶

You can configure the display structure of the plugin in the following ways in either mkdocs.yml or Front Matter.

Configuration structure¶

Global Toggle, configured in mkdocs.yml:

mkdocs.yml

plugins:
  - document-dates:
      ...
      show_created: true    # Show creation date: true false, default: true
      show_updated: true    # Show last updated date: true false, default: true
      show_author: true     # Show author: true(avatar) text(text) false(hidden), default: true

Local Toggle, configured in Front Matter (using the same field names):

---
show_created: true
show_updated: true
show_author: text
---

Note

When used in combination, the global toggle acts as the master switch, and the local toggle only takes effect when the master switch is enabled. This does not follow the logic of local configurations overriding global ones.

Configuration style¶

You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on, you just need to find the file below and uncomment it:

Category:	Location:
Style & Theme	docs/assets/document_dates/user.config.css
Properties & Functions	docs/assets/document_dates/user.config.js

You can also refer to the latest example file for free customization: user.config

Template Variables¶

You can use the following variables in the template to access the document's meta-info:

page.meta._mx.document_dates.dates.created
page.meta._mx.document_dates.dates.updated
page.meta._mx.document_dates.authors
config.extra.recently_updated_docs

Set correct `lastmod` for sitemap¶

You can set the correct lastmod for your site's sitemap.xml with the template variable _mx.document_dates.dates.updated so that search engines can better handle SEO and thus increase your site's exposure

Step: Download the sample template sitemap.xml, and override this path docs/overrides/sitemap.xml

Recustomize plugin¶

The plugin can be re-customized using templates, you have full control over the rendering logic and the plugin is only responsible for providing the data

Step: Download the sample template source-file.html, and override this path docs/overrides/partials/source-file.html, then freely customize the template code

Localization Language¶

The plugin's tooltip and timeago have built-in multi-language support, and the locale is automatically detected, so you don't need to configure it manually. If any language is missing, you can add it for them.

Built-in locales: en zh zh_TW es fr de ar ja ko ru nl pt

Addition Method (choose one):

In user.config.js, refer to Part 3 to add it by registering yourself
Submit a PR for Inclusion

For timeago¶

When type: timeago is set, the timeago.js library is enabled for dynamic time rendering. The built-in locales in timeago.min.js only include en zh. If you need to load other languages, you can configure it as described below (choose one):

In user.config.js, refer to Part 2 to add it by registering yourself
In mkdocs.yml, configure the full version of timeago.full.min.js to reload all locales
mkdocs.yml
```
extra_javascript:
  - assets/document_dates/core/timeago.full.min.js
```

Development Stories¶

A dispensable, insignificant little plug-in, friends who have time can take a look ^_^

Origin:
- Because git-revision-date-localized, a great project. When I used it at the end of 2024, I found that I couldn't use it locally because my mkdocs documentation was not included in git management, I don't understand why not read the file timestamp, but to use the git timestamp, and the file timestamp is exact, then raised an issue to the author, but didn't get a reply for about a week (the author had a reply later, nice guy, I guess he was busy at the time), and then I thought, why not try it myself, and so it was born, in February 2025
Iteration:
- After development, I understood why not use file timestamp, because files will be rebuilt when they go through git checkout or git clone, resulting in the loss of the original timestamp of the branch/file that was cloned or checked out. There are many solutions:
  - Method 1: Use the last git commit date as the last updated date and the first git commit date as the creation date, git-revision-date-localized does this. (This way, there will be a margin of error and dependency on git)
  - Method 2: Cache the original date in advance, and then read the cache subsequently (The date is exact and no dependency on any environment). The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is easier, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
  - Method 3: Configure a custom script git-restore-mtime in the CI system to automatically restore the original file timestamps
Difficulty:
1. When to read and store original date? This is just a plugin for mkdocs, with very limited access and permissions, mkdocs provides only build and serve, so in case a user commits directly without executing build or serve (e.g., when using a CI/CD build system), then you won't be able to retrieve the date of the file, not to mention caching it!
  - Straight to the point: using the Git Hooks mechanism, you can trigger custom scripts when specific Git actions occur, such as every time you make a commit (hook installation is optional)
2. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
  - Workaround: use JSONL instead of JSON, and with the merge strategy merge=union
3. How to speed up the build when there are more documents ( > 200 )? Every time you fetch a git information, it's usually a file I/O operation, and if there are a lot of files, it can slow down the build considerably, which is intolerable for users (e.g., git-revision-date-localized can only improve the preview speed by adding the environment variable enabled: !ENV to disable itself locally, which is a bit like burying one's head in the sand)
  - Solution: skip unnecessary I/O access and reduce the number of I/O operations
Improve:
- Since it's a newly developed plugin, it will be designed in the direction of excellent products, and the pursuit of the ultimate ease of use, simplicity, personalization, intelligence
  - Ease of use: no complex configuration, only 2-3 commonly used configuration items, one-click templates are also provided for personalized
  - Simplicity: no unnecessary configuration, no-Git dependencies, no CI/CD configuration dependencies, no other package dependencies
  - Personalization: fully customizable and full control over the rendering logic, the plugin is only responsible for providing the data
  - Intelligence: Intelligent parsing of document date, author, avatar, intelligent recognition of the user's language and automatic adaptation
  - Compatibility: works well on older operating systems and browsers, such as Windows 7, MacOS 10, iOS 12, Chrome 63

mkdocs-document-dates¶

Features¶

Installation¶

Configuration¶

Settings¶

Date & Time¶

Loading order¶

Customization¶

Cache creation date¶

Configure git fetch depth¶

Author¶

Loading order¶

Customization¶

Enhanced author configuration¶

Git author aggregation¶

Avatar¶

Loading order¶

Customization¶

Other avatars¶

Structure and Style¶

Configuration structure¶

Configuration style¶

Template Variables¶

Set correct `lastmod` for sitemap¶

Recustomize plugin¶

Recently Updated Module¶

Config switch¶

Add to sidebar navigation¶

Add anywhere in document¶

Configure article cover¶

Localization Language¶

For tooltip¶

For timeago¶

Development Stories¶

Comments Section¶

Build Speed Comparison:	100 md:	1000 md:	Time Complexity:
git-revision-date-localized git-authors	＞ 3 s	＞ 30 s	O(n)
document-dates	＜ 0.1 s	＜ 0.15 s	O(1)

mkdocs-document-dates¶

Features¶

Installation¶

Configuration¶

Settings¶

Date & Time¶

Loading order¶

Customization¶

Cache creation date¶

Configure git fetch depth¶

Author¶

Loading order¶

Customization¶

Enhanced author configuration¶

Git author aggregation¶

Avatar¶

Loading order¶

Customization¶

Other avatars¶

Structure and Style¶

Configuration structure¶

Configuration style¶

Template Variables¶

Set correct lastmod for sitemap¶

Recustomize plugin¶

Recently Updated Module¶

Config switch¶

Add to sidebar navigation¶

Add anywhere in document¶

Configure article cover¶

Localization Language¶

For tooltip¶

For timeago¶

Development Stories¶

Comments Section¶

Set correct `lastmod` for sitemap¶