**git-authors** | ＞ 3 s | ＞ 30 s | O(n) |
+ | **document-dates** | ＜ 0.1 s | ＜ 0.15 s | O(1) |
+
+!!! tip "Infrastructure support"
+
+ In addition, this plugin completely resolved date and time infrastructure issues, enabling the project to support automated date processing. **Manual date configuration is no longer required for any feature**, including: page date display, blog post dates, blog date archives, blog list sorting, sitemap.xml (lastmod - SEO improvements), RSS feeds, recently updated section, search ranking, and more.
+
+## Installation
+
+This plugin is built-in and does not require separate installation. If you wish to install it individually, you may use the following command:
+
+=== "Install"
+
+ ```bash
+ pip install mkdocs-document-dates
+ ```
+
+=== "Upgrade"
+
+ ```bash
+ pip install --upgrade mkdocs-document-dates
+ ```
+
+## Configuration
+
+Add the following lines to `mkdocs.yml`:
+
+```yaml
+plugins:
+ - document-dates
+```
+
+Or, common configuration:
+
+```yaml
+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
+```
+
+The following configuration options are supported:
+
+
+
+: This option specifies the display position of the plugin.
+ Valid values are `top`, `bottom`:
+
+ ```yaml
+ plugins:
+ - document-dates:
+ position: top
+ ```
+
+
+
+: This option specifies the type of date to be displayed.
+ Valid values are `date`, `datetime`, `timeago`:
+
+ ```yaml
+ plugins:
+ - document-dates:
+ type: date
+ ```
+
+
+
+: This option specifies a list of excluded files, supporting unix shell-style wildcards, such as `*`, `?`, `[]` etc:
+
+ ```yaml
+ plugins:
+ - document-dates:
+ exclude:
+ - 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
+ ```
+
+
+
+: This option specifies the date formatting string:
+
+ ```yaml
+ plugins:
+ - document-dates:
+ date_format: '%Y-%m-%d' # e.g., %Y-%m-%d, %b %d, %Y
+ time_format: '%H:%M:%S' # valid only if type=datetime
+ ```
+
+
+
+: This option specifies whether to display the creation date.
+ Valid values are `true`, `false`:
+
+ ```yaml
+ plugins:
+ - document-dates:
+ show_created: true
+ ```
+
+
+
+: This option specifies whether to display the last updated date.
+ Valid values are `true`, `false`:
+
+ ```yaml
+ plugins:
+ - document-dates:
+ show_updated: true
+ ```
+
+
+
+: This option specifies the type of author display.
+ Valid values are `true`(avatar), `false`(hidden), `text`(text):
+
+ ```yaml
+ plugins:
+ - document-dates:
+ show_author: true # true(avatar) text(text) false(hidden)
+ ```
+
+## 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 timestamp** to ensure accurate original dates in local no-Git environments
+- Uses **Git timestamp** to ensure relatively accurate dates in Git environments
+- Uses **cache file** 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
+
+??? desc "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.
+
+```mermaid
+%%{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
+```
+
+
+
+!!! quote ""
+
+ === "Creation date"
+
+ 1. Prioritize reading the custom creation date in Front Matter
+ 2. Then read the creation date in the cache file
+ 3. Next read the document’s first git commit date as the creation date
+ 4. Finally read the file’s creation time
+
+ === "Last updated"
+
+ 1. Prioritize reading the custom last updated date in Front Matter
+ 2. Then read the document’s last git commit date as the last updated date
+ 3. 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`
+
+```yaml
+---
+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:
+
+```yaml hl_lines="6 7" title=".github/workflows/ci.yaml"
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+```
+
+!!! quote ""
+ - **Github** Actions: set `fetch-depth` to `0` ([docs](https://github.com/actions/checkout))
+ - **Gitlab** Runners: set `GIT_DEPTH` to `0` ([docs](https://docs.gitlab.com/ee/ci/pipelines/settings.html#limit-the-number-of-changes-fetched-during-clone))
+ - **Bitbucket** pipelines: set `clone: depth: full` ([docs](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/))
+ - **Azure** Devops pipelines: set `Agent.Source.Git.ShallowFetchDepth` to something very high like `10e99` ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/repos/pipeline-options-for-git?view=azure-devops#shallow-fetch))
+
+### 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.
+
+```mermaid
+%%{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
+```
+
+
+
+!!! quote ""
+
+ === "Description"
+
+ 1. Prioritize reading custom authors in Front Matter
+ 2. Then read the Git author
+ 3. Next read the site_author in mkdocs.yml
+ 4. Finally read the PC username
+
+#### Customization
+
+Can be configured in Front Matter in the following ways:
+
+1) Configure a simple author: via field `name`
+
+```yaml
+---
+name: any-name
+email: e-name@gmail.com
+---
+```
+
+2) Configure one or more authors: via field `authors`
+
+```yaml
+---
+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:
+
+```yaml title="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](https://git-scm.com/docs/gitmailmap) for more details.
+
+The following example unifies my other Git accounts and displays them as `Aaron `:
+
+```yaml title=".mailmap"
+Aaron
+Aaron
+Aaron aaron
+```
+
+### Avatar
+
+#### Loading order
+
+The plugin will **automatically** loads the author avatar in the following order.
+
+```mermaid
+%%{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](#enhanced-author-configuration) (supports URL paths and local file paths).
+
+#### Other avatars
+
+!!! quote ""
+
+ === "Online avatar"
+
+ Load from Gravatar or Weavatar based on Git's `user.email`
+
+ === "Character avatar"
+
+ 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:
+
+```yaml title="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):
+
+```yaml
+---
+show_created: true
+show_updated: true
+show_author: text
+---
+```
+
+!!! warning "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](https://github.com/jaywhj/mkdocs-document-dates/tree/main/mkdocs_document_dates/static/config)
+
+### Template Variables
+
+You can use these variables in any template or plugin to access document metadata:
+
+```py
+page.meta.document_dates.dates.created
+page.meta.document_dates.dates.updated
+page.meta.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 `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](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/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](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/partials/source-file.html), and override this path `docs/overrides/partials/source-file.html`, then freely customize the template code
+
+### Recently Updated Module
+
+The recent updates module displays site documentation information in a structured way, which is ideal for sites with **a large number of documents or frequent updates**, allowing readers to **quickly see what's new**.
+
+
+
+You can get the recently updated document data (in descending order of update date) in any template via the variable `config.extra.recently_updated_docs`, then customize the rendering logic yourself.
+
+Or just use the preset template:
+
+- Display recently updated documents in descending order by update time, list items are dynamically updated
+- Support multiple view modes including list, detail and grid
+- Support automatic extraction of article summaries, no manual configuration required
+- Support for customizing article cover in Front Matter
+
+#### Config switch
+
+First, configure the switch of `recently-updated` in `document-dates`:
+
+```yaml title="mkdocs.yml"
+- document-dates:
+ ...
+ recently-updated:
+ limit: 10 # Limit the number of docs displayed
+ exclude: # Exclude documents you don't want to show (support unix shell-style wildcards)
+ - index.md
+ - blog/*
+```
+
+#### Add to sidebar navigation
+
+Download the sample template [nav.html](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/partials/nav.html), and override this path `docs/overrides/partials/nav.html`
+
+#### Add anywhere in document
+
+Insert this line anywhere in your document:
+
+```yaml
+
+```
+
+#### Configure article cover
+
+You can specify an article cover in Front Matter using the field `cover` (supports URL paths and local file paths):
+
+```yaml
+---
+cover: assets/cat.jpg
+---
+```
+
+#### Summary Line Configuration
+
+The plugin intelligently parses article content and simply refine the summary without manual configuration. The number of summary lines can be configured separately for **grid** and **detail** views:
+
+```yaml hl_lines="9-11"
+plugins:
+
+ - document-dates:
+ type: timeago
+ exclude: ['index.md', '*/index.md', 'blog/*']
+ recently-updated:
+ limit: 10
+ exclude: ['index.md', 'tags.md', '*/index.md', 'blog/*']
+ summary_lines:
+ grid: 4
+ detail: 6
+```
+
+#### Reading Time Estimation
+
+The plugin intelligently analyzes article content, extracts valid information, and estimates readtime. It **supports all major languages** and mixed-language content:
+
+- CJK languages: Chinese, Japanese, Korean
+- Space-delimited languages: English, Spanish, French, German, Portuguese, Russian ...
+
+Calculation Rules:
+
+| Valid Element | Calculation Method | Notes |
+| --- | --- | --- |
+| CJK languages | 480 characters / min | Based on common industry standards |
+| Space-delimited languages | 240 words / min | Based on common industry standards |
+| Tables | 2s / row | Simple row-based estimation for variable-length content |
+| Fence blocks | 1s / row | Includes code blocks, text blocks, YAML blocks, etc. |
+| Math blocks | 4s / block | Rough estimation based on individual blocks |
+| Images | 2s / image | Typical for blog post images: 2~3 seconds per image |
+| Front Matter | Skipped | Generally not visible after rendering |
+| HTML blocks | Skipped | Images inside HTML are counted, other content ignored (Markdown-focused) |
+| Quotes & links | Skipped | Link text for href is generally not visible after rendering |
+| Other invalid characters | Skipped | For example, whitespace, blank lines, special symbols, markup characters, etc. |
+
+
+!!! info "Estimation Rule Notes"
+
+ These rules cannot fully account for individual reading habits—reading speed varies by person, language, and content type. This is only a rough estimate designed to suit most users as closely as possible.
+
+ That said, this is still the most full-featured Markdown readtime parser I have seen publicly available. It supports all major languages while maintaining extremely high parsing performance. By comparison, readtime implementations in the mkdocs-material blog only perform simple word and image counting with no special handling for Markdown content. Its image readtime rules are also highly unreasonable (starting at 12 seconds per image and decreasing), and it does not support CJK languages.
+
+ To avoid discouraging clicks with overly long estimated times, the default values in this calculation logic are set conservatively.
+
+### 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.
+
+#### For tooltip
+
+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](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) 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](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) to add it by registering yourself
+- In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to reload [all locales](https://github.com/hustcc/timeago.js/tree/master/src/lang)
+ ```yaml title="mkdocs.yml"
+ extra_javascript:
+ - assets/document_dates/core/timeago.full.min.js
+ ```
+
+## Developer API
+
+This plugin also provides a date data API for developers, making it easy to retrieve exact dates in other plugins or hooks:
+
+!!! quote ""
+
+ **load_dates_and_authors(docs_dir_path: Path, files: Files)**
+
+ Parameters:
+
+ - `docs_dir_path` (Path) - path to the docs directory of the project
+ - `files` (Files) - global files collection
+
+ Returns:
+
+ - `Dict[str, Dict[str, Any]]` - a dictionary containing all documents, built from the document relative path, date, author, and other information
+
+You can use this function to retrieve the date and author information for all site documents at once, it returns either Git or file-system-based dates and authors for each document, with the data structure as follows:
+
+``` json
+{
+ 'index.md': {
+ 'created': datetime.datetime(2025,1,28,16,50,13,tzinfo=datetime.timezone.utc),
+ 'updated': datetime.datetime(2026,4,13,9,38,13,331080,tzinfo=datetime.timezone.utc),
+ 'authors': [
+ {'name': name, 'email': email, 'avatar': avatar, 'url': url, 'description': description},
+ ...
+ ]
+ },
+ 'website.md': {
+ 'created': datetime.datetime(2025,5,19,3,20,39,tzinfo=datetime.timezone.utc),
+ 'updated': datetime.datetime(2026,3,3,3,52,50,364383,tzinfo=datetime.timezone.utc),
+ 'authors': [
+ {'name': name, 'email': email, 'avatar': avatar, 'url': url, 'description': description},
+ ...
+ ]
+ },
+ ...
+}
+```
+
+An example of calling the function is shown below:
+
+``` py
+from mkdocs_document_dates.utils import load_dates_and_authors
+from pathlib import Path
+from datetime import datetime
+
+def __init__(self):
+ super().__init__()
+ self.date_data = {}
+
+# First, call the API in `Global Events` to read data and store it
+def on_files(self, files, config):
+
+ ddPlugin = config.plugins.get("document-dates")
+ if ddPlugin:
+ self.date_data = ddPlugin.data_cached
+ else:
+ self.date_data = load_dates_and_authors(Path(config.docs_dir), files)
+
+ return files
+
+# Then, access the data via the relative path of page.file in `Page Events`
+def on_page_markdown(self, markdown, page: Page, config, files):
+
+ rel_path = getattr(page.file, 'src_uri')
+
+ created: datetime = self.date_data[rel_path]['created']
+ updated: datetime = self.date_data[rel_path]['updated']
+
+ authors = self.date_data[rel_path]['authors']
+ for author in authors:
+ author.name
+ author.email
+ author.avatar
+ author.url
+ author.description
+ ...
+```
+
+!!! warning "Note"
+
+ - Do not call the API function in [Page Events](https://properdocs.org/dev-guide/plugins/#page-events){target="_blank"}, it should only be called **once** in [Global Events](https://properdocs.org/dev-guide/plugins/#global-events){target="_blank"}. For the event lifecycle, please refer to [Events](https://properdocs.org/dev-guide/plugins/#events){target="_blank"}.
+ - The API function does not parse markdown content, so the date and author in frontmatter need to be handled separately by you. For example, you can get the date and author configured by the user in frontmatter via `page.meta.xxx` in `on_page_markdown`, like this:
+
+ ``` py
+ ...
+
+ def on_page_markdown(self, markdown, page: Page, config, files):
+
+ created_str = page.meta.get('created')
+ if created_str:
+ created: datetime = datetime.fromisoformat(created_str).astimezone()
+ else:
+ rel_path = getattr(page.file, 'src_uri')
+ created: datetime = self.date_data[rel_path]['created']
+
+ ...
+ ```
diff --git a/docs/plugins/index.md b/docs/plugins/index.md
index dd5e89afb0..02ea0ca705 100644
--- a/docs/plugins/index.md
+++ b/docs/plugins/index.md
@@ -1,121 +1,183 @@
-# Built-in plugins
+---
+status: new
+---
-Material for MkDocs started out as a theme for [MkDocs][mkdocs], but has since
-evolved into a full-fledged framework for building and maintaining documentation.
-The theme is still the core of the project, but it's now accompanied by a
-growing number of complementary built-in plugins.
+# Plugin recommendation
-We strive to make those plugins as modular and generic as possible, so that they
-can be used in a wide variety of projects and use cases. By providing useful
-default settings, we also try to make them as easy to use as possible, so that
-you can get started quickly, tweaking their settings later on. When
-developing built-in plugins, we always adhere to the following design principles:
+MkDocs boasts a rich ecosystem of plugins that can satisfy a wide range of user customization needs, this is also one of the main reasons why the MkDocs is so popular.
-- **Modularity:** Built-in plugins are designed to be modular, so that they can
- be easily combined to implement sophisticated pipelines. For example, the
- [offline], [optimize] and [privacy] plugins can be used together to build
- truly offline-capable documentation.
+[category](https://github.com/ProperDocs/catalog){target="_blank"} groups most plugins by category. Below, I will select practical ones for recommendation based on the following criteria:
-- **Interoperability:** Built-in plugins are designed to be as compatible as
- possible, so they can be used in combination with other plugins, including
- third-party plugins. We strive to make it simple to integrate with the vast
- ecosystem that has evolved around [MkDocs][mkdocs].
+- Practical and concise
+- Good performance
+- Actively maintained (updated within the last year)
-- **Performance:** Built-in plugins are designed to be as fast and
- memory-efficient as possible, so that they don't unnecessarily slow down
- builds. This is particularly important for large documentation projects with
- thousands of pages.
+Contributions and PRs are welcome.
- [mkdocs]: https://www.mkdocs.org/
- [design principles]: ../design-principles.md
+## External plugins
-## Categories
+External plugins are developed by third-party developers and require manual installation.
-### Management
+### Graphics & Charts
-The following plugins greatly improve the authoring experience when working on
-documentation projects by providing better management capabilities, from the
-management of plugins, multiple projects, and metadata, to the creation of
-minimal reproductions for bug reports:
+???+ tip "[mkdocs-glightbox][glightbox] - click to open the image as a lightbox"
-
+ 
-- :material-format-list-group: __[Built-in group plugin][group]__
+???+ tip "[mkdocs-drawio][drawio] - embed interactive drawio diagrams in documents"
- ---
+ === "Rendering"
- The group plugin allows to group plugins into logical units to conditionally
- enable or disable them for specific environments with the use of
- [environment variables][mkdocs.env].
+ 
- ---
+ === "Usage"
- __Optimal management of plugins when building in different environments__
+ ```markdown
+
+
+ 
+ ```
-- :material-file-tree: __[Built-in meta plugin][meta]__
+???+ tip "[mkdocs-mermaid2-plugin][mermaid2] - renders mermaid text into diagrams (built-in)"
- ---
+ === "Rendering"
- The meta plugin makes it easy to manage metadata (front matter) for all
- pages in a folder, so a certain subset of pages uses specific tags or a
- custom template.
+ ```mermaid
+ %%{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
+ ```
- ---
+ === "Usage"
- __Simpler organization, categorization and management of metadata__
+ ````
+ ```mermaid
+ %%{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
+ ```
+ ````
+??? tip "[mkdocs-markmap][markmap] - create interactive mind maps from markdown and embed them in documents"
-
+ **Usage**: use `markmap` fence blocks to enclose markdown content
- [group]: group.md
- [info]: info.md
- [meta]: meta.md
+ `````
+ ````markmap
-### Optimization
+ ## Mind Map
-The following plugins are designed to help you build optimized documentation,
-making it more accessible to your users through faster loading times, better
-search engine rankings, beautiful preview images on social media, and GDPR
-compliance with a few lines of configuration:
+ ### Fence Block Enclosure
-
+ - That's great. Anything
-- :material-share-circle: __[Built-in social plugin][social]__
+ ### Formatting and Lists
- ---
+ - **strong** ~~del~~ *italic* ==highlight==
+ - `inline code`
+ - [x] checkbox
+ - Katex: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
- The social plugin automatically generates beautiful and customizable
- social cards for each page of your documentation, showing as previews on
- social media.
+ ### Code block
- ---
+ ```js
+ for (let i = 0; i < 5; i++) {
+ console.log("value", i);
+ }
+ ```
- __Links to your site render beautiful social cards when shared on social
- media__
+ ### Table block
-- :material-rabbit: __[Built-in optimize plugin][optimize]__
+ | Header1 | Header2 |
+ | --- | --- |
+ | item 1 | 1\. one 2\. two |
- ---
+ ### Image
- The optimize plugin automatically identifies and optimizes all media files
- that you reference in your project by using compression and conversion
- techniques.
+ 
- ---
+ ````
+ `````
- __Your site loads faster as smaller images are served to your users__
+
+
+
+
+
+- :material-rabbit: __[Built-in optimize plugin][optimize]__
---
- The privacy plugin downloads external assets automatically for easy
- self-hosting, allowing for GDPR compliance with a single line of
- configuration.
+ The optimize plugin automatically identifies and optimizes all media files
+ that you reference in your project by using compression and conversion
+ techniques.
---
- __Your documentation can be made GDPR compliant with minimal effort__
+ __Your site loads faster as smaller images are served to your users__
- :material-connection: __[Built-in offline plugin][offline]__
@@ -131,6 +193,7 @@ compliance with a few lines of configuration:
+ [group]: group.md
[offline]: offline.md
[optimize]: optimize.md
[privacy]: privacy.md
@@ -138,37 +201,31 @@ compliance with a few lines of configuration:
### Content
-The following plugins are designed to help you set up a blog, provide search
-functionality to your users, add tags to pages and posts, and use the same
-typesetting capabilities in specific parts of the documentation exactly as in
-the main content:
-
-- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+- :material-magnify: __[Built-in search plugin][search]__
---
- The blog plugin adds first-class support for blogging to Material for
- MkDocs, either as a sidecar to your documentation or as a standalone
- installation.
+ The search plugin adds a search bar to the header, allowing users to search
+ the entire documentation, so it's easier for them to find what they're
+ looking for.
---
- __Your blog is built with the same powerful engine as your documentation__
+ __Your documentation is searchable without any external services, even
+ offline__
-- :material-magnify: __[Built-in search plugin][search]__
+- :material-account-clock-outline: __[Built-in document-dates plugin][document-dates]__
---
- The search plugin adds a search bar to the header, allowing users to search
- the entire documentation, so it's easier for them to find what they're
- looking for.
+ The document-dates plugin adds date and author to your documents. It's __20-500 times faster__ than `git-authors` and
+ `git-revision-date-localized`.
---
- __Your documentation is searchable without any external services, even
- offline__
+ __Manual date configuration is no longer required for any feature__
- :material-tag-text: __[Built-in tags plugin][tags]__
@@ -182,14 +239,25 @@ the main content:
__Your pages are categorized with tags, yielding additional context__
+- :material-newspaper-variant-outline: __[Built-in blog plugin][blog]__
+
+ ---
+
+ The blog plugin adds first-class support for blogging to MaterialX for
+ MkDocs, either as a sidecar to your documentation or as a standalone
+ installation.
+
+ ---
+
+ __Your blog is built with the same powerful engine as your documentation__
+
+ [document-dates]: date-author.md
[blog]: blog.md
[search]: search.md
[tags]: tags.md
-## Architecture
-
### Multiple instances
Several built-in plugins have support for multiple instances, which means that
diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md
index cdefcce26b..74ee60f725 100644
--- a/docs/reference/admonitions.md
+++ b/docs/reference/admonitions.md
@@ -1,4 +1,5 @@
---
+status: new
icon: material/alert-outline
---
@@ -399,7 +400,7 @@ You can configure the icon and color for each built-in admonition type, and also
- !!! example-new "← Reset icon for `example`"
+ !!! example-new "← Reset icon for type `example`"
@@ -411,19 +412,27 @@ You can configure the icon and color for each built-in admonition type, and also
git:
icon: simple/git
color: '#f34f29'
- desc:
- icon: octicons/sort-desc-24
- color: rgba(158, 158, 158, 0.7)
- pied-piper:
- icon: fontawesome/brands/pied-piper-alt
- color: '#2b9b46'
+ copyright:
+ icon: material/copyright
+ color: '#2b9b9b'
+ heart:
+ icon: octicons/heart-24
+ color: '#9b2b9b'
+ lyrics:
+ icon: material/microphone
+ color: '#2b2b9b'
+ soundcloud:
+ icon: simple/soundcloud
+ color: '#ff7700'
```
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 019e3c558d..ce7daa8a79 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -107,13 +107,13 @@ extra:
```
1. The identifier can only include alphanumeric characters, as well as dashes
- and underscores. For example, if you have a status `Recently added`, you can
+ and underscores. For example, if you have a status `Recently updated`, you can
set `new` as an identifier:
``` yaml
extra:
status:
- new: Recently added
+ new: Recently updated
```
The page status can now be set with the front matter `status` property. For
@@ -134,12 +134,22 @@ The following status identifiers are already defined:
- :material-alert-decagram: – `new`
- :material-trash-can: – `deprecated`
+#### Custom page status
+
You can define a custom page status this way but if you want it to
have an icon other than the default one you need to also configure
-that in your `extra.css`. We have an [example for a custom
-page status] to get you started.
+that in your `extra.css`.
+
+``` css title="extra.css"
+:root {
+ --md-status--happy: url('data:image/svg+xml;charset=utf-8,')
+}
-[example for a custom page status]: https://mkdocs-material.github.io/examples/page-status/
+.md-status--happy::after {
+ mask-image: var(--md-status--happy);
+ -webkit-mask-image: var(--md-status--happy);
+}
+```
### Setting the page `subtitle`
diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md
index d7f53c9d5b..256d6235a2 100644
--- a/docs/setup/adding-a-git-repository.md
+++ b/docs/setup/adding-a-git-repository.md
@@ -174,129 +174,9 @@ You can add date and author information to your documents via the next-generatio
-#### Installation
+For more details: [Date & authors](adding-document-dates-authors.md)
-Install it with `pip`:
-
-```
-pip install mkdocs-document-dates
-```
-
-Then, add the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
- - document-dates
-```
-
-#### Configuration
-
-The following configuration options are supported:
-
-
-
-: This option specifies the display position of the plugin.
- Valid values are `top`, `bottom`:
-
- ``` yaml
- plugins:
- - document-dates:
- position: top
- ```
-
-
-
-: This option specifies the type of date to be displayed.
- Valid values are `date`, `datetime`, `timeago`:
-
- ``` yaml
- plugins:
- - document-dates:
- type: date
- ```
-
-
-
-: This option specifies a list of excluded files, supporting unix shell-style wildcards:
-
- ``` yaml
- plugins:
- - document-dates:
- exclude:
- - 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
- ```
-
-
-
-: This option specifies the date formatting string:
-
- ``` yaml
- plugins:
- - document-dates:
- date_format: '%Y-%m-%d' # e.g., %Y-%m-%d, %b %d, %Y
- time_format: '%H:%M:%S' # valid only if type=datetime
- ```
-
-
-
-: This option specifies whether to display the creation date.
- Valid values are `true`, `false`:
-
- ``` yaml
- plugins:
- - document-dates:
- show_created: true
- ```
-
- ??? note "When using build environments"
-
- If you are deploying through a CI system, you might need to adjust your
- CI settings when fetching the code:
-
- - Github Actions: set `fetch-depth` to `0` ([docs](https://github.com/actions/checkout))
- - Gitlab Runners: set `GIT_DEPTH` to `0` ([docs](https://docs.gitlab.com/ee/ci/pipelines/settings.html#limit-the-number-of-changes-fetched-during-clone))
- - Bitbucket pipelines: set `clone: depth: full` ([docs](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/))
- - Azure Devops pipelines: set `Agent.Source.Git.ShallowFetchDepth` to something very high like `10e99` ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/repos/pipeline-options-for-git?view=azure-devops#shallow-fetch))
-
-
-
-: This option specifies whether to display the last updated date.
- Valid values are `true`, `false`:
-
- ``` yaml
- plugins:
- - document-dates:
- show_updated: true
- ```
-
-
-
-: This option specifies the type of author display.
- Valid values are `true`(avatar), `false`(hidden), `text`(text):
-
- ``` yaml
- plugins:
- - document-dates:
- show_author: true # true(avatar) text(text) false(hidden)
- ```
-
- [document-dates]: https://github.com/jaywhj/mkdocs-document-dates
-
-#### Customization settings
-
-In addition to the above basic configuration, the plug-in also provides a wealth of customization options to meet a variety of individual needs:
-
-- [Date & Time](adding-document-dates-authors.md#date-time): Introduces the mechanism for obtaining document dates and methods for personalized customization, support for manually specifying the creation date and last updated date for each document
-- [Author](adding-document-dates-authors.md#author): Introduces the mechanism for obtaining document authors and methods for personalized customization, support for manually specifying the author information for each document, such as name, link, avatar, email, etc.
-- [Avatar](adding-document-dates-authors.md#avatar): You can manually specify the avatar for each author, support local file path and URL path
-- [Structure and Style](adding-document-dates-authors.md#structure-and-style): You can freely configure the plugin's display structure in mkdocs.yml or Front Matter. You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on
-- [Template Variables](adding-document-dates-authors.md#template-variables): Can be used to optimize `sitemap.xml` for site SEO
-- [Recently Updated Module](adding-document-dates-authors.md#recently-updated-module): Enable list of recently updated documents (in descending order of update date), this is ideal for sites with a large number of documents, so that readers can quickly see what's new
-- [Localization Language](adding-document-dates-authors.md#localization-language): More localization languages for `timeago` and `tooltip`
-
-For more details: [Document dates & authors](adding-document-dates-authors.md)
+ [document-dates]: ../plugins/date-author.md
### Document contributors
diff --git a/docs/setup/adding-document-dates-authors.md b/docs/setup/adding-document-dates-authors.md
index 61e81114ca..9b1ccb96b5 100644
--- a/docs/setup/adding-document-dates-authors.md
+++ b/docs/setup/adding-document-dates-authors.md
@@ -5,66 +5,18 @@ icon: material/account-clock-outline
# Add document dates & authors
-
-
+You can add date and author information to your documents via the built-in plugin [document-dates], a new generation MkDocs plugin for displaying exact creation date, last updated date, authors, email of documents.
-You can add date and author information to your documents via the plugin [document-dates], a new generation MkDocs plugin for displaying exact **creation date, last updated date, authors, email** of documents.
+It's __20-500 times faster__ than `git-revision-date-localized` and `git-authors`, and works in any environment (no-Git, Git environments, Docker, all CI/CD build systems, etc.).
-
+In addition, this plugin completely resolved date and time infrastructure issues, enabling the project to support automated date processing. **Manual date configuration is no longer required for any feature**, including: page date display, blog post dates, blog date archives, blog list sorting, sitemap.xml (lastmod - SEO improvements), RSS feeds, recently updated section, search ranking, and more.
- [document-dates]: https://github.com/jaywhj/mkdocs-document-dates
-
-## 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
-
-This plugin is built-in and does not require separate installation. If you wish to install it individually, you may use the following command:
-
-=== "Install"
-
- ```bash
- pip install mkdocs-document-dates
- ```
-
-=== "Upgrade"
-
- ```bash
- pip install --upgrade mkdocs-document-dates
- ```
+ [document-dates]: ../plugins/date-author.md
## Configuration
-This plugin completely resolved date and time infrastructure issues, enabling the project to support automated date processing. **Manual date configuration is no longer required for any feature**, including: page date display, blog post dates, blog date archives, blog list sorting, sitemap.xml (lastmod - SEO improvements), RSS feeds, recently updated section, search ranking, and more.
-
-!!! tip "Prerequisite"
-
- You need to configure it in the `plugins` section to enable it first.
-
Add the following lines to `mkdocs.yml`:
-```yaml
-plugins:
- - document-dates
-```
-
-Or, common configuration:
-
```yaml
plugins:
- document-dates:
@@ -76,142 +28,27 @@ plugins:
- '*/index.md' # Example: exclude all index.md files in any subfolders
```
-The following configuration options are supported:
-
-
-
-: This option specifies the display position of the plugin.
- Valid values are `top`, `bottom`:
-
- ```yaml
- plugins:
- - document-dates:
- position: top
- ```
-
-
-
-: This option specifies the type of date to be displayed.
- Valid values are `date`, `datetime`, `timeago`:
-
- ```yaml
- plugins:
- - document-dates:
- type: date
- ```
-
-
-
-: This option specifies a list of excluded files, supporting unix shell-style wildcards, such as `*`, `?`, `[]` etc:
-
- ```yaml
- plugins:
- - document-dates:
- exclude:
- - 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
- ```
-
-
-
-: This option specifies the date formatting string:
-
- ```yaml
- plugins:
- - document-dates:
- date_format: '%Y-%m-%d' # e.g., %Y-%m-%d, %b %d, %Y
- time_format: '%H:%M:%S' # valid only if type=datetime
- ```
-
-
-
-: This option specifies whether to display the creation date.
- Valid values are `true`, `false`:
-
- ```yaml
- plugins:
- - document-dates:
- show_created: true
- ```
-
-
-
-: This option specifies whether to display the last updated date.
- Valid values are `true`, `false`:
-
- ```yaml
- plugins:
- - document-dates:
- show_updated: true
- ```
-
-
+
-: This option specifies the type of author display.
- Valid values are `true`(avatar), `false`(hidden), `text`(text):
+Some common features are listed below. For a more complete and systematic introduction, please refer to [Built-in Date Plugin][document-dates].
- ```yaml
- plugins:
- - document-dates:
- show_author: true # true(avatar) text(text) false(hidden)
- ```
-
- [document-dates]: https://github.com/jaywhj/mkdocs-document-dates
-
-## Settings
-
-The plugin provides a wide range of customization options to meet various personalized needs.
-
-### Date & Time
+## 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
+- Uses **filesystem timestamp** to ensure accurate original dates in local no-Git environments
+- Uses **Git timestamp** to ensure relatively accurate dates in Git environments
+- Uses **cache file** 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
-??? desc "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.
-
-```mermaid
-%%{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
-```
-
-
-
-!!! quote ""
+### Loading order
- === "Creation date"
+By default, the plugin will **automatically load** the document's "creation date" and "last updated date" in the following order:
- 1. Prioritize reading the custom creation date in Front Matter
- 2. Then read the creation date in the cache file
- 3. Next read the document’s first git commit date as the creation date
- 4. Finally read the file’s creation time
-
- === "Last updated"
+- Creation date: `Front Matter` > `Cache File` > `Git Timestamp` > `File Timestamp`
+- Last updated: `Front Matter` > `Git Timestamp` > `File Timestamp`
- 1. Prioritize reading the custom last updated date in Front Matter
- 2. Then read the document’s last git commit date as the last updated date
- 3. Finally read the file’s modification time
-
-#### Customization
+### Customization
This can be specified in Front Matter using the following fields:
@@ -225,74 +62,15 @@ 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`.
+## Author
-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.
+### Loading order
-- `docs/.dates_cache.jsonl`, cache file
-- `docs/.gitattributes`, merge mechanism for cache file
+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:
-This method is compatible with CI/CD build systems, which will automatically detect and load the cache file.
+- `Front Matter` > `Git Author` > `site_author(mkdocs.yml)` > `PC Username`
-#### 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:
-
-```yaml hl_lines="6 7" title=".github/workflows/ci.yaml"
-jobs:
- deploy:
- runs-on: ubuntu-latest
- steps:
- - uses: actions/checkout@v4
- with:
- fetch-depth: 0
-```
-
-!!! quote ""
-
- - **Github** Actions: set `fetch-depth` to `0` ([docs](https://github.com/actions/checkout))
- - **Gitlab** Runners: set `GIT_DEPTH` to `0` ([docs](https://docs.gitlab.com/ee/ci/pipelines/settings.html#limit-the-number-of-changes-fetched-during-clone))
- - **Bitbucket** pipelines: set `clone: depth: full` ([docs](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/))
- - **Azure** Devops pipelines: set `Agent.Source.Git.ShallowFetchDepth` to something very high like `10e99` ([docs](https://docs.microsoft.com/en-us/azure/devops/pipelines/repos/pipeline-options-for-git?view=azure-devops#shallow-fetch))
-
-### 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.
-
-```mermaid
-%%{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
-```
-
-
-
-!!! quote ""
-
- === "Description"
-
- 1. Prioritize reading custom authors in Front Matter
- 2. Then read the Git author
- 3. Next read the site_author in mkdocs.yml
- 4. Finally read the PC username
-
-#### Customization
+### Customization
Can be configured in Front Matter in the following ways:
@@ -316,7 +94,7 @@ authors:
---
```
-#### Enhanced author configuration
+### 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:
@@ -338,42 +116,19 @@ authors:
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
+## Avatar
-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](https://git-scm.com/docs/gitmailmap) for more details.
+### Loading order
-The following example unifies my other Git accounts and displays them as `Aaron `:
+The plugin will **automatically** loads the author avatar in the following order:
-```yaml title=".mailmap"
-Aaron
-Aaron
-Aaron aaron
-```
+- `Front Matter` > `Online Avatar` > `Character Avatar`
-### Avatar
-
-#### Loading order
-
-The plugin will **automatically** loads the author avatar in the following order.
-
-```mermaid
-%%{init: {'theme': 'default', 'themeVariables': {'fontSize': '12px'}}}%%
-flowchart LR
- A(1.Front Matter)
- B(2.Online Avatar)
- C(3.Character Avatar)
- A -.-> B -.-> C
-```
-
-
-
-#### Customization
+### Customization
Customizable via `avatar` field in [Enhanced author configuration](#enhanced-author-configuration) (supports URL paths and local file paths).
-#### Other avatars
+### Other avatars
!!! quote ""
@@ -383,15 +138,13 @@ Customizable via `avatar` field in [Enhanced author configuration](#enhanced-aut
=== "Character avatar"
- 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
+ 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
-#### Configuration structure
+You can control whether the component is rendered using the following configuration.
**Global Toggle**, configured in mkdocs.yml:
@@ -418,158 +171,6 @@ show_author: text
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](https://github.com/jaywhj/mkdocs-document-dates/tree/main/mkdocs_document_dates/static/config)
-
-### Template Variables
-
-You can use these variables in any template or plugin to access document metadata:
-
-- page.meta.document_dates.dates.created
-- page.meta.document_dates.dates.updated
-- page.meta.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 `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](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/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](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/partials/source-file.html), and override this path `docs/overrides/partials/source-file.html`, then freely customize the template code
-
-### Recently Updated Module
-
-The recent updates module displays site documentation information in a structured way, which is ideal for sites with **a large number of documents or frequent updates**, allowing readers to **quickly see what's new**.
-
-
-
-You can get the recently updated document data (in descending order of update date) in any template via the variable `config.extra.recently_updated_docs`, then customize the rendering logic yourself.
-
-Or just use the preset template:
-
-- Display recently updated documents in descending order by update time, list items are dynamically updated
-- Support multiple view modes including list, detail and grid
-- Support automatic extraction of article summaries, no manual configuration required
-- Support for customizing article cover in Front Matter
-
-#### Config switch
-
-First, configure the switch of `recently-updated` in `mkdocs.yml`:
-
-```yaml title="mkdocs.yml"
-- document-dates:
- ...
- recently-updated:
- limit: 10 # Limit the number of docs displayed
- exclude: # Exclude documents you don't want to show (support unix shell-style wildcards)
- - index.md
- - blog/*
-```
-
-#### Add to sidebar navigation
-
-Download the sample template [nav.html](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/partials/nav.html), and override this path `docs/overrides/partials/nav.html`
-
-#### Add anywhere in document
-
-Insert this line anywhere in your document:
-
-```yaml
-
-```
-
-#### Configure article cover
-
-You can specify an article cover in Front Matter using the field `cover` (supports URL paths and local file paths):
-
-```yaml
----
-cover: assets/cat.jpg
----
-```
-
-#### Summary Line Configuration
-
-The plugin intelligently parses article content and simply refine the summary without manual configuration. The number of summary lines can be configured separately for **grid** and **detail** views:
-
-```yaml hl_lines="9-11"
-plugins:
-
- - document-dates:
- type: timeago
- exclude: ['index.md', '*/index.md', 'blog/*']
- recently-updated:
- limit: 10
- exclude: ['index.md', 'tags.md', '*/index.md', 'blog/*']
- summary_lines:
- grid: 4
- detail: 6
-```
-
-#### Reading Time Estimation
-
-The plugin intelligently analyzes article content, extracts valid information, and estimates readtime. It supports all major languages and mixed-language content:
-
-- CJK languages: Chinese, Japanese, Korean
-- Space-delimited languages: English, Spanish, French, German, Portuguese, Russian ...
-
-Calculation Rules:
-
-| Valid Element | Calculation Method | Notes |
-| --- | --- | --- |
-| CJK languages | 480 characters / min | Based on common industry standards |
-| Space-delimited languages | 240 words / min | Based on common industry standards |
-| Tables | 2s / row | Simple row-based estimation for variable-length content |
-| Fence blocks | 1s / row | Includes code blocks, text blocks, YAML blocks, etc. |
-| Math blocks | 4s / block | Rough estimation based on individual blocks |
-| Images | 2s / image | Typical for blog post images: 2~3 seconds per image |
-| Front Matter | Skipped | Generally not visible after rendering |
-| HTML blocks | Skipped | Images inside HTML are counted, other content ignored (Markdown-focused) |
-| Quotes & links | Skipped | Link text for href is generally not visible after rendering |
-| Other invalid characters | Skipped | For example, whitespace, blank lines, special symbols, markup characters, etc. |
-
-
-!!! tip "Estimation Rule Notes"
-
- These rules cannot fully account for individual reading habits—reading speed varies by person, language, and content type. This is only a rough estimate designed to suit most users as closely as possible.
-
- That said, this is still the most full-featured Markdown readtime parser I have seen publicly available. It supports all major languages while maintaining extremely high parsing performance. By comparison, readtime implementations in the mkdocs-material blog only perform simple word and image counting with no special handling for Markdown content. Its image readtime rules are also highly unreasonable (starting at 12 seconds per image and decreasing), and it does not support CJK languages.
-
- To avoid discouraging clicks with overly long estimated times, the default values in this calculation logic are set conservatively.
-
-### 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.
-
-#### For tooltip
-
-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](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) 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](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) to add it by registering yourself
-- In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to reload [all locales](https://github.com/hustcc/timeago.js/tree/master/src/lang)
- ```yaml title="mkdocs.yml"
- extra_javascript:
- - assets/document_dates/core/timeago.full.min.js
- ```
+For a more complete and systematic introduction, please refer to [Built-in Date Plugin][document-dates].
\ No newline at end of file
diff --git a/docs/setup/adding-recent-updates-module.md b/docs/setup/adding-recent-updates-module.md
index 0a9680e235..ed82c4d1e9 100644
--- a/docs/setup/adding-recent-updates-module.md
+++ b/docs/setup/adding-recent-updates-module.md
@@ -5,9 +5,6 @@ icon: simple/lastpass
# Add recent updates module
-
-
-
The recent updates module displays site documentation information in a structured way, which is ideal for sites with **a large number of documents or frequent updates**, allowing readers to **quickly see what's new**.
@@ -26,11 +23,11 @@ The recent updates module displays site documentation information in a structure
This feature is provided by the built-in plugin [document-dates] and requires no separate installation.
- [document-dates]: https://github.com/jaywhj/mkdocs-document-dates
+ [document-dates]: ../plugins/date-author.md
## Configuration
-Configure the switch `recently-updated` in `mkdocs.yml`:
+Configure the switch `recently-updated` in `document-dates`:
```yaml title="mkdocs.yml"
- document-dates:
@@ -43,28 +40,6 @@ Configure the switch `recently-updated` in `mkdocs.yml`:
- blog/* # Example: exclude all files in blog folder, including subfolders
```
-The following configuration options are supported:
-
-
-
-: This option specifies the number of documents to be displayed.
-
-
-
-: This option specifies a list of documents to be excluded, supporting unix shell-style wildcards, such as `*`, `?`, `[]` etc.
-
-
-
-: This option configures the number of rows displayed in the summary for the grid and detail views.
-
-
-
- : Default 4 lines
-
-
-
- : Default 6 lines
-
## Add to sidebar navigation
Download the sample template [nav.html](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/partials/nav.html), and override this path `docs/overrides/partials/nav.html`
@@ -103,4 +78,8 @@ plugins:
summary_lines:
grid: 4
detail: 6
-```
\ No newline at end of file
+```
+
+
+
+For a more complete and systematic introduction, please refer to [Built-in Date Plugin][document-dates].
\ No newline at end of file
diff --git a/docs/setup/index.md b/docs/setup/index.md
index 6758de47d9..46e1739e89 100644
--- a/docs/setup/index.md
+++ b/docs/setup/index.md
@@ -64,14 +64,14 @@ versioned documentation that matches your project's versioning methodology.
- :material-book-open-outline: __[Blog]__ – Set up a standalone blog or host it alongside your documentation
- :material-comment-text-outline: __[Comment System]__ – Add a third-party comment system on any page or footer
- :octicons-repo-16: __[Repository]__ – Connect your documentation to your git repository
-- :material-account-clock-outline: __[Dates & Authors]__ – Adding dates and authors to your documents
+- :material-account-clock-outline: __[Date & Authors]__ – Adding dates and authors to your documents