mkdocs-document-dates 3.2.1__tar.gz → 3.3__tar.gz

{mkdocs_document_dates-3.2.1/mkdocs_document_dates.egg-info → mkdocs_document_dates-3.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.2.1
-Summary: A new generation MkDocs plugin for displaying exact meta-info of documents, such as creation time, last update time, authors, email, etc.
+Version: 3.3
+Summary: A new generation MkDocs plugin for displaying exact meta-info, such as creation time, last update time, authors, email, etc
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
 Author-email: aaronwqt@gmail.com
@@ -30,7 +30,7 @@ English | [简体中文](README_zh.md)
 
 
 
-A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc.
+A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc
 
 ## Features
 
@@ -40,10 +40,16 @@ A new generation MkDocs plugin for displaying exact meta-info of documents, such
 - Flexible display position (top or bottom)
 - Elegant styling (fully customizable)
 - Supports Tooltip Hover Tips
-  - Intelligent repositioning to always float optimally in view
+  - Intelligent dynamic positioning, always floating optimally in view
   - Supports automatic theme switching following Material's light/dark color scheme
 - Multi-language support, cross-platform support (Windows, macOS, Linux)
-- Ultimate build efficiency O(1), typically less than 0.2 seconds, regardless of whether the number of documents is 1,000 or 10,000
+- **Ultimate build efficiency**: O(1), typically less than 0.2 seconds
+
+| PK of Build Efficiency:     | 100 md: | 1000 md: | Time Complexity: |
+| --------------------------- | :-----: | :------: | :----------: |
+| git-revision-date-localized |  > 3 s   |  > 30 s   |    O(n)    |
+| document-dates              | < 0.1 s  | < 0.15 s  |    O(1)    |
+
 
 ## Showcases
 
@@ -69,52 +75,78 @@ Or, personalize the configuration:
 ```yaml
 plugins:
   - document-dates:
-      position: top            # Display position: top (after title)  bottom (end of document), default: bottom
+      position: top            # Display position: top (after title)  bottom (end of document)
       type: date               # Date type: date  datetime  timeago, default: date
+      exclude:                 # List of excluded files
+        - temp.md              # Exclude specific file
+        - drafts/*             # Exclude all files in drafts folder, including subfolders
       locale: en               # Localization: en zh zh_TW es fr de ar ja ko ru, default: en
       date_format: '%Y-%m-%d'  # Date format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
       time_format: '%H:%M:%S'  # Time format strings (valid only if type=datetime)
-      exclude:                 # List of excluded files
-        - temp.md              # Exclude specific file
-        - private/*            # Exclude all files in private folder, including subfolders
       show_author: true        # Show author or not, default: true
 ```
 
 ## Specify time manually
 
-The plugin will automatically get the exact time of the document, will automatically cache the creation time, but of course, you can also specify it manually in `Front Matter`
-
-Priority order: `Front Matter` > `File System Timestamps(Cached)` > `Git Timestamps`
-
-```yaml
----
-created: 2023-01-01
-modified: 2025-02-23
----
-
-# Document Title
-```
+By default, the plugin will **automatically** get the exact time of the document, and will automatically cache the creation time, without manual intervention
 
+- **Priority**: `Front Matter` > `File System Timestamps(Cached)` > `Git Timestamps`
+- If you want to customize it, you can specify it manually in Front Matter:
+    ```markdown
+    ---
+    created: 2023-01-01
+    modified: 2025-02-23
+    ---
+    
+    ```
 - `created` can be replaced with: `created, date, creation`
 - `modified` can be replaced with: `modified, updated, last_modified, last_updated`
 
-## Specify author manually
-
-The plugin will automatically get the author of the document, will parse the email and make a link, also you can specify it manually in `Front Matter`
+## Configure Author
 
-Priority order: `Front Matter` > `Git Author` > `site_author(mkdocs.yml)` > `PC Username`
+By default, the plugin will **automatically** get the author of the document, and will automatically parse the email and then do the link, without manual intervention
 
-```yaml
----
-author: any-name
-email: e-name@gmail.com
----
-
-# Document Title
-```
+- **Priority**: `Front Matter` > `Git Author` > `site_author(mkdocs.yml)` > `PC Username`
+- If you want to customize it, you can configure an author in Front Matter with the field `name`:
+    ```markdown
+    ---
+    name: any-name
+    email: e-name@gmail.com
+    ---
+    
+    ```
 
-- `author` can be replaced with: `author, name`
-- `email` can be replaced with: `email, mail`
+## Configure Avatar
+
+By default, the plugin will **automatically** loads the author avatar, without manual intervention
+
+**Priority**: `Custom Avatar` > `GitHub Avatar` > `Character Avatar`
+
+1. Character avatar: will be automatically generated based on the author's name with the following rules
+    - Extract initials: English takes the combination of initials, other languages take the first character
+    - Dynamic background color: Generate HSL color based on the hash of the name
+2. GitHub avatar: will be automatically loaded by parsing the `repo_url` property in mkdocs.yml
+3. Custom avatar: can be customized by customizing the author's `avatar` field in Front Matter
+    ```markdown
+    ---
+    # Way 1: Configure a full author
+    author:
+        name: jay
+        email: jay@qq.com
+        avatar: https://xxx.author-avatar-URL.com/xxx.png
+        url: https://xxx.website-URL.com/xxx
+        description: author description
+    
+    # Way 2: Configure multiple authors
+    authors:
+        - jaywhj
+        - squidfunk
+        - sunny
+    
+    ---
+    ```
+- If you want to configure complete information for multiple authors, you can create a separate configuration file `.authors.yml` in the `docs/` or `docs/blog/` directory, see the [.authors.yml](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/.authors.yml) for its format
+- If the URL avatar fails to load, it falls back to the character avatar
 
 ## Customization
 
@@ -136,16 +168,7 @@ The plugin supports deep customization, such as **icon style, theme color, font,
       - assets/document_dates/core/timeago-load.js
     ```
 
-**Demo Images**:
-
-![01-default-w](mkdocs_document_dates/demo_images/01-default-w.png)
-![02-change-icon](mkdocs_document_dates/demo_images/02-change-icon.png)
-![02-change-icon-color](mkdocs_document_dates/demo_images/02-change-icon-color.png)
-![04-default-pop-up](mkdocs_document_dates/demo_images/04-default-pop-up.png)
-![05-change-theme](mkdocs_document_dates/demo_images/05-change-theme.png)
-
-![06-change-theme](mkdocs_document_dates/demo_images/06-change-theme.png)
-![08-pop-up-from-bottom](mkdocs_document_dates/demo_images/08-pop-up-from-bottom.png)
+![customization](customization.gif)
 
 ## Template Variables
 
@@ -154,24 +177,13 @@ You can access the meta-info of a document in a template using the following var
 - page.meta.document_dates_created
 - page.meta.document_dates_modified
 - page.meta.document_dates_authors
+- page.meta.document_dates_locale
+- page.meta.document_dates_translation
 
-For example like this:
-
-```jinja2
-<div><span>{{ page.meta.document_dates_created }}</span></div>
-<div><span>{{ page.meta.document_dates_modified }}</span></div>
-{% set authors = page.meta.document_dates_authors %}
-{% if authors %}
-<div>
-    {% for author in authors %}
-    {% if author.email %}<a href="mailto:{{ author.email }}">{{ author.name }}</a>
-    {% else %}<span>{{ author.name }}</span>{% endif %}
-    {% endfor %}
-</div>
-{% endif %}
-```
+Usage examples:
 
-**Full example**: set the correct lastmod for [sitemap.xml](https://github.com/jaywhj/mkdocs-document-dates/blob/main/sitemap.xml) so that search engines can better handle SEO and thus increase your site's exposure (override path: `docs/overrides/sitemap.xml`)
+- **Example 1**: Set the correct `lastmod` for your site's `sitemap.xml` so that search engines can better handle SEO and thus increase your site's exposure (download [sitemap.xml](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/sitemap.xml) and override this path: `docs/overrides/sitemap.xml`)
+- **Example 2**: Using the template to re-customize the plugin, you have full control over the rendering logic and the plugin is only responsible for providing the data (download [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`)
 
 ## Other Tips
 
@@ -201,6 +213,8 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
         - Solution: I considered using a shell script, but since I'd have to call back to python eventually, it's easier to use a python script. We can detect the user's python environment when the hook is installed, and then dynamically set the hook's shebang line to set the correct python interpreter
     4. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
         - Workaround: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
+    5. How to reduce build time when there are a lot of documents ( >1000 )?  Getting git information about a document is usually a file I/O operation, and if there are a lot of files, the efficiency of the operation will plummet. 1,000 documents can be expected to take more than 30 seconds, which is intolerable to the user
+        - Solution: Reduce the number of I/Os + Use caching + Replace less efficient system functions
 - **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 and personalization**
         - **Ease of use**: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc

{mkdocs_document_dates-3.2.1 → mkdocs_document_dates-3.3}/README.md

@@ -4,7 +4,7 @@ English | [简体中文](README_zh.md)
 
 
 
-A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc.
+A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc
 
 ## Features
 
@@ -14,10 +14,16 @@ A new generation MkDocs plugin for displaying exact meta-info of documents, such
 - Flexible display position (top or bottom)
 - Elegant styling (fully customizable)
 - Supports Tooltip Hover Tips
-  - Intelligent repositioning to always float optimally in view
+  - Intelligent dynamic positioning, always floating optimally in view
   - Supports automatic theme switching following Material's light/dark color scheme
 - Multi-language support, cross-platform support (Windows, macOS, Linux)
-- Ultimate build efficiency O(1), typically less than 0.2 seconds, regardless of whether the number of documents is 1,000 or 10,000
+- **Ultimate build efficiency**: O(1), typically less than 0.2 seconds
+
+| PK of Build Efficiency:     | 100 md: | 1000 md: | Time Complexity: |
+| --------------------------- | :-----: | :------: | :----------: |
+| git-revision-date-localized |  > 3 s   |  > 30 s   |    O(n)    |
+| document-dates              | < 0.1 s  | < 0.15 s  |    O(1)    |
+
 
 ## Showcases
 
@@ -43,52 +49,78 @@ Or, personalize the configuration:
 ```yaml
 plugins:
   - document-dates:
-      position: top            # Display position: top (after title)  bottom (end of document), default: bottom
+      position: top            # Display position: top (after title)  bottom (end of document)
       type: date               # Date type: date  datetime  timeago, default: date
+      exclude:                 # List of excluded files
+        - temp.md              # Exclude specific file
+        - drafts/*             # Exclude all files in drafts folder, including subfolders
       locale: en               # Localization: en zh zh_TW es fr de ar ja ko ru, default: en
       date_format: '%Y-%m-%d'  # Date format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
       time_format: '%H:%M:%S'  # Time format strings (valid only if type=datetime)
-      exclude:                 # List of excluded files
-        - temp.md              # Exclude specific file
-        - private/*            # Exclude all files in private folder, including subfolders
       show_author: true        # Show author or not, default: true
 ```
 
 ## Specify time manually
 
-The plugin will automatically get the exact time of the document, will automatically cache the creation time, but of course, you can also specify it manually in `Front Matter`
-
-Priority order: `Front Matter` > `File System Timestamps(Cached)` > `Git Timestamps`
-
-```yaml
----
-created: 2023-01-01
-modified: 2025-02-23
----
-
-# Document Title
-```
+By default, the plugin will **automatically** get the exact time of the document, and will automatically cache the creation time, without manual intervention
 
+- **Priority**: `Front Matter` > `File System Timestamps(Cached)` > `Git Timestamps`
+- If you want to customize it, you can specify it manually in Front Matter:
+    ```markdown
+    ---
+    created: 2023-01-01
+    modified: 2025-02-23
+    ---
+    
+    ```
 - `created` can be replaced with: `created, date, creation`
 - `modified` can be replaced with: `modified, updated, last_modified, last_updated`
 
-## Specify author manually
-
-The plugin will automatically get the author of the document, will parse the email and make a link, also you can specify it manually in `Front Matter`
+## Configure Author
 
-Priority order: `Front Matter` > `Git Author` > `site_author(mkdocs.yml)` > `PC Username`
+By default, the plugin will **automatically** get the author of the document, and will automatically parse the email and then do the link, without manual intervention
 
-```yaml
----
-author: any-name
-email: e-name@gmail.com
----
-
-# Document Title
-```
+- **Priority**: `Front Matter` > `Git Author` > `site_author(mkdocs.yml)` > `PC Username`
+- If you want to customize it, you can configure an author in Front Matter with the field `name`:
+    ```markdown
+    ---
+    name: any-name
+    email: e-name@gmail.com
+    ---
+    
+    ```
 
-- `author` can be replaced with: `author, name`
-- `email` can be replaced with: `email, mail`
+## Configure Avatar
+
+By default, the plugin will **automatically** loads the author avatar, without manual intervention
+
+**Priority**: `Custom Avatar` > `GitHub Avatar` > `Character Avatar`
+
+1. Character avatar: will be automatically generated based on the author's name with the following rules
+    - Extract initials: English takes the combination of initials, other languages take the first character
+    - Dynamic background color: Generate HSL color based on the hash of the name
+2. GitHub avatar: will be automatically loaded by parsing the `repo_url` property in mkdocs.yml
+3. Custom avatar: can be customized by customizing the author's `avatar` field in Front Matter
+    ```markdown
+    ---
+    # Way 1: Configure a full author
+    author:
+        name: jay
+        email: jay@qq.com
+        avatar: https://xxx.author-avatar-URL.com/xxx.png
+        url: https://xxx.website-URL.com/xxx
+        description: author description
+    
+    # Way 2: Configure multiple authors
+    authors:
+        - jaywhj
+        - squidfunk
+        - sunny
+    
+    ---
+    ```
+- If you want to configure complete information for multiple authors, you can create a separate configuration file `.authors.yml` in the `docs/` or `docs/blog/` directory, see the [.authors.yml](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/.authors.yml) for its format
+- If the URL avatar fails to load, it falls back to the character avatar
 
 ## Customization
 
@@ -110,16 +142,7 @@ The plugin supports deep customization, such as **icon style, theme color, font,
       - assets/document_dates/core/timeago-load.js
     ```
 
-**Demo Images**:
-
-![01-default-w](mkdocs_document_dates/demo_images/01-default-w.png)
-![02-change-icon](mkdocs_document_dates/demo_images/02-change-icon.png)
-![02-change-icon-color](mkdocs_document_dates/demo_images/02-change-icon-color.png)
-![04-default-pop-up](mkdocs_document_dates/demo_images/04-default-pop-up.png)
-![05-change-theme](mkdocs_document_dates/demo_images/05-change-theme.png)
-
-![06-change-theme](mkdocs_document_dates/demo_images/06-change-theme.png)
-![08-pop-up-from-bottom](mkdocs_document_dates/demo_images/08-pop-up-from-bottom.png)
+![customization](customization.gif)
 
 ## Template Variables
 
@@ -128,24 +151,13 @@ You can access the meta-info of a document in a template using the following var
 - page.meta.document_dates_created
 - page.meta.document_dates_modified
 - page.meta.document_dates_authors
+- page.meta.document_dates_locale
+- page.meta.document_dates_translation
 
-For example like this:
-
-```jinja2
-<div><span>{{ page.meta.document_dates_created }}</span></div>
-<div><span>{{ page.meta.document_dates_modified }}</span></div>
-{% set authors = page.meta.document_dates_authors %}
-{% if authors %}
-<div>
-    {% for author in authors %}
-    {% if author.email %}<a href="mailto:{{ author.email }}">{{ author.name }}</a>
-    {% else %}<span>{{ author.name }}</span>{% endif %}
-    {% endfor %}
-</div>
-{% endif %}
-```
+Usage examples:
 
-**Full example**: set the correct lastmod for [sitemap.xml](https://github.com/jaywhj/mkdocs-document-dates/blob/main/sitemap.xml) so that search engines can better handle SEO and thus increase your site's exposure (override path: `docs/overrides/sitemap.xml`)
+- **Example 1**: Set the correct `lastmod` for your site's `sitemap.xml` so that search engines can better handle SEO and thus increase your site's exposure (download [sitemap.xml](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/sitemap.xml) and override this path: `docs/overrides/sitemap.xml`)
+- **Example 2**: Using the template to re-customize the plugin, you have full control over the rendering logic and the plugin is only responsible for providing the data (download [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`)
 
 ## Other Tips
 
@@ -175,6 +187,8 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
         - Solution: I considered using a shell script, but since I'd have to call back to python eventually, it's easier to use a python script. We can detect the user's python environment when the hook is installed, and then dynamically set the hook's shebang line to set the correct python interpreter
     4. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
         - Workaround: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
+    5. How to reduce build time when there are a lot of documents ( >1000 )?  Getting git information about a document is usually a file I/O operation, and if there are a lot of files, the efficiency of the operation will plummet. 1,000 documents can be expected to take more than 30 seconds, which is intolerable to the user
+        - Solution: Reduce the number of I/Os + Use caching + Replace less efficient system functions
 - **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 and personalization**
         - **Ease of use**: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc

{mkdocs_document_dates-3.2.1 → mkdocs_document_dates-3.3}/mkdocs_document_dates/plugin.py

@@ -1,5 +1,6 @@
 import os
 import json
+import yaml
 import shutil
 import logging
 from datetime import datetime
@@ -7,6 +8,7 @@ from pathlib import Path
 from mkdocs.plugins import BasePlugin
 from mkdocs.config import config_options
 from mkdocs.structure.pages import Page
+from urllib.parse import urlparse
 from .utils import get_file_creation_time, load_git_cache, read_jsonl_cache
 
 logger = logging.getLogger("mkdocs.plugins.document_dates")
@@ -14,20 +16,20 @@ logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
 
 
 class Author:
-    def __init__(self, name="", email="", **kwargs):
+    def __init__(self, name="", email="", avatar="", url="", desc=""):
         self.name = name
         self.email = email
-        # 扩展属性
-        self.attributes = kwargs
-    
-    def __getattr__(self, name):
-        return self.attributes.get(name)
+        self.avatar = avatar
+        self.url = url
+        self.desc = desc
     
     def to_dict(self):
         return {
             'name': self.name,
             'email': self.email,
-            **self.attributes
+            'avatar': self.avatar,
+            'url': self.url,
+            'description': self.desc
         }
 
 
@@ -37,21 +39,19 @@ class DocumentDatesPlugin(BasePlugin):
         ('locale', config_options.Type(str, default=None)),
         ('date_format', config_options.Type(str, default='%Y-%m-%d')),
         ('time_format', config_options.Type(str, default='%H:%M:%S')),
-        ('position', config_options.Type(str, default='bottom')),
+        ('position', config_options.Type(str, default='top')),
         ('exclude', config_options.Type(list, default=[])),
         ('created_field_names', config_options.Type(list, default=['created', 'date', 'creation'])),
         ('modified_field_names', config_options.Type(list, default=['modified', 'updated', 'last_modified', 'last_updated'])),
-        ('show_author', config_options.Type(bool, default=True)),
-        ('author_field_mapping', config_options.Type(dict, default={
-            'name': ['name', 'author'],
-            'email': ['email', 'mail']
-        }))
+        ('show_author', config_options.Type(bool, default=True))
     )
 
     def __init__(self):
         super().__init__()
         self.translation = {}
         self.dates_cache = {}
+        self.authors_yml = {}
+        self.github_username = None
 
     def on_config(self, config):
         try:
@@ -63,6 +63,17 @@ class DocumentDatesPlugin(BasePlugin):
 
         docs_dir_path = Path(config['docs_dir'])
 
+        # 加载 author 配置
+        if self.config['show_author']:
+            self._extract_github_username(config.get('repo_url'))
+            try:
+                blog_config = config['plugins']['material/blog'].config
+                authors_file_resolved = blog_config.authors_file.format(blog=blog_config.blog_dir)
+                authors_file = docs_dir_path / authors_file_resolved
+            except Exception:
+                authors_file = docs_dir_path / '.authors.yml'
+            self._load_authors_from_yaml(authors_file)
+
         # 加载 json 语言文件
         self._load_translation(docs_dir_path)
 
@@ -149,6 +160,9 @@ class DocumentDatesPlugin(BasePlugin):
             'assets/document_dates/user.config.js'
         ])
 
+        if self.config['locale'] == 'zh':
+            self.config['locale'] = 'zh_CN'
+        
         return config
 
     def on_page_markdown(self, markdown, page: Page, config, files):
@@ -175,6 +189,8 @@ class DocumentDatesPlugin(BasePlugin):
         page.meta['document_dates_created'] = created.isoformat()
         page.meta['document_dates_modified'] = modified.isoformat()
         page.meta['document_dates_authors'] = authors
+        page.meta['document_dates_locale'] = self.config['locale']
+        page.meta['document_dates_translation'] = self.translation
         
         # 检查是否需要排除
         if self._is_excluded(rel_path):
@@ -187,6 +203,35 @@ class DocumentDatesPlugin(BasePlugin):
         return self._insert_date_info(markdown, info_html)
 
 
+    def _extract_github_username(self, url):
+        try:
+            parsed = urlparse(url)
+            if parsed.netloc != 'github.com':
+                return
+            path_parts = [p for p in parsed.path.split('/') if p]
+            if path_parts:
+                self.github_username = path_parts[0]
+        except Exception as e:
+            logger.info(f"Error parsing URL: {e}")
+
+    def _load_authors_from_yaml(self, file_path: Path):
+        if not file_path.exists():
+            return
+        try:
+            with open(file_path, 'r', encoding='utf-8') as f:
+                data = yaml.safe_load(f)
+            for key, info in (data or {}).get('authors', {}).items():
+                author = Author(
+                    name=info.get('name', ''),
+                    email=info.get('email', ''),
+                    avatar=info.get('avatar', ''),
+                    url=info.get('url', ''),
+                    desc=info.get('description', '')
+                )
+                self.authors_yml[key] = author
+        except Exception as e:
+            logger.info(f"Error parsing .authors.yml: {e}")
+
     def _load_translation(self, docs_dir_path: Path):
         # 内置语言文件目录
         builtin_dir = Path(__file__).parent / 'static' / 'languages'
@@ -271,34 +316,34 @@ class DocumentDatesPlugin(BasePlugin):
 
     def _process_meta_author(self, meta):
         try:
-            # 1. 处理 author 对象，或 author 字符串
+            # 匹配 authors 数组
+            author_objs = []
+            authors_data = meta.get('authors')
+            for key in authors_data or []:
+                author = self.authors_yml.get(key)
+                if not author:
+                    author = Author(name=str(key))
+                author_objs.append(author)
+            if author_objs:
+                return author_objs
+
+            # 匹配 author 对象，或 author 字符串
             author_data = meta.get('author')
             if author_data:
                 if isinstance(author_data, dict):
-                    name = str(author_data.get('name', ''))
+                    name = author_data.get('name')
                     if not name:
                         return None
-                    email = str(author_data.get('email', ''))
-                    # 提取扩展属性
-                    extra_attrs = {k: str(v) for k, v in author_data.items() 
-                                if k not in ['name', 'email']}
-                    return [Author(name=name, email=email, **extra_attrs)]
+                    email = author_data.get('email')
+                    avatar = author_data.get('avatar')
+                    url = author_data.get('url')
+                    desc = author_data.get('description')
+                    return [Author(name=name, email=email, avatar=avatar, url=url, desc=desc)]
                 return [Author(name=str(author_data))]
-            
-            # 2. 处理独立字段，匹配 author_field_mapping 配置
-            name = ''
-            email = ''
-            
-            for name_field in self.config['author_field_mapping']['name']:
-                if name_field in meta:
-                    name = str(meta[name_field])
-                    break
-            
-            for email_field in self.config['author_field_mapping']['email']:
-                if email_field in meta:
-                    email = str(meta[email_field])
-                    break
-            
+
+            # 匹配独立字段: name, email
+            name = meta.get('name')
+            email = meta.get('email')
             if name or email:
                 if not name and email:
                     name = email.partition('@')[0]
@@ -316,60 +361,62 @@ class DocumentDatesPlugin(BasePlugin):
         return date.strftime(self.config['date_format'])
 
     def _generate_html_info(self, created: datetime, modified: datetime, authors=None):
-        html = ""
         try:
-            locale = 'zh_CN' if self.config['locale'] == 'zh' else self.config['locale']
-            position_class = 'document-dates-top' if self.config['position'] == 'top' else 'document-dates-bottom'
-            
             # 构建基本的日期信息 HTML
-            html += (
-                f"<div class='document-dates-plugin-wrapper {position_class}'>"
-                f"<div class='document-dates-plugin'>"
-                f"<span data-tippy-content='{self.translation.get('created_time', 'Created')}: {created.strftime(self.config['date_format'])}'>"
-                f"<span class='material-icons' data-icon='doc_created'></span>"
-                f"<time datetime='{created.isoformat()}' locale='{locale}'>{self._get_formatted_date(created)}</time></span>"
-                f"<span data-tippy-content='{self.translation.get('modified_time', 'Last Update')}: {modified.strftime(self.config['date_format'])}'>"
-                f"<span class='material-icons' data-icon='doc_modified'></span>"
-                f"<time datetime='{modified.isoformat()}' locale='{locale}'>{self._get_formatted_date(modified)}</time></span>"
-            )
-            
+            html_parts = []
+            position_class = 'document-dates-top' if self.config['position'] == 'top' else 'document-dates-bottom'
+            html_parts.append(f"<div class='document-dates-plugin-wrapper {position_class}'>")
+            html_parts.append(f"<div class='document-dates-plugin'>")
+
+            def build_time_icon(time_obj: datetime, icon: str, label_key: str, default_label:str):
+                formatted = time_obj.strftime(self.config['date_format'])
+                tooltip = f"{self.translation.get(label_key, default_label)}: {formatted}"
+                return (
+                    f"<span data-tippy-content='{tooltip}'>"
+                    f"<span class='material-icons' data-icon='{icon}'></span>"
+                    f"<time datetime='{time_obj.isoformat()}' locale='{self.config['locale']}'>"
+                    f"{self._get_formatted_date(time_obj)}</time></span>"
+                )
+
+            html_parts.append(build_time_icon(created, 'doc_created', 'created_time', 'Created'))
+            html_parts.append(build_time_icon(modified, 'doc_modified', 'modified_time', 'Last Update'))
+
             # 添加作者信息
             if self.config['show_author'] and authors:
-                if len(authors) == 1:
-                    author, = authors
-                    if author.email:
-                        # 使用 HTML 实体编码避免 Tippy.js 转义问题
-                        author_tooltip = f'&lt;a href="mailto:{author.email}"&gt;{author.name}&lt;/a&gt;'
+                def get_author_tooltip(author):
+                    if author.url:
+                        return f'&lt;a href="{author.url}" target="_blank"&gt;{author.name}&lt;/a&gt;'
+                    elif author.email:
+                        return f'&lt;a href="mailto:{author.email}"&gt;{author.name}&lt;/a&gt;'
                     else:
-                        author_tooltip = author.name
-                    html += (
-                        f"<span data-tippy-content='{self.translation.get('author', 'Author')}: {author_tooltip}'>"
-                        f"<span class='material-icons' data-icon='doc_author'></span>"
-                        f"{author.name}</span>"
-                        # f"{author_tooltip}</span>"
-                    )
-                else:
-                    # 多个作者的情况
-                    authors_info = ', '.join(a.name for a in authors if a.name)
-                    authors_tooltip_parts = []
-                    for a in authors:
-                        if a.email:
-                            authors_tooltip_parts.append(f'&lt;a href="mailto:{a.email}"&gt;{a.name}&lt;/a&gt;')
-                        else:
-                            authors_tooltip_parts.append(a.name)
-                    authors_tooltip = ',&nbsp;'.join(authors_tooltip_parts)
-                    html += (
-                        f"<span data-tippy-content='{self.translation.get('authors', 'Authors')}: {authors_tooltip}'>"
-                        f"<span class='material-icons' data-icon='doc_authors'></span>"
-                        f"{authors_info}</span>"
-                        # f"{authors_tooltip}</span>"
+                        return author.name
+
+                def get_avatar_img(author):
+                    if author.avatar:
+                        return f"<img class='avatar' src='{author.avatar}' />"
+                    elif self.github_username and len(authors) == 1:
+                        return f"<img class='avatar' src='https://avatars.githubusercontent.com/{self.github_username}' />"
+                    return ""
+
+                icon = 'doc_author' if len(authors) == 1 else 'doc_authors'
+                html_parts.append(f"<span class='material-icons' data-icon='{icon}'></span>")
+                html_parts.append("<div class='avatar-group'>")
+                for author in authors:
+                    tooltip = get_author_tooltip(author)
+                    img_ele = get_avatar_img(author)
+                    html_parts.append(
+                        f"<div class='avatar-wrapper' data-name='{author.name}' data-tippy-content='{self.translation.get('author', 'Author')}: {tooltip}'>"
+                        f"{img_ele}<span class='avatar-text'></span>"
+                        f"</div>"
                     )
-            
-            html += f"</div></div>"
-        
+                html_parts.append("</div>")
+
+            html_parts.append("</div></div>")
+            return ''.join(html_parts)
+
         except Exception as e:
             logger.warning(f"Error generating HTML info: {e}")
-        return html
+            return ""
 
 
     def _insert_date_info(self, markdown: str, date_info: str):

{mkdocs_document_dates-3.2.1 → mkdocs_document_dates-3.3}/mkdocs_document_dates/static/config/user.config.css

@@ -34,15 +34,22 @@
 
 
 /* 2. Plug-in wrapper styles
-    including divider line, margin, padding, etc
-    for example, remove the divider line like below:
+    including divider line, margin, padding, and the hiding of this plugin, etc
     */
+/* Remove the divider line: */
 /* 
-.md-main .document-dates-plugin-wrapper.document-dates-top,
-.md-main .document-dates-plugin-wrapper.document-dates-bottom {
+.document-dates-plugin-wrapper.document-dates-top,
+.document-dates-plugin-wrapper.document-dates-bottom {
     border-bottom: none;
 } */
 
+/* Hide this plugin (default build version):
+    and then you can reformulate the plugin's arbitrary display position and style based on template variables */
+/* 
+.document-dates-plugin-wrapper {
+    display: none;
+} */
+
 
 
 /* 3. Tooltip styles
@@ -66,3 +73,17 @@
 .tippy-box[data-theme~='sublime'] > .tippy-arrow::before {
     color: #474747;
 } */
+
+
+
+/* 4. Author Avatar styles
+    e.g. shape, hover scale, grayscale mode
+    */
+/* 
+.avatar-wrapper {
+    border-radius: 4px;
+    filter: grayscale(0%);
+}
+.avatar-wrapper:hover {
+    transform: scale(1.08);
+} */

{mkdocs_document_dates-3.2.1 → mkdocs_document_dates-3.3}/mkdocs_document_dates/static/config/user.config.js

@@ -18,7 +18,7 @@ DocumentDates.setConfig({
     },
     tooltip: {
         placement: 'bottom',    // placement: top bottom left right auto
-        offset: [0, 6],         // placement offset: [horizontal, vertical]
+        offset: [0, 10],         // placement offset: [horizontal, vertical]
         interactive: true,      // content in Tooltip is interactive
         allowHTML: true,        // whether to allow HTML in the tooltip content
         

{mkdocs_document_dates-3.2.1 → mkdocs_document_dates-3.3}/mkdocs_document_dates/static/core/core.css

@@ -5,22 +5,22 @@
 .document-dates-plugin {
     color: #666;
     font-size: 0.9rem;
-    padding: 0.2rem 0;
     display: flex;
     align-items: center;
-    margin-bottom: 0.3rem;
+    padding: 0.2rem 0;
+    margin-bottom: 0.6rem;
 }
 .md-main .document-dates-plugin {
     color: rgba(142, 142, 142, 0.7);
     font-size: 0.75rem;
 }
-.document-dates-plugin span:not(:first-child) {
-    margin-left: 1.5rem;
-}
-.document-dates-plugin span {
+.document-dates-plugin > span {
     display: inline-flex;
     align-items: center;
 }
+.document-dates-plugin > span:not(:first-child) {
+    margin-left: 1.5rem;
+}
 .document-dates-plugin .material-icons {
     font-size: 1rem;
     opacity: 0.85;
@@ -59,7 +59,6 @@
 .document-dates-plugin-wrapper.document-dates-top,
 .document-dates-plugin-wrapper.document-dates-bottom {
     margin: 1rem 0;
-    padding-bottom: 0.3rem;
     border-bottom: 1px solid rgba(142, 142, 142, 0.15);
 }
 .md-main .document-dates-plugin-wrapper.document-dates-top {
@@ -104,3 +103,52 @@ Recommended Colors:
     -ms-transform: scale(0.75);
     transform: scale(0.75);
 }
+
+
+
+/* 4. Author Avatar styles */
+.avatar-group {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    margin: -0.15rem;
+    padding-left: 0.15rem;
+}
+.avatar-wrapper {
+    margin: 0.15rem;
+    position: relative;
+    width: 30px;
+    height: 30px;
+    border-radius: 50%;
+    overflow: hidden;
+    flex-shrink: 0;
+    opacity: 0.7;
+    filter: grayscale(90%);
+    transition: transform 0.2s ease, filter 0.2s ease;
+}
+.avatar-wrapper:hover {
+    transform: scale(1.08);
+    filter: grayscale(0%);
+    cursor: pointer;
+}
+.avatar-wrapper img.avatar {
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    z-index: 2;
+}
+.avatar-wrapper .avatar-text {
+    position: absolute;
+    width: 100%;
+    height: 100%;
+    color: #fff;
+    font-size: 13px;
+    font-weight: bold;
+    font-family: sans-serif;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    text-transform: capitalize;
+    z-index: 1;
+}

{mkdocs_document_dates-3.2.1 → mkdocs_document_dates-3.3}/mkdocs_document_dates/static/core/core.js

@@ -6,7 +6,7 @@ const defaultConfig = {
     },
     tooltip: {
         placement: 'bottom',    // placement: top bottom left right auto
-        offset: [0, 10],        // placement offset: [horizontal, vertical]
+        offset: [0, 12],        // placement offset: [horizontal, vertical]
         interactive: true,      // content in Tooltip is interactive
         allowHTML: true,        // whether to allow HTML in the tooltip content
         
@@ -160,3 +160,51 @@ window.DocumentDates = {
     registerHook,
     setConfig
 };
+
+
+
+/* Automatically generate avatars based on text */
+
+function isLatin(name) {
+    return /^[A-Za-z\s]+$/.test(name.trim());
+}
+function extractInitials(name) {
+    name = name.trim();
+    if (!name) return '?';
+    if (isLatin(name)) {
+        const parts = name.toUpperCase().split(/\s+/).filter(Boolean);
+        return parts.length >= 2 ? parts[0][0] + parts[parts.length - 1][0] : parts[0][0];
+    } else {
+        return name[0];
+    }
+}
+function nameToHSL(name, s = 50, l = 55) {
+    let hash = 0;
+    for (let i = 0; i < name.length; i++) {
+        hash = name.charCodeAt(i) + ((hash << 5) - hash);
+    }
+    const hue = hash % 360;
+    return `hsl(${hue}, ${s}%, ${l}%)`;
+}
+function generateAvatar(){
+    document.querySelectorAll('.avatar-wrapper').forEach(wrapper => {
+        const name = wrapper.dataset.name || '';
+        const initials = extractInitials(name);
+        const bgColor = nameToHSL(name);
+
+        const textEl = wrapper.querySelector('.avatar-text');
+        textEl.textContent = initials;
+        textEl.style.backgroundColor = bgColor;
+
+        const imgEl = wrapper.querySelector('img.avatar');
+        if (!imgEl) return;
+        imgEl.onerror = () => {
+            imgEl.style.display = 'none';
+        };
+    });
+}
+if (typeof window.document$ !== 'undefined' && !window.document$.isStopped) {
+    window.document$.subscribe(generateAvatar);
+} else {
+    generateAvatar();
+}

{mkdocs_document_dates-3.2.1 → mkdocs_document_dates-3.3/mkdocs_document_dates.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.2.1
-Summary: A new generation MkDocs plugin for displaying exact meta-info of documents, such as creation time, last update time, authors, email, etc.
+Version: 3.3
+Summary: A new generation MkDocs plugin for displaying exact meta-info, such as creation time, last update time, authors, email, etc
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
 Author-email: aaronwqt@gmail.com
@@ -30,7 +30,7 @@ English | [简体中文](README_zh.md)
 
 
 
-A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc.
+A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc
 
 ## Features
 
@@ -40,10 +40,16 @@ A new generation MkDocs plugin for displaying exact meta-info of documents, such
 - Flexible display position (top or bottom)
 - Elegant styling (fully customizable)
 - Supports Tooltip Hover Tips
-  - Intelligent repositioning to always float optimally in view
+  - Intelligent dynamic positioning, always floating optimally in view
   - Supports automatic theme switching following Material's light/dark color scheme
 - Multi-language support, cross-platform support (Windows, macOS, Linux)
-- Ultimate build efficiency O(1), typically less than 0.2 seconds, regardless of whether the number of documents is 1,000 or 10,000
+- **Ultimate build efficiency**: O(1), typically less than 0.2 seconds
+
+| PK of Build Efficiency:     | 100 md: | 1000 md: | Time Complexity: |
+| --------------------------- | :-----: | :------: | :----------: |
+| git-revision-date-localized |  > 3 s   |  > 30 s   |    O(n)    |
+| document-dates              | < 0.1 s  | < 0.15 s  |    O(1)    |
+
 
 ## Showcases
 
@@ -69,52 +75,78 @@ Or, personalize the configuration:
 ```yaml
 plugins:
   - document-dates:
-      position: top            # Display position: top (after title)  bottom (end of document), default: bottom
+      position: top            # Display position: top (after title)  bottom (end of document)
       type: date               # Date type: date  datetime  timeago, default: date
+      exclude:                 # List of excluded files
+        - temp.md              # Exclude specific file
+        - drafts/*             # Exclude all files in drafts folder, including subfolders
       locale: en               # Localization: en zh zh_TW es fr de ar ja ko ru, default: en
       date_format: '%Y-%m-%d'  # Date format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
       time_format: '%H:%M:%S'  # Time format strings (valid only if type=datetime)
-      exclude:                 # List of excluded files
-        - temp.md              # Exclude specific file
-        - private/*            # Exclude all files in private folder, including subfolders
       show_author: true        # Show author or not, default: true
 ```
 
 ## Specify time manually
 
-The plugin will automatically get the exact time of the document, will automatically cache the creation time, but of course, you can also specify it manually in `Front Matter`
-
-Priority order: `Front Matter` > `File System Timestamps(Cached)` > `Git Timestamps`
-
-```yaml
----
-created: 2023-01-01
-modified: 2025-02-23
----
-
-# Document Title
-```
+By default, the plugin will **automatically** get the exact time of the document, and will automatically cache the creation time, without manual intervention
 
+- **Priority**: `Front Matter` > `File System Timestamps(Cached)` > `Git Timestamps`
+- If you want to customize it, you can specify it manually in Front Matter:
+    ```markdown
+    ---
+    created: 2023-01-01
+    modified: 2025-02-23
+    ---
+    
+    ```
 - `created` can be replaced with: `created, date, creation`
 - `modified` can be replaced with: `modified, updated, last_modified, last_updated`
 
-## Specify author manually
-
-The plugin will automatically get the author of the document, will parse the email and make a link, also you can specify it manually in `Front Matter`
+## Configure Author
 
-Priority order: `Front Matter` > `Git Author` > `site_author(mkdocs.yml)` > `PC Username`
+By default, the plugin will **automatically** get the author of the document, and will automatically parse the email and then do the link, without manual intervention
 
-```yaml
----
-author: any-name
-email: e-name@gmail.com
----
-
-# Document Title
-```
+- **Priority**: `Front Matter` > `Git Author` > `site_author(mkdocs.yml)` > `PC Username`
+- If you want to customize it, you can configure an author in Front Matter with the field `name`:
+    ```markdown
+    ---
+    name: any-name
+    email: e-name@gmail.com
+    ---
+    
+    ```
 
-- `author` can be replaced with: `author, name`
-- `email` can be replaced with: `email, mail`
+## Configure Avatar
+
+By default, the plugin will **automatically** loads the author avatar, without manual intervention
+
+**Priority**: `Custom Avatar` > `GitHub Avatar` > `Character Avatar`
+
+1. Character avatar: will be automatically generated based on the author's name with the following rules
+    - Extract initials: English takes the combination of initials, other languages take the first character
+    - Dynamic background color: Generate HSL color based on the hash of the name
+2. GitHub avatar: will be automatically loaded by parsing the `repo_url` property in mkdocs.yml
+3. Custom avatar: can be customized by customizing the author's `avatar` field in Front Matter
+    ```markdown
+    ---
+    # Way 1: Configure a full author
+    author:
+        name: jay
+        email: jay@qq.com
+        avatar: https://xxx.author-avatar-URL.com/xxx.png
+        url: https://xxx.website-URL.com/xxx
+        description: author description
+    
+    # Way 2: Configure multiple authors
+    authors:
+        - jaywhj
+        - squidfunk
+        - sunny
+    
+    ---
+    ```
+- If you want to configure complete information for multiple authors, you can create a separate configuration file `.authors.yml` in the `docs/` or `docs/blog/` directory, see the [.authors.yml](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/.authors.yml) for its format
+- If the URL avatar fails to load, it falls back to the character avatar
 
 ## Customization
 
@@ -136,16 +168,7 @@ The plugin supports deep customization, such as **icon style, theme color, font,
       - assets/document_dates/core/timeago-load.js
     ```
 
-**Demo Images**:
-
-![01-default-w](mkdocs_document_dates/demo_images/01-default-w.png)
-![02-change-icon](mkdocs_document_dates/demo_images/02-change-icon.png)
-![02-change-icon-color](mkdocs_document_dates/demo_images/02-change-icon-color.png)
-![04-default-pop-up](mkdocs_document_dates/demo_images/04-default-pop-up.png)
-![05-change-theme](mkdocs_document_dates/demo_images/05-change-theme.png)
-
-![06-change-theme](mkdocs_document_dates/demo_images/06-change-theme.png)
-![08-pop-up-from-bottom](mkdocs_document_dates/demo_images/08-pop-up-from-bottom.png)
+![customization](customization.gif)
 
 ## Template Variables
 
@@ -154,24 +177,13 @@ You can access the meta-info of a document in a template using the following var
 - page.meta.document_dates_created
 - page.meta.document_dates_modified
 - page.meta.document_dates_authors
+- page.meta.document_dates_locale
+- page.meta.document_dates_translation
 
-For example like this:
-
-```jinja2
-<div><span>{{ page.meta.document_dates_created }}</span></div>
-<div><span>{{ page.meta.document_dates_modified }}</span></div>
-{% set authors = page.meta.document_dates_authors %}
-{% if authors %}
-<div>
-    {% for author in authors %}
-    {% if author.email %}<a href="mailto:{{ author.email }}">{{ author.name }}</a>
-    {% else %}<span>{{ author.name }}</span>{% endif %}
-    {% endfor %}
-</div>
-{% endif %}
-```
+Usage examples:
 
-**Full example**: set the correct lastmod for [sitemap.xml](https://github.com/jaywhj/mkdocs-document-dates/blob/main/sitemap.xml) so that search engines can better handle SEO and thus increase your site's exposure (override path: `docs/overrides/sitemap.xml`)
+- **Example 1**: Set the correct `lastmod` for your site's `sitemap.xml` so that search engines can better handle SEO and thus increase your site's exposure (download [sitemap.xml](https://github.com/jaywhj/mkdocs-document-dates/blob/main/templates/overrides/sitemap.xml) and override this path: `docs/overrides/sitemap.xml`)
+- **Example 2**: Using the template to re-customize the plugin, you have full control over the rendering logic and the plugin is only responsible for providing the data (download [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`)
 
 ## Other Tips
 
@@ -201,6 +213,8 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
         - Solution: I considered using a shell script, but since I'd have to call back to python eventually, it's easier to use a python script. We can detect the user's python environment when the hook is installed, and then dynamically set the hook's shebang line to set the correct python interpreter
     4. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
         - Workaround: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
+    5. How to reduce build time when there are a lot of documents ( >1000 )?  Getting git information about a document is usually a file I/O operation, and if there are a lot of files, the efficiency of the operation will plummet. 1,000 documents can be expected to take more than 30 seconds, which is intolerable to the user
+        - Solution: Reduce the number of I/Os + Use caching + Replace less efficient system functions
 - **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 and personalization**
         - **Ease of use**: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc

{mkdocs_document_dates-3.2.1 → mkdocs_document_dates-3.3}/setup.py

@@ -26,9 +26,9 @@ try:
     with open("README.md", "r", encoding="utf-8") as fh:
         long_description = fh.read()
 except FileNotFoundError:
-    long_description = "A new generation MkDocs plugin for displaying exact meta-info of documents, such as creation time, last update time, authors, email, etc."
+    long_description = "A new generation MkDocs plugin for displaying exact meta-info, such as creation time, last update time, authors, email, etc"
 
-VERSION = '3.2.1'
+VERSION = '3.3'
 
 setup(
     name="mkdocs-document-dates",
@@ -36,7 +36,7 @@ setup(
     author="Aaron Wang",
     author_email="aaronwqt@gmail.com",
     license="MIT",
-    description="A new generation MkDocs plugin for displaying exact meta-info of documents, such as creation time, last update time, authors, email, etc.",
+    description="A new generation MkDocs plugin for displaying exact meta-info, such as creation time, last update time, authors, email, etc",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/jaywhj/mkdocs-document-dates",