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

mkdocs_document_dates-3.3/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Aaron Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

{mkdocs_document_dates-3.2/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
-Summary: An easy-to-use, lightweight MkDocs plugin for displaying the exact creation time, last modification time and author info of markdown documents.
+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)
 
 
 
-An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark> creation time, last modification time and author info of markdown documents.
+A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc
 
 ## Features
 
@@ -40,9 +40,16 @@ An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark>
 - 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
+
+| 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
 
@@ -68,56 +75,82 @@ 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 directory, including subdirectories
       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` > `Cache Files` > `File System 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
 
-The plugin supports deep customization, such as **icon style, theme color, font, animation, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
+The plugin supports deep customization, such as **icon style, theme color, font, animation, dividing line**, etc. Everything is customizable (Find the file below and turn on the uncomment switch):
 
 |        Category:        | Location:                               |
 | :----------------------: | ---------------------------------------- |
@@ -135,42 +168,22 @@ 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)
+![customization](customization.gif)
 
-![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)
-
-## Used in templates
+## Template Variables
 
 You can access the meta-info of a document in a template using the following variables:
 
 - 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
 
@@ -200,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 → mkdocs_document_dates-3.3}/README.md

@@ -4,7 +4,7 @@ English | [简体中文](README_zh.md)
 
 
 
-An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark> creation time, last modification time and author info of markdown documents.
+A new generation MkDocs plugin for displaying exact meta-info of documents, such as **creation time, last update time, authors, email**, etc
 
 ## Features
 
@@ -14,9 +14,16 @@ An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark>
 - 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
+
+| 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
 
@@ -42,56 +49,82 @@ 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 directory, including subdirectories
       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` > `Cache Files` > `File System 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
 
-The plugin supports deep customization, such as **icon style, theme color, font, animation, dividing line**, etc. Everything is customizable (I've already written the code, you just need to turn on the uncomment switch):
+The plugin supports deep customization, such as **icon style, theme color, font, animation, dividing line**, etc. Everything is customizable (Find the file below and turn on the uncomment switch):
 
 |        Category:        | Location:                               |
 | :----------------------: | ---------------------------------------- |
@@ -109,42 +142,22 @@ 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)
+![customization](customization.gif)
 
-![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)
-
-## Used in templates
+## Template Variables
 
 You can access the meta-info of a document in a template using the following variables:
 
 - 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
 
@@ -174,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 → mkdocs_document_dates-3.3}/mkdocs_document_dates/cache_manager.py

@@ -1,7 +1,7 @@
 import logging
 import subprocess
 from pathlib import Path
-from .utils import read_json_cache, read_jsonl_cache, write_jsonl_cache, get_file_creation_time, get_git_first_commit_time
+from .utils import read_json_cache, read_jsonl_cache, write_jsonl_cache, get_file_creation_time
 
 logger = logging.getLogger("mkdocs.plugins.document_dates")
 logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
@@ -57,7 +57,7 @@ def update_cache():
 
             docs_dir = project_dir / 'docs'
             if not docs_dir.exists():
-                logger.error(f"Document directory does not exist: {docs_dir}")
+                logger.warning(f"Document directory does not exist: {docs_dir}")
                 continue
 
             # 设置.gitattributes文件
@@ -93,11 +93,7 @@ def update_cache():
                         jsonl_dates_cache[rel_path] = json_dates_cache[rel_path]
                         project_updated = True
                     elif full_path.exists():
-                        created_time = get_file_creation_time(full_path)
-                        if not jsonl_cache_file.exists() and not json_cache_file.exists():
-                            git_time = get_git_first_commit_time(full_path)
-                            if git_time:
-                                created_time = min(created_time, git_time)
+                        created_time = get_file_creation_time(full_path).astimezone()
                         jsonl_dates_cache[rel_path] = {
                             "created": created_time.isoformat()
                         }