mkdocs-document-dates 3.7.4__tar.gz → 3.8.1__tar.gz

{mkdocs_document_dates-3.7.4/mkdocs_document_dates.egg-info → mkdocs_document_dates-3.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.7.4
+Version: 3.8.1
 Summary: A new generation MkDocs plugin for displaying exact creation date, last updated date, authors, email of documents
 Author-email: Aaron Wang <aaronwqt@gmail.com>
 License-Expression: MIT
@@ -44,6 +44,8 @@ A new generation MkDocs plugin for displaying exact **creation date, last update
 | git-revision-date-localized<br />git-authors |  ＞ 3 s   |  ＞ 30 s   |    O(n)    |
 | document-dates              | < 0.1 s  | < 0.15 s  |    O(1)    |
 
+> It's 20-500 times faster than `git-revision-date-localized` and `git-authors`
+
 ## Installation
 
 ```bash
@@ -82,8 +84,8 @@ In addition to the above basic configuration, the plug-in also provides a wealth
 - [Structure and Style](https://jaywhj.netlify.app/document-dates-en#Structure-and-Style): You can freely configure the plugin's display structure in mkdocs.yml or Front Matter. You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on
 - [Template Variables](https://jaywhj.netlify.app/document-dates-en#Template-Variables): Can be used to optimize `sitemap.xml` for site SEO
 - [Recently Updated Module](https://jaywhj.netlify.app/document-dates-en#Recently-Updated-Module): Enable list of recently updated documents (in descending order of update date), this is ideal for sites with a large number of documents, so that readers can quickly see what's new
-- [Localization Language](https://jaywhj.netlify.app/document-dates-en#Localization-Language): More localization languages for `timeago` and `tooltip` 
-- [Development Stories](https://jaywhj.netlify.app/document-dates-en#Development-Stories): Describes the origin of the plug-in, the difficulties and solutions encountered in development, and the principles and directions of product design
+- [Localization Language](https://jaywhj.netlify.app/document-dates-en#Localization-Language): More localization languages for `timeago` and `tooltip`
+- [Developer API](https://jaywhj.netlify.app/document-dates-en#Developer-API): Provides a date data API for developers, making it easy to retrieve exact dates in other plugins or hooks
 
 See the documentation for details: https://jaywhj.netlify.app/document-dates-en
 

{mkdocs_document_dates-3.7.4 → mkdocs_document_dates-3.8.1}/README.md

@@ -26,6 +26,8 @@ A new generation MkDocs plugin for displaying exact **creation date, last update
 | git-revision-date-localized<br />git-authors |  ＞ 3 s   |  ＞ 30 s   |    O(n)    |
 | document-dates              | < 0.1 s  | < 0.15 s  |    O(1)    |
 
+> It's 20-500 times faster than `git-revision-date-localized` and `git-authors`
+
 ## Installation
 
 ```bash
@@ -64,8 +66,8 @@ In addition to the above basic configuration, the plug-in also provides a wealth
 - [Structure and Style](https://jaywhj.netlify.app/document-dates-en#Structure-and-Style): You can freely configure the plugin's display structure in mkdocs.yml or Front Matter. You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on
 - [Template Variables](https://jaywhj.netlify.app/document-dates-en#Template-Variables): Can be used to optimize `sitemap.xml` for site SEO
 - [Recently Updated Module](https://jaywhj.netlify.app/document-dates-en#Recently-Updated-Module): Enable list of recently updated documents (in descending order of update date), this is ideal for sites with a large number of documents, so that readers can quickly see what's new
-- [Localization Language](https://jaywhj.netlify.app/document-dates-en#Localization-Language): More localization languages for `timeago` and `tooltip` 
-- [Development Stories](https://jaywhj.netlify.app/document-dates-en#Development-Stories): Describes the origin of the plug-in, the difficulties and solutions encountered in development, and the principles and directions of product design
+- [Localization Language](https://jaywhj.netlify.app/document-dates-en#Localization-Language): More localization languages for `timeago` and `tooltip`
+- [Developer API](https://jaywhj.netlify.app/document-dates-en#Developer-API): Provides a date data API for developers, making it easy to retrieve exact dates in other plugins or hooks
 
 See the documentation for details: https://jaywhj.netlify.app/document-dates-en
 

{mkdocs_document_dates-3.7.4 → mkdocs_document_dates-3.8.1}/mkdocs_document_dates/cache_manager.py

@@ -10,13 +10,19 @@ from .utils import read_jsonl_cache, write_jsonl_cache, load_file_creation_date,
 logger = logging.getLogger("mkdocs.plugins.document_dates")
 _LOGGING_CONFIGURED = False
 
+CONFIG_PRIORITY = {
+    "mkdocs.yml": 0,
+    "properdocs.yml": 1,
+    "mkdocs.yaml": 2,
+    "properdocs.yaml": 3,
+}
 
 def _default_log_file() -> Path:
     try:
         git_root = Path(subprocess.check_output(
-            ['git', 'rev-parse', '--show-toplevel'],
+            ["git", "rev-parse", "--show-toplevel"],
             env=_clean_git_env(),
-            encoding='utf-8'
+            encoding="utf-8"
         ).strip())
         base_dir = git_root
     except Exception:
@@ -82,20 +88,29 @@ def _clean_git_env():
 
     return env
 
-def find_mkdocs_projects():
-    projects = set()
+def find_mkdocs_projects() -> dict[Path, Path]:
+    projects = {}
 
     try:
         git_root = Path(subprocess.check_output(
-            ['git', 'rev-parse', '--show-toplevel'],
+            ["git", "rev-parse", "--show-toplevel"],
             env=_clean_git_env(),
-            encoding='utf-8'
+            encoding="utf-8"
         ).strip())
 
-        target_names = {'mkdocs.yml', 'properdocs.yml'}
-        for config_file in git_root.rglob('*.yml'):
-            if config_file.name.lower() in target_names:
-                projects.add(config_file.parent)
+        for pattern in ("*.yml", "*.yaml"):
+            for config_file in git_root.rglob(pattern):
+                name = config_file.name.lower()
+                if name not in CONFIG_PRIORITY:
+                    continue
+
+                project_dir = config_file.parent
+                existing = projects.get(project_dir)
+                if existing is None:
+                    projects[project_dir] = config_file
+                    continue
+                if CONFIG_PRIORITY[name] < CONFIG_PRIORITY[existing.name.lower()]:
+                    projects[project_dir] = config_file
 
         if not projects:
             logger.warning("No MkDocs/ProperDocs projects found in the repository")
@@ -105,19 +120,19 @@ def find_mkdocs_projects():
     except Exception as e:
         logger.error(f"Unexpected error while searching for projects: {e}")
 
-    return list(projects)
+    return projects
 
 def setup_gitattributes(docs_dir: Path):
     try:
-        gitattributes_path = docs_dir / '.gitattributes'
+        gitattributes_path = docs_dir / ".gitattributes"
         union_merge_line = ".dates_cache.jsonl merge=union"
         # custom_merge_line = ".dates_cache.json merge=custom_json_merge"
-        content = gitattributes_path.read_text(encoding='utf-8') if gitattributes_path.exists() else ""
+        content = gitattributes_path.read_text(encoding="utf-8") if gitattributes_path.exists() else ""
         if union_merge_line not in content:
-            if content and not content.endswith('\n'):
-                content += '\n'
+            if content and not content.endswith("\n"):
+                content += "\n"
             content += f"{union_merge_line}\n"
-            gitattributes_path.write_text(content, encoding='utf-8')
+            gitattributes_path.write_text(content, encoding="utf-8")
             subprocess.run(["git", "add", str(gitattributes_path)], cwd=docs_dir, env=_clean_git_env(), check=True)
             logger.info(f"Updated .gitattributes file: {gitattributes_path}")
             return True
@@ -134,18 +149,14 @@ def update_cache():
         configure_file_logging(_default_log_file())
 
     global_updated = False
-    for project_dir in find_mkdocs_projects():
+    for project_dir, mkdocs_yml in find_mkdocs_projects().items():
         try:
             project_updated = False
 
-            docs_dir = project_dir / 'docs'
+            docs_dir = project_dir / "docs"
 
             # 从 mkdocs.yml 中读取 docs_dir 配置覆盖默认值
             try:
-                mkdocs_yml = project_dir / "properdocs.yml"
-                if not mkdocs_yml.exists():
-                    mkdocs_yml = project_dir / "mkdocs.yml"
-
                 mkdocs_config = yaml.load(
                     mkdocs_yml.read_text(encoding="utf-8"),
                     Loader=yaml.BaseLoader,
@@ -156,16 +167,16 @@ def update_cache():
             except (IOError, OSError, yaml.YAMLError) as e:
                 logger.warning(f"Failed to read docs_dir: {e}")
 
-            if not docs_dir.exists():
+            if not docs_dir.is_dir():
                 logger.info(f"Document directory does not exist: {docs_dir}")
                 continue
 
             # 设置.gitattributes文件
-            global_updated = setup_gitattributes(docs_dir)
+            global_updated |= setup_gitattributes(docs_dir)
 
             # 获取docs目录下已跟踪(tracked)的markdown文件
-            cmd = ["git", "ls-files", "*.md"]
-            result = subprocess.run(cmd, cwd=docs_dir, env=_clean_git_env(), capture_output=True, encoding='utf-8')
+            cmd = ["git", "-c", "core.quotepath=false", "ls-files", "*.md"]
+            result = subprocess.run(cmd, cwd=docs_dir, env=_clean_git_env(), capture_output=True, encoding="utf-8")
             tracked_files = result.stdout.splitlines() if result.stdout else []
 
             if not tracked_files:
@@ -173,7 +184,7 @@ def update_cache():
                 continue
 
             # 读取 JSONL 缓存
-            jsonl_cache_file = docs_dir / '.dates_cache.jsonl'
+            jsonl_cache_file = docs_dir / ".dates_cache.jsonl"
             jsonl_dates_cache = read_jsonl_cache(jsonl_cache_file)
 
             # 根据 git已跟踪的文件来更新
@@ -185,13 +196,13 @@ def update_cache():
 
                     full_path = docs_dir / rel_path
                     if full_path.exists():
-                        created_time = load_file_creation_date(full_path).astimezone()
+                        created_time = load_file_creation_date(full_path)
                         if not jsonl_cache_file.exists():
                             git_time = load_git_first_commit_date(full_path)
                             if git_time:
                                 created_time = min(created_time, git_time)
                         jsonl_dates_cache[rel_path] = {
-                            "created": created_time.isoformat()
+                            "created": int(created_time.timestamp())
                         }
                         project_updated = True
                 except Exception as e:
@@ -204,7 +215,7 @@ def update_cache():
 
             # 如果有更新，写入 JSONL 缓存文件
             if project_updated or not jsonl_cache_file.exists():
-                global_updated = write_jsonl_cache(jsonl_cache_file, jsonl_dates_cache, tracked_files)
+                global_updated |= write_jsonl_cache(jsonl_cache_file, jsonl_dates_cache, tracked_files)
         except subprocess.CalledProcessError as e:
             logger.error(f"Failed to execute git command: {e}")
             continue

{mkdocs_document_dates-3.7.4 → mkdocs_document_dates-3.8.1}/mkdocs_document_dates/plugin.py

@@ -1,16 +1,15 @@
-import os
 import yaml
 import shutil
 import logging
 from jinja2 import ChoiceLoader, FileSystemLoader
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from mkdocs.plugins import BasePlugin, event_priority
 from mkdocs.config import config_options
 from mkdocs.structure.pages import Page
 from mkdocs.utils import get_relative_url
 from urllib.parse import urlparse
-from .utils import load_file_creation_date, load_git_metadata, load_git_last_updated_dates, read_jsonl_cache, compile_exclude_patterns, is_excluded, get_recently_updated_files
+from .utils import compile_exclude_patterns, is_excluded, get_recently_updated_files, load_dates_and_authors
 
 logger = logging.getLogger("mkdocs.plugins.document_dates")
 logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
@@ -45,18 +44,23 @@ class DocumentDatesPlugin(BasePlugin):
         super().__init__()
 
         self.data_cached = {}
-        self.last_updated_dates = {}
         self.authors_yml = {}
         self.recent_docs_html = None
         self.recent_enable = False
         self._exclude_patterns = []
 
     def on_config(self, config):
-        docs_dir_path = Path(config['docs_dir'])
+        docs_dir_path = Path(config.docs_dir)
 
         # 加载 author 配置
-        authors_file = docs_dir_path / 'authors.yml'
-        if not authors_file.exists():
+        authors_file = None
+        for name in ("authors.yml", "authors.yaml"):
+            candidate = docs_dir_path / name
+            if candidate.exists():
+                authors_file = candidate
+                break
+
+        if authors_file is None:
             try:
                 blog_config = config.plugins.get(f"{config.theme.name}/blog").config
                 authors_file_resolved = blog_config.authors_file.format(blog=blog_config.blog_dir)
@@ -65,20 +69,6 @@ class DocumentDatesPlugin(BasePlugin):
                 pass
         self._load_authors_from_yaml(authors_file)
 
-        # 加载文档 git 元数据(日期 & 作者)
-        self.data_cached = load_git_metadata(docs_dir_path)
-        # 加载 jsonl 缓存数据
-        jsonl_cache_file = docs_dir_path / '.dates_cache.jsonl'
-        if jsonl_cache_file.exists():
-            jsonl_cache = read_jsonl_cache(jsonl_cache_file)
-            for filename, new_info in jsonl_cache.items():
-                if filename in self.data_cached:
-                    self.data_cached[filename].update(new_info)
-
-        # 加载文档最近更新时间(日期)
-        self.last_updated_dates = load_git_last_updated_dates(docs_dir_path)
-
-
         # 复制配置文件到用户目录（如果不存在）
         dest_dir = docs_dir_path / 'assets' / 'document_dates'
         dest_dir.mkdir(parents=True, exist_ok=True)
@@ -151,32 +141,41 @@ class DocumentDatesPlugin(BasePlugin):
 
         return config
 
+    @event_priority(50)
+    def on_files(self, files, config):
+        self.data_cached = load_dates_and_authors(Path(config.docs_dir), files)
+        return files
+
     @event_priority(50)
     def on_page_markdown(self, markdown, page: Page, config, files):
         # 获取相对路径，src_uri 总是以"/"分隔
-        rel_path = getattr(page.file, 'src_uri', page.file.src_path)
-        if os.sep != '/':
-            rel_path = rel_path.replace(os.sep, '/')
-        file_path = page.file.abs_src_path
-        
+        rel_path = getattr(page.file, 'src_uri')
+
         # 优先获取 page.meta 中的数据
         created = self._load_meta_date(page.meta, self.config['created_field_names'])
         updated = self._load_meta_date(page.meta, self.config['updated_field_names'])
         authors = self._load_meta_author(page.meta, page.url)
 
-        # 再获取缓存的数据
-        if not created:
-            created = self._load_created_cached(file_path, rel_path)
-        if not updated:
-            updated = self._load_updated_cached(file_path, rel_path)
+        # 如果 meta 数据存在，则存储
+        cache = self.data_cached.setdefault(rel_path, {})
+        if created:
+            cache['created'] = created
+        else:
+            created = cache.get('created')
+
+        if updated:
+            cache['updated'] = updated
+        else:
+            updated = cache.get('updated')
+
         if not authors:
             authors = self._load_author_cached(rel_path, page, config)
 
-        # 注入数据
+        # 注入数据到模板 (utc datetime -> local datetime)
         page.meta["document_dates"] = {
             "dates": {
-                "created": created.isoformat(),
-                "updated": updated.isoformat(),
+                "created": created.astimezone().isoformat() if created else None,
+                "updated": updated.astimezone().isoformat() if updated else None,
             },
             "authors": authors
         }
@@ -206,13 +205,13 @@ class DocumentDatesPlugin(BasePlugin):
         limit = recently_updated_config.get('limit', 10)
 
         # 获取站点 URL 路径前缀
-        site_url = config.get("site_url", "")
+        site_url = config.get("site_url") or ""
         base_path = urlparse(site_url).path.rstrip("/")
         prefix = f"{base_path}/" if base_path else "/"
 
         # 获取最近更新的文档数据
         recent_exclude_patterns = compile_exclude_patterns(exclude_list)
-        recently_updated_docs = get_recently_updated_files(self.last_updated_dates, files, recent_exclude_patterns, limit, self.recent_enable, prefix)
+        recently_updated_docs = get_recently_updated_files(self.data_cached, files, recent_exclude_patterns, limit, self.recent_enable, prefix)
 
         # 将数据注入到 config['extra'] 中供全局访问
         if not config.get('extra', {}).get("recently_updated_docs", {}):
@@ -290,42 +289,31 @@ class DocumentDatesPlugin(BasePlugin):
         for field in field_names:
             if field in meta:
                 try:
-                    # 移除首尾可能存在的单双引号和时区信息
+                    # 移除首尾可能存在的单双引号
                     date_str = str(meta[field]).strip("'\"")
-                    return datetime.fromisoformat(date_str).replace(tzinfo=None)
+                    dt = datetime.fromisoformat(date_str)
+                    # 如果没时区，则当成本地时间，再转 UTC
+                    if dt.tzinfo is None:
+                        local_tz = datetime.now().astimezone().tzinfo
+                        dt = dt.replace(tzinfo=local_tz)
+                    return dt.astimezone(timezone.utc)
+                    # return datetime.fromisoformat(date_str).astimezone()
                 except Exception:
                     continue
         return None
 
-    def _load_created_cached(self, file_path, rel_path):
-        # 优先从缓存中读取
-        if rel_path in self.data_cached:
-            return datetime.fromisoformat(self.data_cached[rel_path]['created'])
-        # 从文件系统获取
-        return load_file_creation_date(file_path).astimezone()
-
-    def _load_updated_cached(self, file_path, rel_path):
-        # 优先从缓存中读取
-        if rel_path in self.last_updated_dates:
-            return datetime.fromtimestamp(self.last_updated_dates[rel_path]).astimezone()
-        # 从文件系统获取最后修改时间
-        stat = os.stat(file_path)
-        return datetime.fromtimestamp(stat.st_mtime).astimezone()
-
-
     def _load_author_cached(self, rel_path, page, config):
         # 1. git author
-        if rel_path in self.data_cached:
-            authors_list = self.data_cached[rel_path].get('authors')
-            if authors_list:
-                authors = []
-                for data in authors_list:
-                    full_author = self.authors_yml.get(data['name'])
-                    if full_author:
-                        authors.append(self._repair_author(full_author, page.url))
-                    else:
-                        authors.append(Author(**data))
-                return authors
+        authors_list = self.data_cached.get(rel_path, {}).get('authors', None)
+        if authors_list:
+            authors = []
+            for data in authors_list:
+                full_author = self.authors_yml.get(data['name'])
+                if full_author:
+                    authors.append(self._repair_author(full_author, page.url))
+                else:
+                    authors.append(Author(**data))
+            return authors
 
         # 2. site_author 或 PC username
         name = config.get('site_author') or Path.home().name
@@ -407,7 +395,7 @@ class DocumentDatesPlugin(BasePlugin):
                 return (
                     f"<span class='dd-item' data-tippy-content data-tippy-raw='{formatted}'>"
                     f"<span class='material-icons' data-icon='{icon}'></span>"
-                    f"<time datetime='{time_obj.isoformat()}'>{self._formatting_date(time_obj)}</time>"
+                    f"<time datetime='{time_obj.astimezone().isoformat()}'>{self._formatting_date(time_obj)}</time>"
                     f"</span>"
                 )
 

{mkdocs_document_dates-3.7.4 → mkdocs_document_dates-3.8.1}/mkdocs_document_dates/utils.py

@@ -9,7 +9,7 @@ import re
 import math
 from pathlib import Path
 from operator import itemgetter
-from datetime import datetime
+from datetime import datetime, timezone
 from collections import defaultdict
 from mkdocs.structure.files import Files
 
@@ -17,6 +17,44 @@ logger = logging.getLogger("mkdocs.plugins.document_dates")
 logger.setLevel(logging.WARNING)  # DEBUG, INFO, WARNING, ERROR, CRITICAL
 
 
+def load_dates_and_authors(docs_dir_path: Path, files: Files):
+
+    # git 创建日期
+    created_data = load_git_metadata(docs_dir_path)
+
+    # 覆盖 jsonl 创建日期
+    jsonl_cache_file = docs_dir_path / '.dates_cache.jsonl'
+    if jsonl_cache_file.exists():
+        jsonl_cache = read_jsonl_cache(jsonl_cache_file)
+        for filename, new_info in jsonl_cache.items():
+            if filename in created_data:
+                created_data[filename].update(new_info)
+
+    # git 更新日期
+    updated_data = load_git_last_updated_dates(docs_dir_path)
+
+    for file in files:
+        if file.inclusion.is_excluded():
+            continue
+        if not file.src_path.endswith('.md'):
+            continue
+        rel_path = getattr(file, 'src_uri')
+
+        # created: timestamp -> datetime
+        cache = created_data.setdefault(rel_path, {})
+        created_ts = cache.get('created')
+        cache['created'] = (
+            datetime.fromtimestamp(created_ts, tz=timezone.utc)
+            if created_ts is not None
+            else load_file_creation_date(file.abs_src_path)
+        )
+
+        # updated: timestamp -> datetime
+        mtime = updated_data.get(rel_path, os.path.getmtime(file.abs_src_path))
+        created_data[rel_path]['updated'] = datetime.fromtimestamp(mtime, tz=timezone.utc)
+
+    return created_data
+
 def compile_exclude_patterns(exclude_list):
     if not exclude_list:
         return []
@@ -36,34 +74,34 @@ def is_excluded(path, patterns):
                 return True
     return False
 
-def load_file_creation_date(file_path):
+def load_file_creation_date(file_path) -> datetime:
     try:
         stat = os.stat(file_path)
         system = platform.system().lower()
         if system.startswith('win'):  # Windows
-            return datetime.fromtimestamp(stat.st_ctime)
+            return datetime.fromtimestamp(stat.st_ctime, tz=timezone.utc)
         elif system == 'darwin':  # macOS
             try:
-                return datetime.fromtimestamp(stat.st_birthtime)
+                return datetime.fromtimestamp(stat.st_birthtime, tz=timezone.utc)
             except AttributeError:
-                return datetime.fromtimestamp(stat.st_ctime)
+                return datetime.fromtimestamp(stat.st_ctime, tz=timezone.utc)
         else:  # Linux, 没有创建时间，使用修改时间
-            return datetime.fromtimestamp(stat.st_mtime)
+            return datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc)
     except (OSError, ValueError) as e:
         logger.error(f"Failed to load file creation date for {file_path}: {e}")
-        return datetime.now()
+        return datetime.now(timezone.utc)
 
-def load_git_first_commit_date(file_path):
+def load_git_first_commit_date(file_path) -> datetime:
     try:
         # git log --reverse --format="%aI" -- {file_path} | head -n 1
-        cmd_list = ['git', 'log', '--reverse', '--format=%aI', '--', file_path]
+        cmd_list = ['git', 'log', '--reverse', '--format=%at', '--', file_path]
         process = subprocess.run(cmd_list, capture_output=True, encoding='utf-8')
         if process.returncode == 0 and process.stdout.strip():
-            first_line = process.stdout.partition('\n')[0].strip()
-            return datetime.fromisoformat(first_line)
+            first_line = int(process.stdout.partition('\n')[0].strip())
+            return datetime.fromtimestamp(first_line, tz=timezone.utc)
     except Exception as e:
         logger.info(f"Error load git first commit date for {file_path}: {e}")
-    return None
+    return datetime.now(timezone.utc)
 
 def load_git_metadata(docs_dir_path: Path):
     dates_cache = {}
@@ -74,7 +112,7 @@ def load_git_metadata(docs_dir_path: Path):
         ).strip())
         rel_docs_path = docs_dir_path.relative_to(git_root).as_posix()
 
-        cmd = ['git', 'log', '--reverse', '--no-merges', '--use-mailmap', '--name-only', '--format=%aN|%aE|%aI', f'--relative={rel_docs_path}', '--', '*.md']
+        cmd = ['git', '-c', 'core.quotepath=false', 'log', '--reverse', '--no-merges', '--use-mailmap', '--name-only', '--format=%aN|%aE|%at', f'--relative={rel_docs_path}', '--', '*.md']
         process = subprocess.run(cmd, cwd=docs_dir_path, capture_output=True, encoding='utf-8')
         if process.returncode == 0:
             authors_dict = defaultdict(dict)
@@ -93,7 +131,7 @@ def load_git_metadata(docs_dir_path: Path):
                         # a.巧用 Python 字典的 setdefault 特性来去重（setdefault 为不存在的键提供初始值，不会覆盖已有值）
                         # b.巧用 Python 字典的插入顺序特性来保留内容插入顺序（Python 3.7+ 字典会保持插入顺序）
                     authors_dict[line].setdefault((name, email), None)
-                    first_commit.setdefault(line, created)
+                    first_commit.setdefault(line, int(created))
 
             # 构建最终的缓存数据
             for file_path in first_commit:
@@ -118,11 +156,11 @@ def load_git_last_updated_dates(docs_dir_path: Path):
         ).strip())
         rel_docs_path = docs_dir_path.relative_to(git_root).as_posix()
 
-        cmd = ['git', 'log', '--no-merges', '--use-mailmap', '--format=%aN|%aE|%at', '--name-only', f'--relative={rel_docs_path}', '--', '*.md']
+        cmd = ['git', '-c', 'core.quotepath=false', 'log', '--no-merges', '--use-mailmap', '--format=%aN|%aE|%at', '--name-only', f'--relative={rel_docs_path}', '--', '*.md']
         process = subprocess.run(cmd, cwd=docs_dir_path, capture_output=True, encoding='utf-8')
         if process.returncode == 0:
             result = subprocess.run(
-                ["git", "ls-files", "*.md"],
+                ['git', '-c', 'core.quotepath=false', 'ls-files', '*.md'],
                 cwd=docs_dir_path, capture_output=True, encoding='utf-8'
             )
             # 只记录已跟踪的文件（还有已删除、重命名、不再跟踪）
@@ -134,7 +172,7 @@ def load_git_last_updated_dates(docs_dir_path: Path):
                 if not line:
                     continue
                 if '|' in line:
-                    ts = float(line.split('|')[2])
+                    ts = int(line.split('|')[2])
                 elif line.endswith('.md') and line in tracked_files and ts:
                     # 只记录第一次出现的文件，即最近一次提交（setdefault 机制不会覆盖已有值）
                     doc_mtime_map.setdefault(line, ts)
@@ -153,14 +191,13 @@ def get_recently_updated_files(existing_dates: dict, files: Files, exclude_list:
                 continue
             if not file.src_path.endswith('.md'):
                 continue
-            rel_path = getattr(file, 'src_uri', file.src_path)
-            if os.sep != '/':
-                rel_path = rel_path.replace(os.sep, '/')
+            rel_path = getattr(file, 'src_uri')
             if is_excluded(rel_path, exclude_list):
                 continue
 
             # 优先从现有数据获取 mtime，如果不存在则 fallback 到文件系统 mtime
-            mtime = existing_dates.get(rel_path, os.path.getmtime(file.abs_src_path))
+            exist_updated: datetime = existing_dates.get(rel_path, {}).get('updated')
+            mtime = exist_updated.timestamp() if exist_updated else os.path.getmtime(file.abs_src_path)
 
             # 获取文档其它信息
             title = file.page.title if file.page and file.page.title else file.name
@@ -193,23 +230,17 @@ def get_recently_updated_files(existing_dates: dict, files: Files, exclude_list:
                 "readtime": readtime,
                 "tags": tags,
             })
-            # existing_map[rel_path] = mtime
 
         # 构建最近更新列表
         if files_meta:
-            fmt_full = "%Y-%m-%d %H:%M:%S"
-            fmt_date = "%Y-%m-%d"
             # heapq 取 top limit
-            top_results = heapq.nlargest(limit, files_meta, key=itemgetter("updated_ts"))
-
-            for doc in top_results:
-                dt = datetime.fromtimestamp(doc["updated_ts"])
+            recently_updated_results = heapq.nlargest(limit, files_meta, key=itemgetter("updated_ts"))
 
-                recently_updated_results.append({
-                    **doc,
-                    "updated_dt": dt.strftime(fmt_full),
-                    "updated": dt.strftime(fmt_date),
-                })
+            for doc in recently_updated_results:
+                # timestamp -> utc datetime -> local datetime
+                dt = datetime.fromtimestamp(doc["updated_ts"], tz=timezone.utc).astimezone()
+                doc["updated_dt"] = dt.isoformat()
+                doc["updated"] = dt.date().isoformat()
 
     return recently_updated_results
 
@@ -223,10 +254,16 @@ def read_jsonl_cache(jsonl_file: Path):
                         entry = json.loads(line.strip())
                         if entry and isinstance(entry, dict) and len(entry) == 1:
                             file_path, file_info = next(iter(entry.items()))
-                            dates_cache[file_path] = file_info
-                    except (json.JSONDecodeError, StopIteration) as e:
+                            if isinstance(file_info, dict):
+                                created = file_info.get('created')
+                                if isinstance(created, str):
+                                    file_info['created'] = int(datetime.fromisoformat(created).timestamp())
+                                elif isinstance(created, (int, float)):
+                                    file_info['created'] = int(created)
+                                dates_cache[file_path] = file_info
+                    except (json.JSONDecodeError, StopIteration, ValueError, TypeError,) as e:
                         logger.warning(f"Skipping invalid JSONL line: {e}")
-        except IOError as e:
+        except OSError as e:
             logger.warning(f"Error reading from '.dates_cache.jsonl': {str(e)}")
     return dates_cache
 
@@ -237,7 +274,11 @@ def write_jsonl_cache(jsonl_file: Path, dates_cache, tracked_files):
         with open(temp_file, 'w', encoding='utf-8') as f:
             for file_path in tracked_files:
                 if file_path in dates_cache:
-                    entry = {file_path: dates_cache[file_path]}
+                    file_info = dates_cache[file_path].copy()
+                    created = file_info.get('created')
+                    if created is not None:
+                        file_info['created'] = datetime.fromtimestamp(created, tz=timezone.utc).isoformat()
+                    entry = {file_path: file_info}
                     f.write(json.dumps(entry, ensure_ascii=False) + '\n')
         
         # 替换原文件
@@ -247,7 +288,7 @@ def write_jsonl_cache(jsonl_file: Path, dates_cache, tracked_files):
         subprocess.run(["git", "add", str(jsonl_file)], check=True)
         logger.info(f"Successfully updated JSONL cache file: {jsonl_file}")
         return True
-    except (IOError, json.JSONDecodeError) as e:
+    except OSError as e:
         logger.warning(f"Failed to write JSONL cache file {jsonl_file}: {e}")
     except Exception as e:
         logger.warning(f"Failed to add JSONL cache file to git: {e}")

{mkdocs_document_dates-3.7.4 → mkdocs_document_dates-3.8.1/mkdocs_document_dates.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.7.4
+Version: 3.8.1
 Summary: A new generation MkDocs plugin for displaying exact creation date, last updated date, authors, email of documents
 Author-email: Aaron Wang <aaronwqt@gmail.com>
 License-Expression: MIT
@@ -44,6 +44,8 @@ A new generation MkDocs plugin for displaying exact **creation date, last update
 | git-revision-date-localized<br />git-authors |  ＞ 3 s   |  ＞ 30 s   |    O(n)    |
 | document-dates              | < 0.1 s  | < 0.15 s  |    O(1)    |
 
+> It's 20-500 times faster than `git-revision-date-localized` and `git-authors`
+
 ## Installation
 
 ```bash
@@ -82,8 +84,8 @@ In addition to the above basic configuration, the plug-in also provides a wealth
 - [Structure and Style](https://jaywhj.netlify.app/document-dates-en#Structure-and-Style): You can freely configure the plugin's display structure in mkdocs.yml or Front Matter. You can quickly set the plugin styles through preset entrances, such as icons, themes, colors, fonts, animations, dividing line and so on
 - [Template Variables](https://jaywhj.netlify.app/document-dates-en#Template-Variables): Can be used to optimize `sitemap.xml` for site SEO
 - [Recently Updated Module](https://jaywhj.netlify.app/document-dates-en#Recently-Updated-Module): Enable list of recently updated documents (in descending order of update date), this is ideal for sites with a large number of documents, so that readers can quickly see what's new
-- [Localization Language](https://jaywhj.netlify.app/document-dates-en#Localization-Language): More localization languages for `timeago` and `tooltip` 
-- [Development Stories](https://jaywhj.netlify.app/document-dates-en#Development-Stories): Describes the origin of the plug-in, the difficulties and solutions encountered in development, and the principles and directions of product design
+- [Localization Language](https://jaywhj.netlify.app/document-dates-en#Localization-Language): More localization languages for `timeago` and `tooltip`
+- [Developer API](https://jaywhj.netlify.app/document-dates-en#Developer-API): Provides a date data API for developers, making it easy to retrieve exact dates in other plugins or hooks
 
 See the documentation for details: https://jaywhj.netlify.app/document-dates-en
 

{mkdocs_document_dates-3.7.4 → mkdocs_document_dates-3.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mkdocs-document-dates"
-version = "3.7.4"
+version = "3.8.1"
 description = "A new generation MkDocs plugin for displaying exact creation date, last updated date, authors, email of documents"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.7"

{mkdocs_document_dates-3.7.4 → mkdocs_document_dates-3.8.1}/setup.py

@@ -4,7 +4,7 @@ from setuptools import find_packages, setup
 def legacy_setup():
     setup(
         name="mkdocs-document-dates",
-        version="3.7.4",
+        version="3.8.1",
         author="Aaron Wang",
         author_email="aaronwqt@gmail.com",
         license="MIT",