mkdocs-document-dates 0.4.0__tar.gz → 0.5.0__tar.gz

{mkdocs_document_dates-0.4.0 → mkdocs_document_dates-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: mkdocs-document-dates
-Version: 0.4.0
+Version: 0.5.0
 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
@@ -31,15 +31,15 @@ A MkDocs plugin for displaying **accurate** document creation and last modificat
 ## Features
 
 - Automatically displays document creation and last modification times
-- Supports manual date specification in `Front Matter`
 - No Git dependency, uses filesystem timestamps directly
+- Supports manual date specification in `Front Matter`
 - Cross-platform support (Windows, macOS, Linux)
-- Configurable date and time formats
+- Configurable time display formats (supports date, time, and relative time)
 - Flexible display position (top or bottom)
 - File exclusion rules support
-- Material Design icons
-- Elegant styling
+- Material Design icons, Elegant styling
 - Lightweight with no extra dependencies
+- Multi-language support
 
 ## Installation
 
@@ -49,7 +49,7 @@ pip install mkdocs-document-dates
 
 ## Configuration
 
-Add the plugin to your mkdocs.yml:
+Just add the plugin to your mkdocs.yml:
 
 ```yaml
 plugins:
@@ -61,15 +61,15 @@ Or, customize the configuration:
 ```yaml
 plugins:
   - document-dates:
-      date_format: '%Y-%m-%d'    # Date format
-      show_time: false           # Whether to show time
-      time_format: '%H:%M:%S'    # Time format
-      position: bottom           # Display position: top (after title) or bottom (end of document)
-      exclude:                   # List of file patterns to exclude
-        - "private/*"            # Exclude all files in private directory, including subdirectories
-        - "drafts/*.md"         # Exclude all markdown files in drafts directory
-        - "temp.md"             # Exclude specific file
-        - "*.tmp"               # Exclude all files with .tmp extension
+      type: date               # Date type: date | datetime | timeago, default: date
+      locale: en               # Localization: zh zh_tw en es fr de ar ja ko ru, default: en
+      date_format: '%Y-%m-%d'  # Date format
+      time_format: '%H:%M:%S'  # Time format
+      position: bottom         # Display position: top (after title) | bottom (end of document), default: bottom
+      exclude:                 # List of file patterns to exclude
+        - temp.md              # Exclude specific file
+        - private/*            # Exclude all files in private directory, including subdirectories
+        - drafts/*.md          # Exclude all markdown files in the current directory drafts, but not subdirectories
 ```
 
 ## Manual Date Specification
@@ -85,20 +85,24 @@ modified_date: 2023-12-31
 # Document Title
 ```
 
+
+
 ## Configuration Options
 
-- `date_format`: Date format (default: %Y-%m-%d)
-  - Supports all Python datetime format strings, examples: %Y-%m-%d, %b %d, %Y, etc.
-- `show_time`: Whether to show time (default: false)
-  - true: Show both date and time
-  - false: Show date only
-- `time_format`: Time format (default: %H:%M:%S)
-  - Only effective when show_time is true
-- `position`: Display position (default: bottom)
-  - top: Display after the first heading
-  - bottom: Display at the end of document
-- `exclude`: List of files to exclude (default: [])
-  - Supports glob patterns, example: ["private/*", "temp.md"]
+- `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` )
+  - Supports: `zh zh_tw en es fr de ar ja ko ru`
+- `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`)
+  - `top` : Display after the first heading
+  - `bottom` : Display at the end of the document
+- `exclude` : File exclusion list (default: [] )
+  - Supports glob patterns, e.g., ["private/\*", "temp.md", "drafts/\*.md"]
 
 ## Notes
 
@@ -106,5 +110,5 @@ modified_date: 2023-12-31
   - Windows: Uses file creation time
   - macOS: Uses file creation time (birthtime)
   - Linux: Uses modification time as creation time due to system limitations
-- For accurate creation times, it's recommended to use Front Matter for manual specification
+- For accurate creation times, it's recommended to specify dates manually in Front Matter
 

mkdocs_document_dates-0.5.0/README.md

@@ -0,0 +1,92 @@
+# mkdocs-document-dates
+
+English | [简体中文](README_zh.md)
+
+
+
+A MkDocs plugin for displaying **accurate** document creation and last modification dates.
+
+## Features
+
+- Automatically displays document creation and last modification times
+- No Git dependency, uses filesystem timestamps directly
+- Supports manual date specification in `Front Matter`
+- Cross-platform support (Windows, macOS, Linux)
+- Configurable time display formats (supports date, time, and relative time)
+- Flexible display position (top or bottom)
+- File exclusion rules support
+- Material Design icons, Elegant styling
+- Lightweight with no extra dependencies
+- Multi-language support
+
+## Installation
+
+```bash
+pip install mkdocs-document-dates
+```
+
+## Configuration
+
+Just add the plugin to your mkdocs.yml:
+
+```yaml
+plugins:
+  - document-dates
+```
+
+Or, customize the configuration:
+
+```yaml
+plugins:
+  - document-dates:
+      type: date               # Date type: date | datetime | timeago, default: date
+      locale: en               # Localization: zh zh_tw en es fr de ar ja ko ru, default: en
+      date_format: '%Y-%m-%d'  # Date format
+      time_format: '%H:%M:%S'  # Time format
+      position: bottom         # Display position: top (after title) | bottom (end of document), default: bottom
+      exclude:                 # List of file patterns to exclude
+        - temp.md              # Exclude specific file
+        - private/*            # Exclude all files in private directory, including subdirectories
+        - drafts/*.md          # Exclude all markdown files in the current directory drafts, but not subdirectories
+```
+
+## Manual Date Specification
+
+You can also manually specify the date of a Markdown document in its `Front Matter` :
+
+```yaml
+---
+created_date: 2023-01-01
+modified_date: 2023-12-31
+---
+
+# Document Title
+```
+
+
+
+## Configuration Options
+
+- `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` )
+  - Supports: `zh zh_tw en es fr de ar ja ko ru`
+- `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`)
+  - `top` : Display after the first heading
+  - `bottom` : Display at the end of the document
+- `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
+- For accurate creation times, it's recommended to specify dates manually in Front Matter
+

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/__init__.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+import importlib.util
+
+def load_translations():
+    """加载所有可用的翻译"""
+    translations = {}
+    translations_dir = Path(__file__).parent
+    
+    for lang_file in translations_dir.glob('*.py'):
+        if lang_file.stem == '__init__':
+            continue
+            
+        spec = importlib.util.spec_from_file_location(
+            f"translations.{lang_file.stem}",
+            lang_file
+        )
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        
+        if hasattr(module, 'translations'):
+            translations[lang_file.stem] = module.translations
+            
+    return translations

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/ar.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': 'الآن',
+    'seconds_ago': 'منذ {} ثانية',
+    'minute_ago': 'منذ دقيقة',
+    'minutes_ago': 'منذ {} دقيقة',
+    'hour_ago': 'منذ ساعة',
+    'hours_ago': 'منذ {} ساعة',
+    'day_ago': 'منذ يوم',
+    'days_ago': 'منذ {} يوم',
+    'week_ago': 'منذ أسبوع',
+    'weeks_ago': 'منذ {} أسبوع',
+    'month_ago': 'منذ شهر',
+    'months_ago': 'منذ {} شهر',
+    'year_ago': 'منذ سنة',
+    'years_ago': 'منذ {} سنة',
+    'created_time': 'تاريخ الإنشاء',
+    'modified_time': 'تاريخ التعديل',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/de.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': 'gerade jetzt',
+    'seconds_ago': 'vor {} Sekunden',
+    'minute_ago': 'vor einer Minute',
+    'minutes_ago': 'vor {} Minuten',
+    'hour_ago': 'vor einer Stunde',
+    'hours_ago': 'vor {} Stunden',
+    'day_ago': 'vor einem Tag',
+    'days_ago': 'vor {} Tagen',
+    'week_ago': 'vor einer Woche',
+    'weeks_ago': 'vor {} Wochen',
+    'month_ago': 'vor einem Monat',
+    'months_ago': 'vor {} Monaten',
+    'year_ago': 'vor einem Jahr',
+    'years_ago': 'vor {} Jahren',
+    'created_time': 'Erstellungszeit',
+    'modified_time': 'Änderungszeit',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/en.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': 'just now',
+    'seconds_ago': '{} seconds ago',
+    'minute_ago': '1 minute ago',
+    'minutes_ago': '{} minutes ago',
+    'hour_ago': '1 hour ago',
+    'hours_ago': '{} hours ago',
+    'day_ago': '1 day ago',
+    'days_ago': '{} days ago',
+    'week_ago': '1 week ago',
+    'weeks_ago': '{} weeks ago',
+    'month_ago': '1 month ago',
+    'months_ago': '{} months ago',
+    'year_ago': '1 year ago',
+    'years_ago': '{} years ago',
+    'created_time': 'Created Time',
+    'modified_time': 'Last Update',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/es.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': 'justo ahora',
+    'seconds_ago': 'hace {} segundos',
+    'minute_ago': 'hace un minuto',
+    'minutes_ago': 'hace {} minutos',
+    'hour_ago': 'hace una hora',
+    'hours_ago': 'hace {} horas',
+    'day_ago': 'hace un día',
+    'days_ago': 'hace {} días',
+    'week_ago': 'hace una semana',
+    'weeks_ago': 'hace {} semanas',
+    'month_ago': 'hace un mes',
+    'months_ago': 'hace {} meses',
+    'year_ago': 'hace un año',
+    'years_ago': 'hace {} años',
+    'created_time': 'Fecha de creación',
+    'modified_time': 'Fecha de modificación',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/fr.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': 'à l\'instant',
+    'seconds_ago': 'il y a {} secondes',
+    'minute_ago': 'il y a une minute',
+    'minutes_ago': 'il y a {} minutes',
+    'hour_ago': 'il y a une heure',
+    'hours_ago': 'il y a {} heures',
+    'day_ago': 'il y a un jour',
+    'days_ago': 'il y a {} jours',
+    'week_ago': 'il y a une semaine',
+    'weeks_ago': 'il y a {} semaines',
+    'month_ago': 'il y a un mois',
+    'months_ago': 'il y a {} mois',
+    'year_ago': 'il y a un an',
+    'years_ago': 'il y a {} ans',
+    'created_time': 'Date de création',
+    'modified_time': 'Date de modification',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/ja.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': 'たった今',
+    'seconds_ago': '{} 秒前',
+    'minute_ago': '1 分前',
+    'minutes_ago': '{} 分前',
+    'hour_ago': '1 時間前',
+    'hours_ago': '{} 時間前',
+    'day_ago': '1 日前',
+    'days_ago': '{} 日前',
+    'week_ago': '1 週間前',
+    'weeks_ago': '{} 週間前',
+    'month_ago': '1 ヶ月前',
+    'months_ago': '{} ヶ月前',
+    'year_ago': '1 年前',
+    'years_ago': '{} 年前',
+    'created_time': '作成日時',
+    'modified_time': '更新日時',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/ko.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': '방금',
+    'seconds_ago': '{} 초 전',
+    'minute_ago': '1 분 전',
+    'minutes_ago': '{} 분 전',
+    'hour_ago': '1 시간 전',
+    'hours_ago': '{} 시간 전',
+    'day_ago': '1 일 전',
+    'days_ago': '{} 일 전',
+    'week_ago': '1 주 전',
+    'weeks_ago': '{} 주 전',
+    'month_ago': '1 개월 전',
+    'months_ago': '{} 개월 전',
+    'year_ago': '1 년 전',
+    'years_ago': '{} 년 전',
+    'created_time': '작성일',
+    'modified_time': '수정일',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/ru.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': 'только что',
+    'seconds_ago': '{} секунд назад',
+    'minute_ago': 'минуту назад',
+    'minutes_ago': '{} минут назад',
+    'hour_ago': 'час назад',
+    'hours_ago': '{} часов назад',
+    'day_ago': 'день назад',
+    'days_ago': '{} дней назад',
+    'week_ago': 'неделю назад',
+    'weeks_ago': '{} недель назад',
+    'month_ago': 'месяц назад',
+    'months_ago': '{} месяцев назад',
+    'year_ago': 'год назад',
+    'years_ago': '{} лет назад',
+    'created_time': 'Дата создания',
+    'modified_time': 'Дата изменения',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/zh.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': '刚刚',
+    'seconds_ago': '{} 秒前',
+    'minute_ago': '1 分钟前',
+    'minutes_ago': '{} 分钟前',
+    'hour_ago': '1 小时前',
+    'hours_ago': '{} 小时前',
+    'day_ago': '1 天前',
+    'days_ago': '{} 天前',
+    'week_ago': '1 周前',
+    'weeks_ago': '{} 周前',
+    'month_ago': '1 个月前',
+    'months_ago': '{} 个月前',
+    'year_ago': '1 年前',
+    'years_ago': '{} 年前',
+    'created_time': '创建时间',
+    'modified_time': '最后更新',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/lang/zh_tw.py

@@ -0,0 +1,18 @@
+translations = {
+    'just_now': '剛剛',
+    'seconds_ago': '{} 秒前',
+    'minute_ago': '1 分鐘前',
+    'minutes_ago': '{} 分鐘前',
+    'hour_ago': '1 小時前',
+    'hours_ago': '{} 小時前',
+    'day_ago': '1 天前',
+    'days_ago': '{} 天前',
+    'week_ago': '1 週前',
+    'weeks_ago': '{} 週前',
+    'month_ago': '1 個月前',
+    'months_ago': '{} 個月前',
+    'year_ago': '1 年前',
+    'years_ago': '{} 年前',
+    'created_time': '建立時間',
+    'modified_time': '修改時間',
+}

mkdocs_document_dates-0.5.0/mkdocs_document_dates/plugin.py

@@ -0,0 +1,219 @@
+import os
+import platform
+from datetime import datetime
+from pathlib import Path
+from mkdocs.plugins import BasePlugin
+from mkdocs.config import config_options
+from .lang import load_translations
+from .styles import DOCUMENT_DATES_CSS
+
+class DocumentDatesPlugin(BasePlugin):
+    config_scheme = (
+        ('type', config_options.Type(str, default='date')),
+        ('locale', config_options.Type(str, default='en')),
+        ('date_format', config_options.Type(str, default='%Y-%m-%d')),
+        ('time_format', config_options.Type(str, default='%H:%M:%S')),
+        ('position', config_options.Type(str, default='bottom')),
+        ('exclude', config_options.Type(list, default=[])),
+    )
+
+    def __init__(self):
+        super().__init__()
+        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'] = []
+        
+        # 添加 Material Icons
+        material_icons_url = 'https://fonts.googleapis.com/icon?family=Material+Icons'
+        if material_icons_url not in config['extra_css']:
+            config['extra_css'].append(material_icons_url)
+        
+        # 添加自定义 CSS
+        css_file = Path(config['docs_dir']) / 'assets' / 'document_dates.css'
+        css_file.parent.mkdir(parents=True, exist_ok=True)
+        css_file.write_text(self._get_css_content())
+        config['extra_css'].append('assets/document_dates.css')
+        
+        return config
+
+    def _get_date_info(self, created, modified):
+        """格式化日期信息的 HTML"""
+        # 获取翻译字典
+        locale = self.config['locale']
+        if locale not in self.translations:
+            locale = 'en'
+        t = self.translations[locale]
+        
+        return (
+            f"<div class='document-dates-plugin-wrapper'>"
+            f"<div class='document-dates-plugin'>"
+            f"<span title='{t['created_time']}'><span class='material-icons'>add_circle</span>"
+            f"{self._get_formatted_date(created)}</span>"
+            f"<span title='{t['modified_time']}'><span class='material-icons'>update</span>"
+            f"{self._get_formatted_date(modified)}</span>"
+            f"</div>"
+            f"</div>"
+        )
+
+    def _insert_date_info(self, markdown, date_info):
+        """根据配置将日期信息插入到合适的位置"""
+        if not markdown.strip():
+            return markdown
+            
+        if self.config['position'] == 'top':
+            lines = markdown.splitlines()
+            for i, line in enumerate(lines):
+                if line.startswith('#'):
+                    lines.insert(i + 1, date_info)
+                    return '\n'.join(lines)
+            return f"{date_info}\n{markdown}"
+        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)
+        created, modified = self._process_meta_dates(page.meta, created, modified)
+        
+        date_info = self._get_date_info(created, modified)
+        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)
+            pattern_path = Path(pattern)
+
+            # 情况1：匹配具体文件路径
+            if '*' not in pattern:
+                return str(rel_path) == pattern
+
+            # 情况2：匹配目录下所有文件（包含子目录）
+            if pattern.endswith('/*'):
+                base_dir = pattern[:-2]
+                return str(rel_path).startswith(f"{base_dir}/")
+
+            # 情况3：匹配指定目录下的特定类型文件（不包含子目录）
+            if '*.' in pattern:
+                pattern_dir = pattern_path.parent
+                pattern_suffix = pattern_path.name[1:]  # 去掉 * 号
+                return (rel_path.parent == Path(pattern_dir) and 
+                       rel_path.name.endswith(pattern_suffix))
+
+            return False
+        except ValueError:
+            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_date'), created)
+        result_modified = self._parse_meta_date(meta.get('modified_date'), 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
+
+        try:
+            return datetime.fromisoformat(str(date_str).strip("'\""))
+        except (ValueError, TypeError):
+            return default_date
+
+    def _get_file_dates(self, file_path):
+        """获取文件的创建时间和修改时间"""
+        try:
+            stat = os.stat(file_path)
+            modified = datetime.fromtimestamp(stat.st_mtime)
+
+            system = platform.system().lower()
+            if 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 和其他系统
+                # Linux 没有可靠的创建时间，使用修改时间作为创建时间
+                created = modified
+
+            return created, modified
+        except (OSError, ValueError) as e:
+            # 添加错误处理，确保即使文件访问出错也能正常工作
+            current_time = datetime.now()
+            return current_time, current_time
+
+    def _get_timeago(self, date):
+        """将日期格式化为 timeago 格式"""
+        now = datetime.now()
+        diff = now - date
+        seconds = diff.total_seconds()
+        
+        # 获取翻译字典
+        locale = self.config['locale']
+        if locale not in self.translations:
+            locale = 'en'
+        t = self.translations[locale]
+        
+        # 时间间隔判断
+        if seconds < 10:
+            return t['just_now']
+        elif seconds < 60:
+            return t['seconds_ago'].format(int(seconds))
+        elif seconds < 120:
+            return t['minute_ago']
+        elif seconds < 3600:
+            return t['minutes_ago'].format(int(seconds / 60))
+        elif seconds < 7200:
+            return t['hour_ago']
+        elif seconds < 86400:
+            return t['hours_ago'].format(int(seconds / 3600))
+        elif seconds < 172800:
+            return t['day_ago']
+        elif seconds < 604800:
+            return t['days_ago'].format(int(seconds / 86400))
+        elif seconds < 1209600:
+            return t['week_ago']
+        elif seconds < 2592000:
+            return t['weeks_ago'].format(int(seconds / 604800))
+        elif seconds < 5184000:
+            return t['month_ago']
+        elif seconds < 31536000:
+            return t['months_ago'].format(int(seconds / 2592000))
+        elif seconds < 63072000:
+            return t['year_ago']
+        else:
+            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':
+            return date.strftime(f"{self.config['date_format']} {self.config['time_format']}")
+        return date.strftime(self.config['date_format'])

mkdocs_document_dates-0.5.0/mkdocs_document_dates/styles.py

@@ -0,0 +1,28 @@
+"""CSS 样式定义"""
+
+DOCUMENT_DATES_CSS = """
+.document-dates-plugin {
+    color: #8e8e8e;
+    font-size: 0.75rem;
+    padding: 0.2rem 0;
+    opacity: 0.8;
+    display: flex;
+    gap: 1.5rem;
+    align-items: center;
+    margin-bottom: 0.3rem;
+}
+.document-dates-plugin span {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.3rem;
+}
+.document-dates-plugin .material-icons {
+    font-size: 0.9rem;
+    opacity: 0.7;
+}
+.document-dates-plugin-wrapper {
+    margin: 0.3rem 0 1rem 0;
+    border-bottom: 1px solid rgba(0, 0, 0, 0.07);
+    padding-bottom: 0.5rem;
+}
+"""

{mkdocs_document_dates-0.4.0 → mkdocs_document_dates-0.5.0}/mkdocs_document_dates.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: mkdocs-document-dates
-Version: 0.4.0
+Version: 0.5.0
 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
@@ -31,15 +31,15 @@ A MkDocs plugin for displaying **accurate** document creation and last modificat
 ## Features
 
 - Automatically displays document creation and last modification times
-- Supports manual date specification in `Front Matter`
 - No Git dependency, uses filesystem timestamps directly
+- Supports manual date specification in `Front Matter`
 - Cross-platform support (Windows, macOS, Linux)
-- Configurable date and time formats
+- Configurable time display formats (supports date, time, and relative time)
 - Flexible display position (top or bottom)
 - File exclusion rules support
-- Material Design icons
-- Elegant styling
+- Material Design icons, Elegant styling
 - Lightweight with no extra dependencies
+- Multi-language support
 
 ## Installation
 
@@ -49,7 +49,7 @@ pip install mkdocs-document-dates
 
 ## Configuration
 
-Add the plugin to your mkdocs.yml:
+Just add the plugin to your mkdocs.yml:
 
 ```yaml
 plugins:
@@ -61,15 +61,15 @@ Or, customize the configuration:
 ```yaml
 plugins:
   - document-dates:
-      date_format: '%Y-%m-%d'    # Date format
-      show_time: false           # Whether to show time
-      time_format: '%H:%M:%S'    # Time format
-      position: bottom           # Display position: top (after title) or bottom (end of document)
-      exclude:                   # List of file patterns to exclude
-        - "private/*"            # Exclude all files in private directory, including subdirectories
-        - "drafts/*.md"         # Exclude all markdown files in drafts directory
-        - "temp.md"             # Exclude specific file
-        - "*.tmp"               # Exclude all files with .tmp extension
+      type: date               # Date type: date | datetime | timeago, default: date
+      locale: en               # Localization: zh zh_tw en es fr de ar ja ko ru, default: en
+      date_format: '%Y-%m-%d'  # Date format
+      time_format: '%H:%M:%S'  # Time format
+      position: bottom         # Display position: top (after title) | bottom (end of document), default: bottom
+      exclude:                 # List of file patterns to exclude
+        - temp.md              # Exclude specific file
+        - private/*            # Exclude all files in private directory, including subdirectories
+        - drafts/*.md          # Exclude all markdown files in the current directory drafts, but not subdirectories
 ```
 
 ## Manual Date Specification
@@ -85,20 +85,24 @@ modified_date: 2023-12-31
 # Document Title
 ```
 
+
+
 ## Configuration Options
 
-- `date_format`: Date format (default: %Y-%m-%d)
-  - Supports all Python datetime format strings, examples: %Y-%m-%d, %b %d, %Y, etc.
-- `show_time`: Whether to show time (default: false)
-  - true: Show both date and time
-  - false: Show date only
-- `time_format`: Time format (default: %H:%M:%S)
-  - Only effective when show_time is true
-- `position`: Display position (default: bottom)
-  - top: Display after the first heading
-  - bottom: Display at the end of document
-- `exclude`: List of files to exclude (default: [])
-  - Supports glob patterns, example: ["private/*", "temp.md"]
+- `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` )
+  - Supports: `zh zh_tw en es fr de ar ja ko ru`
+- `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`)
+  - `top` : Display after the first heading
+  - `bottom` : Display at the end of the document
+- `exclude` : File exclusion list (default: [] )
+  - Supports glob patterns, e.g., ["private/\*", "temp.md", "drafts/\*.md"]
 
 ## Notes
 
@@ -106,5 +110,5 @@ modified_date: 2023-12-31
   - Windows: Uses file creation time
   - macOS: Uses file creation time (birthtime)
   - Linux: Uses modification time as creation time due to system limitations
-- For accurate creation times, it's recommended to use Front Matter for manual specification
+- For accurate creation times, it's recommended to specify dates manually in Front Matter
 

mkdocs_document_dates-0.5.0/mkdocs_document_dates.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+setup.py
+mkdocs_document_dates/__init__.py
+mkdocs_document_dates/plugin.py
+mkdocs_document_dates/styles.py
+mkdocs_document_dates.egg-info/PKG-INFO
+mkdocs_document_dates.egg-info/SOURCES.txt
+mkdocs_document_dates.egg-info/dependency_links.txt
+mkdocs_document_dates.egg-info/entry_points.txt
+mkdocs_document_dates.egg-info/requires.txt
+mkdocs_document_dates.egg-info/top_level.txt
+mkdocs_document_dates/lang/__init__.py
+mkdocs_document_dates/lang/ar.py
+mkdocs_document_dates/lang/de.py
+mkdocs_document_dates/lang/en.py
+mkdocs_document_dates/lang/es.py
+mkdocs_document_dates/lang/fr.py
+mkdocs_document_dates/lang/ja.py
+mkdocs_document_dates/lang/ko.py
+mkdocs_document_dates/lang/ru.py
+mkdocs_document_dates/lang/zh.py
+mkdocs_document_dates/lang/zh_tw.py

{mkdocs_document_dates-0.4.0 → mkdocs_document_dates-0.5.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="mkdocs-document-dates",
-    version="0.4.0",
+    version="0.5.0",
     author="Aaron Wang",
     description="A MkDocs plugin for displaying accurate document creation and last modification dates.",
     long_description=long_description,

mkdocs_document_dates-0.4.0/README.md

@@ -1,88 +0,0 @@
-# mkdocs-document-dates
-
-English | [简体中文](README_zh.md)
-
-
-
-A MkDocs plugin for displaying **accurate** document creation and last modification dates.
-
-## Features
-
-- Automatically displays document creation and last modification times
-- Supports manual date specification in `Front Matter`
-- No Git dependency, uses filesystem timestamps directly
-- Cross-platform support (Windows, macOS, Linux)
-- Configurable date and time formats
-- Flexible display position (top or bottom)
-- File exclusion rules support
-- Material Design icons
-- Elegant styling
-- Lightweight with no extra dependencies
-
-## Installation
-
-```bash
-pip install mkdocs-document-dates
-```
-
-## Configuration
-
-Add the plugin to your mkdocs.yml:
-
-```yaml
-plugins:
-  - document-dates
-```
-
-Or, customize the configuration:
-
-```yaml
-plugins:
-  - document-dates:
-      date_format: '%Y-%m-%d'    # Date format
-      show_time: false           # Whether to show time
-      time_format: '%H:%M:%S'    # Time format
-      position: bottom           # Display position: top (after title) or bottom (end of document)
-      exclude:                   # List of file patterns to exclude
-        - "private/*"            # Exclude all files in private directory, including subdirectories
-        - "drafts/*.md"         # Exclude all markdown files in drafts directory
-        - "temp.md"             # Exclude specific file
-        - "*.tmp"               # Exclude all files with .tmp extension
-```
-
-## Manual Date Specification
-
-You can also manually specify the date of a Markdown document in its `Front Matter` :
-
-```yaml
----
-created_date: 2023-01-01
-modified_date: 2023-12-31
----
-
-# Document Title
-```
-
-## Configuration Options
-
-- `date_format`: Date format (default: %Y-%m-%d)
-  - Supports all Python datetime format strings, examples: %Y-%m-%d, %b %d, %Y, etc.
-- `show_time`: Whether to show time (default: false)
-  - true: Show both date and time
-  - false: Show date only
-- `time_format`: Time format (default: %H:%M:%S)
-  - Only effective when show_time is true
-- `position`: Display position (default: bottom)
-  - top: Display after the first heading
-  - bottom: Display at the end of document
-- `exclude`: List of files to exclude (default: [])
-  - Supports glob patterns, example: ["private/*", "temp.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
-- For accurate creation times, it's recommended to use Front Matter for manual specification
-

mkdocs_document_dates-0.4.0/mkdocs_document_dates/plugin.py

@@ -1,175 +0,0 @@
-import os
-import platform
-from datetime import datetime
-from pathlib import Path
-from mkdocs.plugins import BasePlugin
-from mkdocs.config import config_options
-
-class DocumentDatesPlugin(BasePlugin):
-    config_scheme = (
-        ('date_format', config_options.Type(str, default='%Y-%m-%d')),
-        ('show_time', config_options.Type(bool, default=False)),
-        ('time_format', config_options.Type(str, default='%H:%M:%S')),
-        ('position', config_options.Type(str, default='bottom')),
-        ('exclude', config_options.Type(list, default=[])),
-    )
-
-    def __init__(self):
-        super().__init__()
-
-    def get_css_content(self):
-        """返回插件的 CSS 样式"""
-        return """
-.document-dates-plugin {
-    color: #8e8e8e;
-    font-size: 0.75rem;
-    padding: 0.2rem 0;
-    opacity: 0.8;
-    display: flex;
-    gap: 1.5rem;
-    align-items: center;
-    margin-bottom: 0.3rem;
-}
-.document-dates-plugin span {
-    display: inline-flex;
-    align-items: center;
-    gap: 0.3rem;
-}
-.document-dates-plugin .material-icons {
-    font-size: 0.9rem;
-    opacity: 0.7;
-}
-.document-dates-plugin-wrapper {
-    margin: 0.3rem 0 1rem 0;
-    border-bottom: 1px solid rgba(0, 0, 0, 0.07);
-    padding-bottom: 0.5rem;
-}
-"""
-
-    def on_config(self, config):
-        """配置插件并添加必要的 CSS"""
-        if 'extra_css' not in config:
-            config['extra_css'] = []
-        
-        # 添加 Material Icons
-        material_icons_url = 'https://fonts.googleapis.com/icon?family=Material+Icons'
-        if material_icons_url not in config['extra_css']:
-            config['extra_css'].append(material_icons_url)
-        
-        # 添加自定义 CSS
-        css_file = Path(config['docs_dir']) / 'assets' / 'document_dates.css'
-        css_file.parent.mkdir(parents=True, exist_ok=True)
-        css_file.write_text(self.get_css_content())
-        config['extra_css'].append('assets/document_dates.css')
-        
-        return config
-
-    def format_date_info(self, created, modified):
-        """格式化日期信息的 HTML"""
-        return (
-            f"\n\n"
-            f"<div class='document-dates-plugin-wrapper'>"
-            f"<div class='document-dates-plugin'>"
-            f"<span><span class='material-icons'>add_circle</span>"
-            f"{self.format_date(created)}</span>"
-            f"<span><span class='material-icons'>update</span>"
-            f"{self.format_date(modified)}</span>"
-            f"</div>"
-            f"</div>\n"
-        )
-
-    def insert_date_info(self, markdown, date_info):
-        """根据配置将日期信息插入到合适的位置"""
-        if self.config['position'] == 'top':
-            lines = markdown.split('\n')
-            for i, line in enumerate(lines):
-                if line.startswith('#'):
-                    lines.insert(i + 1, date_info)
-                    return '\n'.join(lines)
-            return date_info + markdown
-        return markdown + "\n\n" + date_info
-
-    def on_page_markdown(self, markdown, page, config, files):
-        """处理页面内容，添加日期信息"""
-        file_path = Path(page.file.abs_src_path)
-        docs_dir = Path(config['docs_dir'])
-        
-        # 检查是否在排除列表中
-        for exclude_pattern in self.config['exclude']:
-            # 处理目录递归排除（如 private/*）
-            if exclude_pattern.endswith('/*'):
-                base_dir = exclude_pattern[:-2]  # 移除 /*
-                try:
-                    # 检查当前文件是否在指定目录或其子目录中
-                    rel_path = file_path.relative_to(docs_dir)
-                    if str(rel_path).startswith(f"{base_dir}/"):
-                        return markdown
-                except ValueError:
-                    continue
-            
-            # 处理特定目录下的特定类型文件（如 drafts/*.md）
-            elif '/*.' in exclude_pattern:
-                dir_part, ext_part = exclude_pattern.split('/*.')
-                if (file_path.parent.name == dir_part and 
-                    file_path.suffix == f".{ext_part}"):
-                    return markdown
-            
-            # 处理特定后缀文件（如 *.tmp）
-            elif exclude_pattern.startswith('*.'):
-                if file_path.suffix == f".{exclude_pattern[2:]}":
-                    return markdown
-            
-            # 处理精确文件匹配（如 temp.md）
-            elif file_path.name == exclude_pattern:
-                return markdown
-        
-        # 直接获取日期信息
-        created, modified = self.get_file_dates(file_path)
-        
-        # 检查 frontmatter 中的日期
-        meta = getattr(page, 'meta', {})
-        if 'created_date' in meta:
-            try:
-                date_str = str(meta['created_date']).strip("'\"")  # 移除可能存在的引号
-                created = datetime.fromisoformat(date_str)
-            except (ValueError, TypeError):
-                # 如果解析失败，保持原有的文件系统日期
-                pass
-                
-        if 'modified_date' in meta:
-            try:
-                date_str = str(meta['modified_date']).strip("'\"")  # 移除可能存在的引号
-                modified = datetime.fromisoformat(date_str)
-            except (ValueError, TypeError):
-                # 如果解析失败，保持原有的文件系统日期
-                pass
-        
-        # 格式化并插入日期信息
-        date_info = self.format_date_info(created, modified)
-        return self.insert_date_info(markdown, date_info)
-
-    def get_file_dates(self, file_path):
-        """获取文件的创建时间和修改时间"""
-        
-        stat = os.stat(file_path)
-        modified = datetime.fromtimestamp(stat.st_mtime)
-        
-        system = platform.system().lower()
-        if 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 和其他系统
-            # Linux 没有可靠的创建时间，使用修改时间作为创建时间
-            created = modified
-        
-        return created, modified
-
-    def format_date(self, date):
-        if self.config['show_time']:
-            return date.strftime(f"{self.config['date_format']} {self.config['time_format']}")
-        return date.strftime(self.config['date_format'])
-

mkdocs_document_dates-0.4.0/mkdocs_document_dates.egg-info/SOURCES.txt

@@ -1,11 +0,0 @@
-LICENSE
-README.md
-setup.py
-mkdocs_document_dates/__init__.py
-mkdocs_document_dates/plugin.py
-mkdocs_document_dates.egg-info/PKG-INFO
-mkdocs_document_dates.egg-info/SOURCES.txt
-mkdocs_document_dates.egg-info/dependency_links.txt
-mkdocs_document_dates.egg-info/entry_points.txt
-mkdocs_document_dates.egg-info/requires.txt
-mkdocs_document_dates.egg-info/top_level.txt