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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.3
+Version: 3.3.2
 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
@@ -30,20 +30,21 @@ 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 **creation time, last update time, authors, email** of documents
 
 ## Features
 
-- Always display exact meta-info of the document for any environment (no-Git, Git, all CI/CD build systems, etc)
+- Always display **exact** meta-info of the document for any environment (no-Git, Git, all CI/CD build systems, etc)
 - Support for manually specifying time and author in `Front Matter`
 - Support for multiple time formats (date, datetime, timeago)
 - Flexible display position (top or bottom)
 - Elegant styling (fully customizable)
 - Supports Tooltip Hover Tips
-  - 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
+    - Intelligent dynamic positioning, always floating optimally in view
+    - Supports automatic theme switching following Material's light/dark color scheme
+- Multi-language support, localization support, intelligent recognition of user language, automatic adaptation
+- Cross-platform support (Windows, macOS, Linux)
+- **Ultimate build efficiency**: O(1), no need to set env vars to distinguish runs
 
 | PK of Build Efficiency:     | 100 md: | 1000 md: | Time Complexity: |
 | --------------------------- | :-----: | :------: | :----------: |
@@ -80,10 +81,8 @@ plugins:
       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)
-      show_author: true        # Show author or not, default: true
 ```
 
 ## Specify time manually
@@ -129,7 +128,7 @@ By default, the plugin will **automatically** loads the author avatar, without m
 3. Custom avatar: can be customized by customizing the author's `avatar` field in Front Matter
     ```markdown
     ---
-    # Way 1: Configure a full author
+    # Way 1: Configure a full author (fields optional)
     author:
         name: jay
         email: jay@qq.com
@@ -140,35 +139,37 @@ By default, the plugin will **automatically** loads the author avatar, without m
     # Way 2: Configure multiple authors
     authors:
         - jaywhj
-        - squidfunk
+        - dawang
         - 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
+- If you want to configure complete information for multiple authors, you can create a separate configuration file `authors.yml` in the `docs/` 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 automatically 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 (Find the file below and turn on the uncomment switch):
+The plugin supports full customization, such as **icon style, theme color, font, animation, dividing line** etc, and the entrance has been preset, you just need to find the file below and uncomment it:
 
 |        Category:        | Location:                               |
 | :----------------------: | ---------------------------------------- |
 |     **Style & Theme**     | `docs/assets/document_dates/user.config.css` |
 | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
-| **Localized languages** | `docs/assets/document_dates/languages/` <br />refer to the template file `en.json` for any additions or modifications |
 
-**Tip**: when `type: timeago` is set, timeago.js is enabled to render dynamic time, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
+![customization](customization.gif)
 
-- In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
-- In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to load all languages at once
-    ```yaml
-    extra_javascript:
-      - assets/document_dates/core/timeago.full.min.js
-      - assets/document_dates/core/timeago-load.js
-    ```
+## Localization
 
-![customization](customization.gif)
+- **tooltip**: the plugin has 10 built-in languages: `en zh zh_TW es fr de ar ja ko ru`, **no need for manual configuration**, intelligent recognition, automatic switching
+    - If the language is missing or the built-in language is inaccurate, you can refer to [Part 3](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) in `user.config.js` to register and add it yourself, or submit an issue
+    - The original configuration option `locale` is retained, but manual configuration is no longer recommended
+- **timeago**: when `type: timeago` is set, timeago.js is enabled to render dynamic time, `timeago.min.js` only contains English and Chinese by default, if need to load other languages, you can configure it as below (choose one):
+    - In `user.config.js`, refer to [Part 2](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js), register and add it yourself
+    - In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to reload all languages at once
+        ```yaml
+        extra_javascript:
+        - assets/document_dates/core/timeago.full.min.js
+        ```
 
 ## Template Variables
 
@@ -177,8 +178,6 @@ 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
 
 Usage examples:
 
@@ -206,7 +205,7 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
     - Method 2: Cache the original time in advance, and then read the cache subsequently (The time is exact and no dependency on any environment). The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is easier, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
 - **Difficulty**:
     1. When to read and store original time? This is just a plugin for mkdocs, with very limited access and permissions, mkdocs provides only build and serve, so in case a user commits directly without executing build or serve (e.g., when using a CI/CD build system), then you won't be able to retrieve the time information of the file, not to mention caching it!
-        - Let's take a straight shot: the Git Hooks mechanism was found, prompted by the AI, which can trigger a custom script when a specific git action occurs, such as every time commit is performed
+        - Straight to the bottom line: Git Hooks can be used to trigger custom scripts when specific git actions occur, such as every time a commit occurs
     2. How to install Git Hooks automatically? When and how are they triggered? Installing packages from PyPI via pip doesn't have a standard post-install hook mechanism
         - Workaround: After analyzing the flow of pip installing packages from PyPI, I found that when compiling and installing through the source package (sdist), setuptools will be called to handle it, so we can find a way to implant the installation script in the process of setuptools, i.e., we can add a custom script in setup.py
     3. How to design a cross-platform hook? To execute a python script, we need to explicitly specify the python interpreter, and the user's python environment varies depending on the operating system, the way python is installed, and the configuration, so how can we ensure that it works properly in all environments?
@@ -216,10 +215,11 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
     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
+    - 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, compatibility, personalization, intelligence**
+        - **Ease of use**: there are no complex configurations, only 2-3 commonly used configuration options, in addition, a template is provided for personalized configurations
         - **Simplicity**: no unnecessary configuration, no Git dependencies, no CI/CD configuration dependencies, no other package dependencies
-        - **Personalization**: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
-    - In addition, it has good compatibility and extensibility, and works well in WIN7, mobile devices, old Safari, etc
+        - **Compatibility**: works well on older operating systems and browsers, such as WIN7, MacOS 10.11, iOS 12, Chrome 63.0.3239
+        - **Personalization**: fully customizable and full control over the rendering logic, the plugin is only responsible for providing the data
+        - **Intelligence**: intelligently parse document time, author, avatar, intelligent recognition of user language and automatic adaptation, in addition, there are auto-install Git Hooks, auto-cache, auto-commit
 - **The Last Secret**:
     - Programming is a hobby, and I'm a marketer of 8 years (Feel free to leave a comment)

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

@@ -4,20 +4,21 @@ 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 **creation time, last update time, authors, email** of documents
 
 ## Features
 
-- Always display exact meta-info of the document for any environment (no-Git, Git, all CI/CD build systems, etc)
+- Always display **exact** meta-info of the document for any environment (no-Git, Git, all CI/CD build systems, etc)
 - Support for manually specifying time and author in `Front Matter`
 - Support for multiple time formats (date, datetime, timeago)
 - Flexible display position (top or bottom)
 - Elegant styling (fully customizable)
 - Supports Tooltip Hover Tips
-  - 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
+    - Intelligent dynamic positioning, always floating optimally in view
+    - Supports automatic theme switching following Material's light/dark color scheme
+- Multi-language support, localization support, intelligent recognition of user language, automatic adaptation
+- Cross-platform support (Windows, macOS, Linux)
+- **Ultimate build efficiency**: O(1), no need to set env vars to distinguish runs
 
 | PK of Build Efficiency:     | 100 md: | 1000 md: | Time Complexity: |
 | --------------------------- | :-----: | :------: | :----------: |
@@ -54,10 +55,8 @@ plugins:
       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)
-      show_author: true        # Show author or not, default: true
 ```
 
 ## Specify time manually
@@ -103,7 +102,7 @@ By default, the plugin will **automatically** loads the author avatar, without m
 3. Custom avatar: can be customized by customizing the author's `avatar` field in Front Matter
     ```markdown
     ---
-    # Way 1: Configure a full author
+    # Way 1: Configure a full author (fields optional)
     author:
         name: jay
         email: jay@qq.com
@@ -114,35 +113,37 @@ By default, the plugin will **automatically** loads the author avatar, without m
     # Way 2: Configure multiple authors
     authors:
         - jaywhj
-        - squidfunk
+        - dawang
         - 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
+- If you want to configure complete information for multiple authors, you can create a separate configuration file `authors.yml` in the `docs/` 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 automatically 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 (Find the file below and turn on the uncomment switch):
+The plugin supports full customization, such as **icon style, theme color, font, animation, dividing line** etc, and the entrance has been preset, you just need to find the file below and uncomment it:
 
 |        Category:        | Location:                               |
 | :----------------------: | ---------------------------------------- |
 |     **Style & Theme**     | `docs/assets/document_dates/user.config.css` |
 | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
-| **Localized languages** | `docs/assets/document_dates/languages/` <br />refer to the template file `en.json` for any additions or modifications |
 
-**Tip**: when `type: timeago` is set, timeago.js is enabled to render dynamic time, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
+![customization](customization.gif)
 
-- In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
-- In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to load all languages at once
-    ```yaml
-    extra_javascript:
-      - assets/document_dates/core/timeago.full.min.js
-      - assets/document_dates/core/timeago-load.js
-    ```
+## Localization
 
-![customization](customization.gif)
+- **tooltip**: the plugin has 10 built-in languages: `en zh zh_TW es fr de ar ja ko ru`, **no need for manual configuration**, intelligent recognition, automatic switching
+    - If the language is missing or the built-in language is inaccurate, you can refer to [Part 3](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) in `user.config.js` to register and add it yourself, or submit an issue
+    - The original configuration option `locale` is retained, but manual configuration is no longer recommended
+- **timeago**: when `type: timeago` is set, timeago.js is enabled to render dynamic time, `timeago.min.js` only contains English and Chinese by default, if need to load other languages, you can configure it as below (choose one):
+    - In `user.config.js`, refer to [Part 2](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js), register and add it yourself
+    - In `mkdocs.yml`, configure the full version of `timeago.full.min.js` to reload all languages at once
+        ```yaml
+        extra_javascript:
+        - assets/document_dates/core/timeago.full.min.js
+        ```
 
 ## Template Variables
 
@@ -151,8 +152,6 @@ 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
 
 Usage examples:
 
@@ -180,7 +179,7 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
     - Method 2: Cache the original time in advance, and then read the cache subsequently (The time is exact and no dependency on any environment). The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is easier, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
 - **Difficulty**:
     1. When to read and store original time? This is just a plugin for mkdocs, with very limited access and permissions, mkdocs provides only build and serve, so in case a user commits directly without executing build or serve (e.g., when using a CI/CD build system), then you won't be able to retrieve the time information of the file, not to mention caching it!
-        - Let's take a straight shot: the Git Hooks mechanism was found, prompted by the AI, which can trigger a custom script when a specific git action occurs, such as every time commit is performed
+        - Straight to the bottom line: Git Hooks can be used to trigger custom scripts when specific git actions occur, such as every time a commit occurs
     2. How to install Git Hooks automatically? When and how are they triggered? Installing packages from PyPI via pip doesn't have a standard post-install hook mechanism
         - Workaround: After analyzing the flow of pip installing packages from PyPI, I found that when compiling and installing through the source package (sdist), setuptools will be called to handle it, so we can find a way to implant the installation script in the process of setuptools, i.e., we can add a custom script in setup.py
     3. How to design a cross-platform hook? To execute a python script, we need to explicitly specify the python interpreter, and the user's python environment varies depending on the operating system, the way python is installed, and the configuration, so how can we ensure that it works properly in all environments?
@@ -190,10 +189,11 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
     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
+    - 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, compatibility, personalization, intelligence**
+        - **Ease of use**: there are no complex configurations, only 2-3 commonly used configuration options, in addition, a template is provided for personalized configurations
         - **Simplicity**: no unnecessary configuration, no Git dependencies, no CI/CD configuration dependencies, no other package dependencies
-        - **Personalization**: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
-    - In addition, it has good compatibility and extensibility, and works well in WIN7, mobile devices, old Safari, etc
+        - **Compatibility**: works well on older operating systems and browsers, such as WIN7, MacOS 10.11, iOS 12, Chrome 63.0.3239
+        - **Personalization**: fully customizable and full control over the rendering logic, the plugin is only responsible for providing the data
+        - **Intelligence**: intelligently parse document time, author, avatar, intelligent recognition of user language and automatic adaptation, in addition, there are auto-install Git Hooks, auto-cache, auto-commit
 - **The Last Secret**:
     - Programming is a hobby, and I'm a marketer of 8 years (Feel free to leave a comment)

{mkdocs_document_dates-3.3 → mkdocs_document_dates-3.3.2}/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()
                         }

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

@@ -1,5 +1,4 @@
 import os
-import json
 import yaml
 import shutil
 import logging
@@ -36,7 +35,7 @@ class Author:
 class DocumentDatesPlugin(BasePlugin):
     config_scheme = (
         ('type', config_options.Type(str, default='date')),
-        ('locale', config_options.Type(str, default=None)),
+        ('locale', config_options.Type(str, default='')),
         ('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='top')),
@@ -48,35 +47,26 @@ class DocumentDatesPlugin(BasePlugin):
 
     def __init__(self):
         super().__init__()
-        self.translation = {}
         self.dates_cache = {}
         self.authors_yml = {}
         self.github_username = None
 
     def on_config(self, config):
-        try:
-            # 设置 locale 在无配置时跟随主题语言
-            if not self.config['locale']:
-                self.config['locale'] = config['theme']['language']
-        except Exception:
-            self.config['locale'] = 'en'
-
         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'
+            authors_file = docs_dir_path / 'authors.yml'
+            if not authors_file.exists():
+                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:
+                    pass
             self._load_authors_from_yaml(authors_file)
 
-        # 加载 json 语言文件
-        self._load_translation(docs_dir_path)
-
         # 加载 git 缓存
         self.dates_cache = load_git_cache(docs_dir_path)
         # 加载 jsonl 缓存覆盖
@@ -106,7 +96,7 @@ class DocumentDatesPlugin(BasePlugin):
         dest_dir = docs_dir_path / 'assets' / 'document_dates'
         dest_dir.mkdir(parents=True, exist_ok=True)
         
-        for dir_name in ['tippy', 'core']:
+        for dir_name in ['tippy', 'core', 'fonts']:
             source_dir = Path(__file__).parent / 'static' / dir_name
             target_dir = dest_dir / dir_name
             # shutil.copytree(source_dir, target_dir, dirs_exist_ok=True)
@@ -123,9 +113,9 @@ class DocumentDatesPlugin(BasePlugin):
             if not target_config.exists():
                 shutil.copy2(source_config, target_config)
 
-        
-        # 加载图标 Google Fonts Icons: https://fonts.google.com/icons
-        material_icons_url = 'https://fonts.googleapis.com/icon?family=Material+Icons'
+        # 加载离线 Google Fonts Icons: https://fonts.google.com/icons
+        # material_icons_url = 'https://fonts.googleapis.com/icon?family=Material+Icons'
+        material_icons_url = 'assets/document_dates/fonts/material-icons.css'
         if material_icons_url not in config['extra_css']:
             config['extra_css'].append(material_icons_url)
         
@@ -133,10 +123,7 @@ class DocumentDatesPlugin(BasePlugin):
         # https://cdn.jsdelivr.net/npm/timeago.js@4.0.2/dist/timeago.min.js
         # https://cdnjs.cloudflare.com/ajax/libs/timeago.js/4.0.2/timeago.full.min.js
         if self.config['type'] == 'timeago':
-            config['extra_javascript'][0:0] = [
-                'assets/document_dates/core/timeago.min.js',
-                'assets/document_dates/core/timeago-load.js'
-            ]
+            config['extra_javascript'].insert(0, 'assets/document_dates/core/timeago.min.js')
 
         # 加载 Tippy CSS 文件
         tippy_css_dir = dest_dir / 'tippy'
@@ -156,13 +143,12 @@ class DocumentDatesPlugin(BasePlugin):
         
         # 加载自定义 JS 文件
         config['extra_javascript'].extend([
-            'assets/document_dates/core/core.js',
-            'assets/document_dates/user.config.js'
+            'assets/document_dates/core/default.config.js',
+            'assets/document_dates/user.config.js',
+            'assets/document_dates/core/utils.js',
+            'assets/document_dates/core/core.js'
         ])
 
-        if self.config['locale'] == 'zh':
-            self.config['locale'] = 'zh_CN'
-        
         return config
 
     def on_page_markdown(self, markdown, page: Page, config, files):
@@ -189,8 +175,6 @@ 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):
@@ -232,37 +216,6 @@ class DocumentDatesPlugin(BasePlugin):
         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'
-        # 用户自定义语言文件目录
-        custom_dir = docs_dir_path / 'assets' / 'document_dates' / 'languages'
-
-        # 加载语言文件
-        self._load_lang_file(builtin_dir)
-        self._load_lang_file(custom_dir)
-        if not self.translation:
-            self.config['locale'] = 'en'
-            self._load_lang_file(builtin_dir)
-
-        # 复制 en.json 到用户目录作为自定义参考
-        custom_en_json = custom_dir / 'en.json'
-        if not custom_en_json.exists():
-            custom_dir.mkdir(parents=True, exist_ok=True)
-            en_json = builtin_dir / 'en.json'
-            shutil.copy2(en_json, custom_en_json)
-
-    def _load_lang_file(self, lang_dir: Path):
-        try:
-            locale_file = lang_dir / f"{self.config['locale']}.json"
-            if locale_file.exists():
-                with locale_file.open('r', encoding='utf-8') as f:
-                    self.translation = json.load(f)
-        except json.JSONDecodeError as e:
-            logger.error(f"Invalid JSON format in language file {locale_file}: {str(e)}")
-        except Exception as e:
-            logger.error(f"Error loading language file {locale_file}: {str(e)}")
-
 
     def _is_excluded(self, rel_path):
         for pattern in self.config['exclude']:
@@ -366,20 +319,19 @@ class DocumentDatesPlugin(BasePlugin):
             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'>")
+            html_parts.append(f"<div class='document-dates-plugin' locale='{self.config['locale']}'>")
 
-            def build_time_icon(time_obj: datetime, icon: str, label_key: str, default_label:str):
+            def build_time_icon(time_obj: datetime, icon: 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 data-tippy-content data-tippy-raw='{formatted}'>"
                     f"<span class='material-icons' data-icon='{icon}'></span>"
-                    f"<time datetime='{time_obj.isoformat()}' locale='{self.config['locale']}'>"
+                    f"<time datetime='{time_obj.isoformat()}'>"
                     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'))
+            html_parts.append(build_time_icon(created, 'doc_created'))
+            html_parts.append(build_time_icon(modified, 'doc_modified'))
 
             # 添加作者信息
             if self.config['show_author'] and authors:
@@ -388,14 +340,13 @@ class DocumentDatesPlugin(BasePlugin):
                         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:
-                        return author.name
+                    return author.name
 
-                def get_avatar_img(author):
+                def get_avatar_img_url(author):
                     if author.avatar:
-                        return f"<img class='avatar' src='{author.avatar}' />"
+                        return author.avatar
                     elif self.github_username and len(authors) == 1:
-                        return f"<img class='avatar' src='https://avatars.githubusercontent.com/{self.github_username}' />"
+                        return f"https://avatars.githubusercontent.com/{self.github_username}"
                     return ""
 
                 icon = 'doc_author' if len(authors) == 1 else 'doc_authors'
@@ -403,10 +354,11 @@ class DocumentDatesPlugin(BasePlugin):
                 html_parts.append("<div class='avatar-group'>")
                 for author in authors:
                     tooltip = get_author_tooltip(author)
-                    img_ele = get_avatar_img(author)
+                    img_url = get_avatar_img_url(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 class='avatar-wrapper' data-name='{author.name}' data-tippy-content data-tippy-raw='{tooltip}'>"
+                        f"<span class='avatar-text'></span>"
+                        f"<img class='avatar' src='{img_url}' />"
                         f"</div>"
                     )
                 html_parts.append("</div>")
@@ -423,7 +375,7 @@ class DocumentDatesPlugin(BasePlugin):
         if self.config['position'] == 'top':
             first_line, insert_pos = self.find_markdown_body_start(markdown)
             if first_line.startswith(('# ', '<h1')):
-                return markdown[:insert_pos] + date_info + '\n' + markdown[insert_pos:]
+                return markdown[:insert_pos] + '\n' + date_info + '\n' + markdown[insert_pos:]
             else:
                 return f"{date_info}\n{markdown}"
         return f"{markdown}\n\n{date_info}"

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

@@ -43,13 +43,6 @@
     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

mkdocs_document_dates-3.3.2/mkdocs_document_dates/static/config/user.config.js

@@ -0,0 +1,96 @@
+/*
+Part 1: 
+    Configuration Overrides for Tooltip
+    see: https://atomiks.github.io/tippyjs/
+*/
+
+/* Configure one by one: */
+// tooltip_config.theme.light = 'tomato';
+// tooltip_config.placement = 'top';
+// tooltip_config.arrow = false;
+
+/* Or, override all configuration items: */
+/*
+TooltipConfig.setConfig({
+    theme: {
+        // configurable: light material, or custom theme in user.config.css, for example: sorrel sublime tomato
+        light: 'light',
+        dark: 'material'
+    },
+    placement: 'bottom',    // placement: top bottom left right auto
+    offset: [0, 12],        // placement offset: [horizontal, vertical]
+    allowHTML: true,        // whether to allow HTML in the tooltip content
+    interactive: true,      // content in Tooltip is interactive
+    animation: 'scale',     // animation type: scale shift-away
+    inertia: true,          // animation inertia
+    // arrow: false,           // whether to allow arrows
+    // animateFill: true,      // determines if the background fill color should be animated
+    // delay: [400, null],     // delay: [show, hide]: show is 400ms, and hide is null for the default value
+});
+*/
+
+
+
+/*
+Part 2: 
+    Demonstrates how to register a local language when using 'timeago.js', 
+        then you can configure the localeStr you just registered anywhere!
+*/
+/*
+const localeFunc = (number, index) => {
+    return [
+        ['just now', 'right now'],
+        ['%s seconds ago', 'in %s seconds'],
+        ['1 minute ago', 'in 1 minute'],
+        ['%s minutes ago', 'in %s minutes'],
+        ['1 hour ago', 'in 1 hour'],
+        ['%s hours ago', 'in %s hours'],
+        ['1 day ago', 'in 1 day'],
+        ['%s days ago', 'in %s days'],
+        ['1 week ago', 'in 1 week'],
+        ['%s weeks ago', 'in %s weeks'],
+        ['1 month ago', 'in 1 month'],
+        ['%s months ago', 'in %s months'],
+        ['1 year ago', 'in 1 year'],
+        ['%s years ago', 'in %s years']
+    ][index];
+};
+const localeStr = 'any';
+timeago.register(localeStr, localeFunc);
+*/
+
+
+
+/*
+Part 3: 
+    Demonstrates how to register the local language for the plugin's tooltip,
+        when the local language is missing, or when the default language translation is inaccurate.
+*/
+/*
+// Way 1: User-defined one language
+TooltipLanguage.register('en', {
+    created_time: "Custom Created",
+    modified_time: "Custom Last Update",
+    author: "Custom Author",
+    authors: "Custom Authors"
+});
+
+// Way 2: User-defined multiple languages
+const userLanguages = {
+    en: {
+        created_time: "Created",
+        modified_time: "Last Update",
+        author: "Author",
+        authors: "Authors"
+    },
+    zh: {
+        created_time: "创建时间",
+        modified_time: "最后更新",
+        author: "作者",
+        authors: "作者"
+    }
+};
+Object.entries(userLanguages).forEach(([locale, data]) => {
+    TooltipLanguage.register(locale, data);
+});
+*/