mkdocs-document-dates 3.7.3__tar.gz → 3.8.0__tar.gz

{mkdocs_document_dates-3.7.3/mkdocs_document_dates.egg-info → mkdocs_document_dates-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.7.3
+Version: 3.8.0
 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
@@ -13,6 +13,7 @@ Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mkdocs<=1.6.1,>=1.6
+Requires-Dist: properdocs>=1.6.5
 Dynamic: license-file
 
 # mkdocs-document-dates
@@ -81,8 +82,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.3 → mkdocs_document_dates-3.8.0}/README.md

@@ -64,8 +64,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.3 → mkdocs_document_dates-3.8.0}/mkdocs_document_dates/cache_manager.py

@@ -164,7 +164,7 @@ def update_cache():
             global_updated = setup_gitattributes(docs_dir)
 
             # 获取docs目录下已跟踪(tracked)的markdown文件
-            cmd = ["git", "ls-files", "*.md"]
+            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 []
 
@@ -185,13 +185,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:

{mkdocs_document_dates-3.7.3 → mkdocs_document_dates-3.8.0}/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,14 +44,13 @@ 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'
@@ -65,20 +63,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 +135,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
         }
@@ -205,9 +198,14 @@ class DocumentDatesPlugin(BasePlugin):
         exclude_list = recently_updated_config.get('exclude', [])
         limit = recently_updated_config.get('limit', 10)
 
+        # 获取站点 URL 路径前缀
+        site_url = config.get("site_url", "")
+        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)
+        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", {}):
@@ -285,42 +283,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
@@ -402,7 +389,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.3 → mkdocs_document_dates-3.8.0}/mkdocs_document_dates/static/templates/recently_updated_group.html

@@ -260,11 +260,19 @@
         --summary-lines-grid: {{ summary_lines.grid }};
         --summary-lines-detail: {{ summary_lines.detail }};
      ">
-    {%- for mtime, rel_path, title, url, cover, summary, readtime, tags in recent_docs %}
+    {%- for doc in recent_docs %}
+    {%- set title = doc.title | default('') %}
+    {%- set url = doc.url | default('') %}
+    {%- set updated_dt = doc.updated_dt | default('') %}
+    {%- set updated = doc.updated | default(updated_dt[:10]) %}
+    {%- set cover = doc.cover | default('') %}
+    {%- set summary = doc.summary | default('') %}
+    {%- set readtime = doc.readtime | default(0) %}
+    {%- set tags = doc.tags | default([]) %}
     <div class="article-card">
         <a class="card-header" href="{{ url }}" target="_blank">
             <div class="card-title">{{ title }}</div>
-            <time class="dd-timeago card-date" datetime="{{ mtime }}">{{ mtime[:10] }}</time>
+            <time class="dd-timeago card-date" datetime="{{ updated_dt }}">{{ updated }}</time>
         </a>
         <div class="card-body">
             {%- if cover %}

{mkdocs_document_dates-3.7.3 → mkdocs_document_dates-3.8.0}/mkdocs_document_dates/utils.py

@@ -8,7 +8,8 @@ import fnmatch
 import re
 import math
 from pathlib import Path
-from datetime import datetime
+from operator import itemgetter
+from datetime import datetime, timezone
 from collections import defaultdict
 from mkdocs.structure.files import Files
 
@@ -16,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 []
@@ -35,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 = {}
@@ -73,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)
@@ -92,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:
@@ -117,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'
             )
             # 只记录已跟踪的文件（还有已删除、重命名、不再跟踪）
@@ -133,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)
@@ -143,7 +182,7 @@ def load_git_last_updated_dates(docs_dir_path: Path):
     return doc_mtime_map
 
 # 建议在 on_page_markdown 之后的全局事件中调用，因为需要读取 page.meta 中的信息
-def get_recently_updated_files(existing_dates: dict, files: Files, exclude_list: list, limit: int = 10, recent_enable: bool = False):
+def get_recently_updated_files(existing_dates: dict, files: Files, exclude_list: list, limit: int = 10, recent_enable: bool = False, prefix: str = ""):
     recently_updated_results = []
     if recent_enable:
         files_meta = []
@@ -152,19 +191,18 @@ 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
-            url = file.page.url if file.page and file.page.url else file.url
-            tags = file.page.meta.get("tags") or []
+            url = prefix + (file.page.url if file.page and file.page.url else file.url)
+            tags = (file.page.meta.get("tags") or []) if file.page else []
 
             cover = ''
             summary = ''
@@ -172,25 +210,37 @@ def get_recently_updated_files(existing_dates: dict, files: Files, exclude_list:
             # authors = []
             if file.page:
                 cover = file.page.meta.get('cover', '')
+                if cover and not cover.startswith(('http', 'ftp')):
+                    cover = prefix + cover.lstrip('/')
                 # authors = file.page.meta.document_dates.authors
                 if file.page.file:
                     summary, readtime = analyze_markdown(file.page.file.content_string)
 
-            meta_readtime = int(file.page.meta.get('readtime') or 0)
+            meta_readtime = int((file.page.meta.get('readtime') or 0) if file.page else 0)
             readtime = meta_readtime if meta_readtime > 0 else readtime
 
             # 存储信息（更新时间、路径、标题、URL、封面、摘要、阅读时间、标签）
-            files_meta.append((mtime, rel_path, title, url, cover, summary, readtime, tags))
-            # existing_map[rel_path] = mtime
+            files_meta.append({
+                "updated_ts": mtime,
+                "rel_path": rel_path,
+                "title": title,
+                "url": url,
+                "cover": cover,
+                "summary": summary,
+                "readtime": readtime,
+                "tags": tags,
+            })
 
         # 构建最近更新列表
         if files_meta:
             # heapq 取 top limit
-            top_results = heapq.nlargest(limit, files_meta, key=lambda x: x[0])
-            recently_updated_results = [
-                (datetime.fromtimestamp(mtime).strftime("%Y-%m-%d %H:%M:%S"), *rest)
-                for mtime, *rest in top_results
-            ]
+            recently_updated_results = heapq.nlargest(limit, files_meta, key=itemgetter("updated_ts"))
+
+            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
 
@@ -204,8 +254,11 @@ 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()))
+                            if isinstance(file_info, dict):
+                                if file_info.get('created'):
+                                    file_info['created'] = int(datetime.fromisoformat(file_info['created']).timestamp())
                             dates_cache[file_path] = file_info
-                    except (json.JSONDecodeError, StopIteration) as e:
+                    except (json.JSONDecodeError, StopIteration, ValueError) as e:
                         logger.warning(f"Skipping invalid JSONL line: {e}")
         except IOError as e:
             logger.warning(f"Error reading from '.dates_cache.jsonl': {str(e)}")
@@ -218,6 +271,9 @@ 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:
+                    file_info = dates_cache[file_path].copy()
+                    if file_info.get('created') is not None:
+                        file_info['created'] = datetime.fromtimestamp(file_info['created'], tz=timezone.utc).isoformat()
                     entry = {file_path: dates_cache[file_path]}
                     f.write(json.dumps(entry, ensure_ascii=False) + '\n')
         
@@ -228,7 +284,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 IOError 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}")
@@ -503,4 +559,4 @@ def analyze_markdown(md: str) -> list:
     summary = MD_SYNTAX_RE.sub("", "  ".join(summary_lines)).strip()
     minutes = max(1, math.ceil(seconds / 60))
 
-    return summary, minutes
+    return summary, minutes

{mkdocs_document_dates-3.7.3 → mkdocs_document_dates-3.8.0/mkdocs_document_dates.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-document-dates
-Version: 3.7.3
+Version: 3.8.0
 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
@@ -13,6 +13,7 @@ Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mkdocs<=1.6.1,>=1.6
+Requires-Dist: properdocs>=1.6.5
 Dynamic: license-file
 
 # mkdocs-document-dates
@@ -81,8 +82,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.3 → mkdocs_document_dates-3.8.0}/mkdocs_document_dates.egg-info/requires.txt

@@ -1 +1,2 @@
 mkdocs<=1.6.1,>=1.6
+properdocs>=1.6.5

{mkdocs_document_dates-3.7.3 → mkdocs_document_dates-3.8.0}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mkdocs-document-dates"
-version = "3.7.3"
+version = "3.8.0"
 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"
 license = "MIT"
 authors = [{ name = "Aaron Wang", email = "aaronwqt@gmail.com" }]
 dependencies = [
-  "mkdocs>=1.6,<=1.6.1"
-  # "properdocs>=1.6.5"
+  "mkdocs>=1.6,<=1.6.1",
+  "properdocs>=1.6.5"
 ]
 classifiers = [
   "Programming Language :: Python :: 3",

{mkdocs_document_dates-3.7.3 → mkdocs_document_dates-3.8.0}/setup.py

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