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

{mkdocs_document_dates-3.2.1/mkdocs_document_dates.egg-info → mkdocs_document_dates-3.3.1}/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.1
+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.1}/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.1}/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
+from .utils import read_json_cache, read_jsonl_cache, write_jsonl_cache, get_file_creation_time, get_git_first_commit_time
 
 logger = logging.getLogger("mkdocs.plugins.document_dates")
 logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
@@ -94,6 +94,10 @@ def update_cache():
                         project_updated = True
                     elif full_path.exists():
                         created_time = get_file_creation_time(full_path).astimezone()
+                        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)
                         jsonl_dates_cache[rel_path] = {
                             "created": created_time.isoformat()
                         }