mkdocs-document-dates 2.2.0__tar.gz → 2.3.1__tar.gz

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/LICENSE

@@ -9,4 +9,3 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-[... 后续 MIT 许可证内容 ...]

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.2
 Name: mkdocs-document-dates
-Version: 2.2.0
+Version: 2.3.1
 Summary: A MkDocs plugin for displaying accurate document creation and last modification dates.
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mkdocs>=1.0.0
@@ -26,12 +26,12 @@ English | [简体中文](README_zh.md)
 
 
 
-A MkDocs plugin for displaying **accurate** document creation and last modification dates.
+A MkDocs plugin for displaying <mark>accurate</mark> document creation and last modification dates.
 
 ## Features
 
 - Automatically displays document creation and last modification times
-- No Git dependency, uses filesystem timestamps directly
+- **No Git dependency**, uses filesystem timestamps directly
 - Supports manual date specification in `Front Matter`
 - Cross-platform support (Windows, macOS, Linux)
 - Support for multiple time formats (date, datetime, timeago)
@@ -40,6 +40,7 @@ A MkDocs plugin for displaying **accurate** document creation and last modificat
 - Material Design icons, Elegant styling
 - Lightweight with no extra dependencies
 - Multi-language support
+- Support for CI/CD build systems (e.g. Github Actions)
 
 ## Installation
 
@@ -79,7 +80,7 @@ You can also manually specify the date of a Markdown document in its `Front Matt
 ```yaml
 ---
 created: 2023-01-01
-modified: 2023-12-31
+modified: 2025-02-23
 ---
 
 # Document Title
@@ -89,33 +90,35 @@ modified: 2023-12-31
 
 ## Configuration Options
 
-- `type` : Date type (default: `date` )
+- **type** : Date type (default: `date` )
   - `date` : Display date only
   - `datetime` : Display date and time
   - `timeago` : Display relative time (e.g., 2 minutes ago)
-- `locale` : Localization (default: `en` )
+- **locale** : Localization (default: `en` )
   - Supports: `zh zh_tw en es fr de ar ja ko ru`
-- `date_format` : Date format (default: `%Y-%m-%d`)
+- **date_format** : Date format (default: `%Y-%m-%d`)
   - Supports all Python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc.
-- `time_format` : Time format (default: `%H:%M:%S`)
-- `position` : Display position (default: `bottom`)
+- **time_format** : Time format (default: `%H:%M:%S`)
+- **position** : Display position (default: `bottom`)
   - `top` : Display after the first heading
   - `bottom` : Display at the end of the document
-- `exclude` : File exclusion list (default: [] )
+- **exclude** : File exclusion list (default: [] )
   - Supports glob patterns, e.g., ["private/\*", "temp.md", "drafts/\*.md"]
 
 ## Notes
 
-- Creation time behavior varies across operating systems:
-  - Windows: Uses file creation time
-  - macOS: Uses file creation time (birthtime)
-  - Linux: Uses modification time as creation time due to system limitations, if you need the exact creation time, you can manually specify it in Front Matter
 - It still works when using CI/CD build systems (e.g. Github Actions)
   - Used a cache file `.dates_cache.json` to solve this problem
-  - You can configure it like this:
+  - You can configure it like this in your .github/workflows/ci.yml:
+    
     ```
     ...
     
       - run: pip install mkdocs-document-dates
       - run: mkdocs gh-deploy --force
-    ```  
+    ```
+  - Then update your Markdown files in MkDocs as normal, execute commands such as mkdocs build or directly git add, commit, and push
+    - Make sure you have installed python3 ahead of time and set environment variables
+- Priority of time reads:
+  - `Front Matter` > `Cache file` > `Filesystem timestamp`
+- If you are using MkDocs on a Linux system, the modification time is used as the creation time because of system limitations. If you need the exact creation time, you can specify it manually in Front Matter

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/README.md

@@ -4,12 +4,12 @@ English | [简体中文](README_zh.md)
 
 
 
-A MkDocs plugin for displaying **accurate** document creation and last modification dates.
+A MkDocs plugin for displaying <mark>accurate</mark> document creation and last modification dates.
 
 ## Features
 
 - Automatically displays document creation and last modification times
-- No Git dependency, uses filesystem timestamps directly
+- **No Git dependency**, uses filesystem timestamps directly
 - Supports manual date specification in `Front Matter`
 - Cross-platform support (Windows, macOS, Linux)
 - Support for multiple time formats (date, datetime, timeago)
@@ -18,6 +18,7 @@ A MkDocs plugin for displaying **accurate** document creation and last modificat
 - Material Design icons, Elegant styling
 - Lightweight with no extra dependencies
 - Multi-language support
+- Support for CI/CD build systems (e.g. Github Actions)
 
 ## Installation
 
@@ -57,7 +58,7 @@ You can also manually specify the date of a Markdown document in its `Front Matt
 ```yaml
 ---
 created: 2023-01-01
-modified: 2023-12-31
+modified: 2025-02-23
 ---
 
 # Document Title
@@ -67,33 +68,35 @@ modified: 2023-12-31
 
 ## Configuration Options
 
-- `type` : Date type (default: `date` )
+- **type** : Date type (default: `date` )
   - `date` : Display date only
   - `datetime` : Display date and time
   - `timeago` : Display relative time (e.g., 2 minutes ago)
-- `locale` : Localization (default: `en` )
+- **locale** : Localization (default: `en` )
   - Supports: `zh zh_tw en es fr de ar ja ko ru`
-- `date_format` : Date format (default: `%Y-%m-%d`)
+- **date_format** : Date format (default: `%Y-%m-%d`)
   - Supports all Python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc.
-- `time_format` : Time format (default: `%H:%M:%S`)
-- `position` : Display position (default: `bottom`)
+- **time_format** : Time format (default: `%H:%M:%S`)
+- **position** : Display position (default: `bottom`)
   - `top` : Display after the first heading
   - `bottom` : Display at the end of the document
-- `exclude` : File exclusion list (default: [] )
+- **exclude** : File exclusion list (default: [] )
   - Supports glob patterns, e.g., ["private/\*", "temp.md", "drafts/\*.md"]
 
 ## Notes
 
-- Creation time behavior varies across operating systems:
-  - Windows: Uses file creation time
-  - macOS: Uses file creation time (birthtime)
-  - Linux: Uses modification time as creation time due to system limitations, if you need the exact creation time, you can manually specify it in Front Matter
 - It still works when using CI/CD build systems (e.g. Github Actions)
   - Used a cache file `.dates_cache.json` to solve this problem
-  - You can configure it like this:
+  - You can configure it like this in your .github/workflows/ci.yml:
+    
     ```
     ...
     
       - run: pip install mkdocs-document-dates
       - run: mkdocs gh-deploy --force
-    ```  
+    ```
+  - Then update your Markdown files in MkDocs as normal, execute commands such as mkdocs build or directly git add, commit, and push
+    - Make sure you have installed python3 ahead of time and set environment variables
+- Priority of time reads:
+  - `Front Matter` > `Cache file` > `Filesystem timestamp`
+- If you are using MkDocs on a Linux system, the modification time is used as the creation time because of system limitations. If you need the exact creation time, you can specify it manually in Front Matter

mkdocs_document_dates-2.3.1/mkdocs_document_dates/__init__.py

@@ -0,0 +1,13 @@
+"""MkDocs Document Dates Plugin."""
+
+__version__ = '2.3.1'
+
+from .hooks_installer import install
+
+# 在包被导入时自动执行 hooks 安装
+try:
+    result = install()
+    if not result:
+        print("Tip: Git hooks installation was skipped (probably because Git was not detected or not in the Git repository)")
+except Exception as e:
+    print(f"Warning: Git hooks installation failed: {e}")

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/hooks/pre-commit

@@ -9,25 +9,23 @@ from datetime import datetime
 from pathlib import Path
 
 def find_mkdocs_projects():
-    """查找当前 git 仓库中的所有 MkDocs 项目"""
     try:
         git_root = Path(subprocess.check_output(
             ['git', 'rev-parse', '--show-toplevel'],
             text=True, encoding='utf-8'
         ).strip())
-        
+
         projects = []
         for config_file in git_root.rglob('mkdocs.y*ml'):
             if config_file.name.lower() in ('mkdocs.yml', 'mkdocs.yaml'):
                 projects.append(config_file.parent)
-        
+
         return projects
     except subprocess.CalledProcessError as e:
-        print(f"查找 Git 仓库根目录失败: {e}", file=sys.stderr)
+        print(f"Failed to find the Git repository root: {e}", file=sys.stderr)
         return []
 
 def get_file_dates(file_path):
-    """获取文件的创建和修改时间"""
     try:
         stat = os.stat(file_path)
         modified = datetime.fromtimestamp(stat.st_mtime)
@@ -49,12 +47,10 @@ def get_file_dates(file_path):
         return current_time.isoformat(), current_time.isoformat()
 
 def update_dates_cache():
-    """更新文档时间缓存"""
-    print("开始更新文档时间缓存...")
     for project_dir in find_mkdocs_projects():
         docs_dir = project_dir / 'docs'
         if not docs_dir.exists():
-            print(f"文档目录不存在: {docs_dir}")
+            print(f"Document directory does not exist: {docs_dir}")
             continue
 
         dates_cache = {}
@@ -69,25 +65,24 @@ def update_dates_cache():
                     "modified": modified
                 }
             except Exception as e:
-                print(f"处理文件 {md_file} 时出错: {e}")
+                print(f"Error processing file {md_file}: {e}")
 
         if not dates_cache:
             continue
 
         cache_file = docs_dir / '.dates_cache.json'
-        print(f"正在写入缓存文件: {cache_file}")
         try:
             with open(cache_file, "w") as f:
                 json.dump(dates_cache, f, indent=2, ensure_ascii=False)
             subprocess.run(["git", "add", str(cache_file)], check=True)
-            print(f"缓存文件 {cache_file} 已更新.")
+            # print(f"The cache file {cache_file} has been updated")
         except Exception as e:
-            print(f"写入缓存文件时出错: {e}", file=sys.stderr)
+            print(f"Error writing to cache file: {e}", file=sys.stderr)
             raise
 
 if __name__ == "__main__":
     try:
         update_dates_cache()
     except Exception as e:
-        print(f"Hook 执行出错: {e}", file=sys.stderr)
+        print(f"Hook execution error: {e}", file=sys.stderr)
         sys.exit(1)

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/hooks_installer.py

@@ -6,21 +6,18 @@ from pathlib import Path
 import platform
 
 def get_config_dir():
-    """获取用户配置目录"""
-    system = platform.system().lower()
-    if system.startswith('win'):
+    if platform.system().lower().startswith('win'):
         return Path(os.getenv('APPDATA', str(Path.home() / 'AppData' / 'Roaming')))
-    else:  # macOS 和 Linux 统一使用 ~/.config
+    else:
         return Path.home() / '.config'
 
 def install():
-    """安装 git hooks"""
     try:
         # 检查 git 是否可用
         try:
             subprocess.run(['git', '--version'], check=True, capture_output=True, encoding='utf-8')
         except (subprocess.CalledProcessError, FileNotFoundError):
-            print("提示: 未检测到 Git，跳过 hooks 安装")
+            print("Tip: Git not detected, skip hooks installation")
             return False
         
         # 准备配置目录
@@ -28,49 +25,48 @@ def install():
         try:
             config_dir.mkdir(parents=True, exist_ok=True)
         except PermissionError:
-            print(f"错误: 无权限创建目录: {config_dir}")
+            print(f"Error: No permission to create directory: {config_dir}")
             return False
         except Exception as e:
-            print(f"错误: 创建目录失败: {config_dir}, 原因: {e}")
+            print(f"Error: Failed to create directory: {config_dir}, reason: {e}")
             return False
 
         hook_path = config_dir / 'pre-commit'
 
-        # 复制 hook 文件
+        # 复制 hook 文件到配置目录
         source_hook = Path(__file__).parent / 'hooks' / 'pre-commit'
         if not source_hook.exists():
-            print(f"错误: 源 hook 文件不存在: {source_hook}")
+            print(f"Error: Source hook file does not exist: {source_hook}")
             return False
-            
+
         try:
             shutil.copy2(source_hook, hook_path)
         except PermissionError:
-            print(f"错误: 无权限复制文件到: {hook_path}")
+            print(f"Error: No permission to copy file to: {hook_path}")
             return False
         except Exception as e:
-            print(f"错误: 复制文件失败, 原因: {e}")
+            print(f"Error: Failed to copy file, reason: {e}")
             return False
 
-        # 设置文件权限（Unix-like 系统）
-        if not platform.system().lower().startswith('win'):
-            try:
-                os.chmod(config_dir, 0o755)
-                os.chmod(hook_path, 0o755)
-            except OSError as e:
-                print(f"警告: 设置权限时出错: {e}")
+        # 设置文件权限
+        try:
+            os.chmod(config_dir, 0o755)
+            os.chmod(hook_path, 0o755)
+        except OSError as e:
+            print(f"Warning: Error setting permissions: {e}")
 
-        # 配置 git hooks 路径
+        # 配置全局 git hooks 路径
         try:
             subprocess.run(['git', 'config', '--global', 'core.hooksPath', 
                           str(config_dir)], check=True, encoding='utf-8')
-            print(f"Git hooks 已安装到: {config_dir}")
+            # print(f"Git hooks are installed in the: {config_dir}")
             return True
         except subprocess.CalledProcessError as e:
-            print(f"错误: 设置 git hooks 路径失败: {e}")
+            print(f"Error: Setting git hooks path failed: {e}")
             return False
             
     except Exception as e:
-        print(f"安装 hooks 时出错: {e}")
+        print(f"Error installing hooks: {e}")
         return False
 
 if __name__ == '__main__':

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/__init__.py

@@ -2,7 +2,6 @@ from pathlib import Path
 import importlib.util
 
 def load_translations():
-    """加载所有可用的翻译"""
     translations = {}
     translations_dir = Path(__file__).parent
     

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/ar.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'الآن',
     'seconds_ago': 'منذ {} ثانية',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/de.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'gerade jetzt',
     'seconds_ago': 'vor {} Sekunden',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/en.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'just now',
     'seconds_ago': '{} seconds ago',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/es.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'justo ahora',
     'seconds_ago': 'hace {} segundos',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/fr.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'à l\'instant',
     'seconds_ago': 'il y a {} secondes',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/ja.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'たった今',
     'seconds_ago': '{} 秒前',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/ko.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': '방금',
     'seconds_ago': '{} 초 전',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/ru.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': 'только что',
     'seconds_ago': '{} секунд назад',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/zh.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': '刚刚',
     'seconds_ago': '{} 秒前',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/zh_tw.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 translations = {
     'just_now': '剛剛',
     'seconds_ago': '{} 秒前',

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/plugin.py

@@ -23,11 +23,9 @@ class DocumentDatesPlugin(BasePlugin):
         self.translations = load_translations()
 
     def _get_css_content(self):
-        """返回插件的 CSS 样式"""
         return DOCUMENT_DATES_CSS
 
     def on_config(self, config):
-        """配置插件并添加必要的 CSS"""
         if 'extra_css' not in config:
             config['extra_css'] = []
         
@@ -45,8 +43,6 @@ class DocumentDatesPlugin(BasePlugin):
         return config
 
     def _get_date_info(self, created, modified):
-        """格式化日期信息的 HTML"""
-        # 获取翻译字典
         locale = self.config['locale']
         if locale not in self.translations:
             locale = 'en'
@@ -64,7 +60,6 @@ class DocumentDatesPlugin(BasePlugin):
         )
 
     def _insert_date_info(self, markdown, date_info):
-        """根据配置将日期信息插入到合适的位置"""
         if not markdown.strip():
             return markdown
             
@@ -78,14 +73,13 @@ class DocumentDatesPlugin(BasePlugin):
         return f"{markdown}\n\n{date_info}"
 
     def on_page_markdown(self, markdown, page, config, files):
-        """处理页面内容，添加日期信息"""
         file_path = Path(page.file.abs_src_path)
         
         if self._is_excluded(file_path, Path(config['docs_dir'])):
             return markdown
         
         # 获取文件时间
-        created, modified = self._get_file_dates(file_path, config)  # 传入 config
+        created, modified = self._get_file_dates(file_path, config)
         
         # 处理 front matter 中的时间
         created, modified = self._process_meta_dates(page.meta, created, modified)
@@ -97,19 +91,12 @@ class DocumentDatesPlugin(BasePlugin):
         return self._insert_date_info(markdown, date_info)
 
     def _is_excluded(self, file_path: Path, docs_dir: Path) -> bool:
-        """检查文件是否在排除列表中"""
         for pattern in self.config['exclude']:
             if self._matches_exclude_pattern(file_path, docs_dir, pattern):
                 return True
         return False
 
     def _matches_exclude_pattern(self, file_path: Path, docs_dir: Path, pattern: str) -> bool:
-        """检查文件是否匹配排除模式
-        支持三种匹配模式：
-        1. 具体文件路径：支持多级目录，如 'private/temp.md'
-        2. 目录下所有文件：使用 '*' 通配符，如 'private/*'，匹配包含子目录的所有文件
-        3. 指定目录下特定类型文件：如 'private/*.md'，仅匹配当前目录下的特定类型文件
-        """
         try:
             # 获取相对于 docs_dir 的路径
             rel_path = file_path.relative_to(docs_dir)
@@ -136,13 +123,11 @@ class DocumentDatesPlugin(BasePlugin):
             return False
 
     def _process_meta_dates(self, meta: dict, created: datetime, modified: datetime) -> tuple[datetime, datetime]:
-        """处理 frontmatter 中的日期"""
         result_created = self._parse_meta_date(meta.get('created'), created)
         result_modified = self._parse_meta_date(meta.get('modified'), modified)
         return result_created, result_modified
 
     def _parse_meta_date(self, date_str: str | None, default_date: datetime) -> datetime:
-        """解析 meta 中的日期字符串"""
         if not date_str:
             return default_date
 
@@ -151,10 +136,8 @@ class DocumentDatesPlugin(BasePlugin):
         except (ValueError, TypeError):
             return default_date
 
-    def _get_file_dates(self, file_path, config):  # 添加 config 参数
-        """获取文件的创建时间和修改时间"""
+    def _get_file_dates(self, file_path, config):
         try:
-            # 从传入的 config 中获取 docs_dir
             docs_dir = Path(config['docs_dir'])
             rel_path = str(Path(file_path).relative_to(docs_dir))
             
@@ -172,16 +155,16 @@ class DocumentDatesPlugin(BasePlugin):
             # 如果缓存不存在或文件不在缓存中，使用文件系统时间
             stat = os.stat(file_path)
             modified = datetime.fromtimestamp(stat.st_mtime)
-            
+
             system = platform.system().lower()
-            if system == 'darwin':  # macOS
+            if system.startswith('win'):  # Windows
+                created = datetime.fromtimestamp(stat.st_ctime)
+            elif system == 'darwin':  # macOS
                 try:
                     created = datetime.fromtimestamp(stat.st_birthtime)
                 except AttributeError:
                     created = datetime.fromtimestamp(stat.st_ctime)
-            elif system == 'windows':  # Windows
-                created = datetime.fromtimestamp(stat.st_ctime)
-            else:  # Linux 和其他系统
+            else:  # Linux
                 created = modified
 
             return created, modified
@@ -191,7 +174,6 @@ class DocumentDatesPlugin(BasePlugin):
             return current_time, current_time
 
     def _get_timeago(self, date):
-        """将日期格式化为 timeago 格式"""
         now = datetime.now()
         diff = now - date
         seconds = diff.total_seconds()
@@ -233,7 +215,6 @@ class DocumentDatesPlugin(BasePlugin):
             return t['years_ago'].format(int(seconds / 31536000))
 
     def _get_formatted_date(self, date):
-        """格式化日期，支持 timeago、date 和 datetime 格式"""
         if self.config['type'] == 'timeago':
             return self._get_timeago(date)
         elif self.config['type'] == 'datetime':

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/styles.py

@@ -1,4 +1,3 @@
-"""CSS 样式定义"""
 
 DOCUMENT_DATES_CSS = """
 .document-dates-plugin {

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.2
 Name: mkdocs-document-dates
-Version: 2.2.0
+Version: 2.3.1
 Summary: A MkDocs plugin for displaying accurate document creation and last modification dates.
 Home-page: https://github.com/jaywhj/mkdocs-document-dates
 Author: Aaron Wang
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mkdocs>=1.0.0
@@ -26,12 +26,12 @@ English | [简体中文](README_zh.md)
 
 
 
-A MkDocs plugin for displaying **accurate** document creation and last modification dates.
+A MkDocs plugin for displaying <mark>accurate</mark> document creation and last modification dates.
 
 ## Features
 
 - Automatically displays document creation and last modification times
-- No Git dependency, uses filesystem timestamps directly
+- **No Git dependency**, uses filesystem timestamps directly
 - Supports manual date specification in `Front Matter`
 - Cross-platform support (Windows, macOS, Linux)
 - Support for multiple time formats (date, datetime, timeago)
@@ -40,6 +40,7 @@ A MkDocs plugin for displaying **accurate** document creation and last modificat
 - Material Design icons, Elegant styling
 - Lightweight with no extra dependencies
 - Multi-language support
+- Support for CI/CD build systems (e.g. Github Actions)
 
 ## Installation
 
@@ -79,7 +80,7 @@ You can also manually specify the date of a Markdown document in its `Front Matt
 ```yaml
 ---
 created: 2023-01-01
-modified: 2023-12-31
+modified: 2025-02-23
 ---
 
 # Document Title
@@ -89,33 +90,35 @@ modified: 2023-12-31
 
 ## Configuration Options
 
-- `type` : Date type (default: `date` )
+- **type** : Date type (default: `date` )
   - `date` : Display date only
   - `datetime` : Display date and time
   - `timeago` : Display relative time (e.g., 2 minutes ago)
-- `locale` : Localization (default: `en` )
+- **locale** : Localization (default: `en` )
   - Supports: `zh zh_tw en es fr de ar ja ko ru`
-- `date_format` : Date format (default: `%Y-%m-%d`)
+- **date_format** : Date format (default: `%Y-%m-%d`)
   - Supports all Python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc.
-- `time_format` : Time format (default: `%H:%M:%S`)
-- `position` : Display position (default: `bottom`)
+- **time_format** : Time format (default: `%H:%M:%S`)
+- **position** : Display position (default: `bottom`)
   - `top` : Display after the first heading
   - `bottom` : Display at the end of the document
-- `exclude` : File exclusion list (default: [] )
+- **exclude** : File exclusion list (default: [] )
   - Supports glob patterns, e.g., ["private/\*", "temp.md", "drafts/\*.md"]
 
 ## Notes
 
-- Creation time behavior varies across operating systems:
-  - Windows: Uses file creation time
-  - macOS: Uses file creation time (birthtime)
-  - Linux: Uses modification time as creation time due to system limitations, if you need the exact creation time, you can manually specify it in Front Matter
 - It still works when using CI/CD build systems (e.g. Github Actions)
   - Used a cache file `.dates_cache.json` to solve this problem
-  - You can configure it like this:
+  - You can configure it like this in your .github/workflows/ci.yml:
+    
     ```
     ...
     
       - run: pip install mkdocs-document-dates
       - run: mkdocs gh-deploy --force
-    ```  
+    ```
+  - Then update your Markdown files in MkDocs as normal, execute commands such as mkdocs build or directly git add, commit, and push
+    - Make sure you have installed python3 ahead of time and set environment variables
+- Priority of time reads:
+  - `Front Matter` > `Cache file` > `Filesystem timestamp`
+- If you are using MkDocs on a Linux system, the modification time is used as the creation time because of system limitations. If you need the exact creation time, you can specify it manually in Front Matter

{mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/setup.py

@@ -7,7 +7,7 @@ try:
 except FileNotFoundError:
     long_description = "A MkDocs plugin for displaying accurate document creation and last modification dates."
 
-VERSION = '2.2.0'
+VERSION = '2.3.1'
 
 setup(
     name="mkdocs-document-dates",
@@ -31,12 +31,12 @@ setup(
             'document-dates = mkdocs_document_dates.plugin:DocumentDatesPlugin',
         ],
         'console_scripts': [
-            # 提供命令行工具，允许用户手动执行 hooks 安装
+            # 提供手动执行 hooks 安装的入口
             'mkdocs-document-dates-hooks=mkdocs_document_dates.hooks_installer:install'
         ],
     },
     package_data={
         'mkdocs_document_dates': ['hooks/*'],
     },
-    python_requires=">=3.6",
+    python_requires=">=3.7",
 )

mkdocs_document_dates-2.2.0/mkdocs_document_dates/__init__.py

@@ -1,13 +0,0 @@
-"""MkDocs Document Dates Plugin."""
-
-__version__ = '2.0.0'
-
-from .hooks_installer import install
-
-# 在包被导入时自动执行 hooks 安装
-try:
-    result = install()
-    if not result:
-        print("提示: Git hooks 安装被跳过（可能是因为未检测到 Git 或不在 Git 仓库中）")
-except Exception as e:
-    print(f"警告: Git hooks 安装失败: {e}")