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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/LICENSE +0 -1
  2. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/PKG-INFO +20 -17
  3. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/README.md +18 -15
  4. mkdocs_document_dates-2.3.1/mkdocs_document_dates/__init__.py +13 -0
  5. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/hooks/pre-commit +8 -13
  6. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/hooks_installer.py +20 -24
  7. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/__init__.py +0 -1
  8. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/ar.py +1 -0
  9. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/de.py +1 -0
  10. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/en.py +1 -0
  11. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/es.py +1 -0
  12. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/fr.py +1 -0
  13. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/ja.py +1 -0
  14. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/ko.py +1 -0
  15. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/ru.py +1 -0
  16. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/zh.py +1 -0
  17. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/lang/zh_tw.py +1 -0
  18. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/plugin.py +7 -26
  19. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates/styles.py +0 -1
  20. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates.egg-info/PKG-INFO +20 -17
  21. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/setup.py +3 -3
  22. mkdocs_document_dates-2.2.0/mkdocs_document_dates/__init__.py +0 -13
  23. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates.egg-info/SOURCES.txt +0 -0
  24. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates.egg-info/dependency_links.txt +0 -0
  25. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates.egg-info/entry_points.txt +0 -0
  26. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates.egg-info/requires.txt +0 -0
  27. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/mkdocs_document_dates.egg-info/top_level.txt +0 -0
  28. {mkdocs_document_dates-2.2.0 → mkdocs_document_dates-2.3.1}/setup.cfg +0 -0
@@ -9,4 +9,3 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
9
  copies of the Software, and to permit persons to whom the Software is
10
10
  furnished to do so, subject to the following conditions:
11
11
 
12
- [... 后续 MIT 许可证内容 ...]
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.2
2
2
  Name: mkdocs-document-dates
3
- Version: 2.2.0
3
+ Version: 2.3.1
4
4
  Summary: A MkDocs plugin for displaying accurate document creation and last modification dates.
5
5
  Home-page: https://github.com/jaywhj/mkdocs-document-dates
6
6
  Author: Aaron Wang
7
7
  Classifier: Programming Language :: Python :: 3
8
8
  Classifier: License :: OSI Approved :: MIT License
9
9
  Classifier: Operating System :: OS Independent
10
- Requires-Python: >=3.6
10
+ Requires-Python: >=3.7
11
11
  Description-Content-Type: text/markdown
12
12
  License-File: LICENSE
13
13
  Requires-Dist: mkdocs>=1.0.0
@@ -26,12 +26,12 @@ English | [简体中文](README_zh.md)
26
26
 
27
27
 
28
28
 
29
- A MkDocs plugin for displaying **accurate** document creation and last modification dates.
29
+ A MkDocs plugin for displaying <mark>accurate</mark> document creation and last modification dates.
30
30
 
31
31
  ## Features
32
32
 
33
33
  - Automatically displays document creation and last modification times
34
- - No Git dependency, uses filesystem timestamps directly
34
+ - **No Git dependency**, uses filesystem timestamps directly
35
35
  - Supports manual date specification in `Front Matter`
36
36
  - Cross-platform support (Windows, macOS, Linux)
37
37
  - Support for multiple time formats (date, datetime, timeago)
@@ -40,6 +40,7 @@ A MkDocs plugin for displaying **accurate** document creation and last modificat
40
40
  - Material Design icons, Elegant styling
41
41
  - Lightweight with no extra dependencies
42
42
  - Multi-language support
43
+ - Support for CI/CD build systems (e.g. Github Actions)
43
44
 
44
45
  ## Installation
45
46
 
@@ -79,7 +80,7 @@ You can also manually specify the date of a Markdown document in its `Front Matt
79
80
  ```yaml
80
81
  ---
81
82
  created: 2023-01-01
82
- modified: 2023-12-31
83
+ modified: 2025-02-23
83
84
  ---
84
85
 
85
86
  # Document Title
@@ -89,33 +90,35 @@ modified: 2023-12-31
89
90
 
90
91
  ## Configuration Options
91
92
 
92
- - `type` : Date type (default: `date` )
93
+ - **type** : Date type (default: `date` )
93
94
  - `date` : Display date only
94
95
  - `datetime` : Display date and time
95
96
  - `timeago` : Display relative time (e.g., 2 minutes ago)
96
- - `locale` : Localization (default: `en` )
97
+ - **locale** : Localization (default: `en` )
97
98
  - Supports: `zh zh_tw en es fr de ar ja ko ru`
98
- - `date_format` : Date format (default: `%Y-%m-%d`)
99
+ - **date_format** : Date format (default: `%Y-%m-%d`)
99
100
  - Supports all Python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc.
100
- - `time_format` : Time format (default: `%H:%M:%S`)
101
- - `position` : Display position (default: `bottom`)
101
+ - **time_format** : Time format (default: `%H:%M:%S`)
102
+ - **position** : Display position (default: `bottom`)
102
103
  - `top` : Display after the first heading
103
104
  - `bottom` : Display at the end of the document
104
- - `exclude` : File exclusion list (default: [] )
105
+ - **exclude** : File exclusion list (default: [] )
105
106
  - Supports glob patterns, e.g., ["private/\*", "temp.md", "drafts/\*.md"]
106
107
 
107
108
  ## Notes
108
109
 
109
- - Creation time behavior varies across operating systems:
110
- - Windows: Uses file creation time
111
- - macOS: Uses file creation time (birthtime)
112
- - 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
113
110
  - It still works when using CI/CD build systems (e.g. Github Actions)
114
111
  - Used a cache file `.dates_cache.json` to solve this problem
115
- - You can configure it like this:
112
+ - You can configure it like this in your .github/workflows/ci.yml:
113
+
116
114
  ```
117
115
  ...
118
116
 
119
117
  - run: pip install mkdocs-document-dates
120
118
  - run: mkdocs gh-deploy --force
121
- ```
119
+ ```
120
+ - Then update your Markdown files in MkDocs as normal, execute commands such as mkdocs build or directly git add, commit, and push
121
+ - Make sure you have installed python3 ahead of time and set environment variables
122
+ - Priority of time reads:
123
+ - `Front Matter` > `Cache file` > `Filesystem timestamp`
124
+ - 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
@@ -4,12 +4,12 @@ English | [简体中文](README_zh.md)
4
4
 
5
5
 
6
6
 
7
- A MkDocs plugin for displaying **accurate** document creation and last modification dates.
7
+ A MkDocs plugin for displaying <mark>accurate</mark> document creation and last modification dates.
8
8
 
9
9
  ## Features
10
10
 
11
11
  - Automatically displays document creation and last modification times
12
- - No Git dependency, uses filesystem timestamps directly
12
+ - **No Git dependency**, uses filesystem timestamps directly
13
13
  - Supports manual date specification in `Front Matter`
14
14
  - Cross-platform support (Windows, macOS, Linux)
15
15
  - Support for multiple time formats (date, datetime, timeago)
@@ -18,6 +18,7 @@ A MkDocs plugin for displaying **accurate** document creation and last modificat
18
18
  - Material Design icons, Elegant styling
19
19
  - Lightweight with no extra dependencies
20
20
  - Multi-language support
21
+ - Support for CI/CD build systems (e.g. Github Actions)
21
22
 
22
23
  ## Installation
23
24
 
@@ -57,7 +58,7 @@ You can also manually specify the date of a Markdown document in its `Front Matt
57
58
  ```yaml
58
59
  ---
59
60
  created: 2023-01-01
60
- modified: 2023-12-31
61
+ modified: 2025-02-23
61
62
  ---
62
63
 
63
64
  # Document Title
@@ -67,33 +68,35 @@ modified: 2023-12-31
67
68
 
68
69
  ## Configuration Options
69
70
 
70
- - `type` : Date type (default: `date` )
71
+ - **type** : Date type (default: `date` )
71
72
  - `date` : Display date only
72
73
  - `datetime` : Display date and time
73
74
  - `timeago` : Display relative time (e.g., 2 minutes ago)
74
- - `locale` : Localization (default: `en` )
75
+ - **locale** : Localization (default: `en` )
75
76
  - Supports: `zh zh_tw en es fr de ar ja ko ru`
76
- - `date_format` : Date format (default: `%Y-%m-%d`)
77
+ - **date_format** : Date format (default: `%Y-%m-%d`)
77
78
  - Supports all Python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc.
78
- - `time_format` : Time format (default: `%H:%M:%S`)
79
- - `position` : Display position (default: `bottom`)
79
+ - **time_format** : Time format (default: `%H:%M:%S`)
80
+ - **position** : Display position (default: `bottom`)
80
81
  - `top` : Display after the first heading
81
82
  - `bottom` : Display at the end of the document
82
- - `exclude` : File exclusion list (default: [] )
83
+ - **exclude** : File exclusion list (default: [] )
83
84
  - Supports glob patterns, e.g., ["private/\*", "temp.md", "drafts/\*.md"]
84
85
 
85
86
  ## Notes
86
87
 
87
- - Creation time behavior varies across operating systems:
88
- - Windows: Uses file creation time
89
- - macOS: Uses file creation time (birthtime)
90
- - 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
91
88
  - It still works when using CI/CD build systems (e.g. Github Actions)
92
89
  - Used a cache file `.dates_cache.json` to solve this problem
93
- - You can configure it like this:
90
+ - You can configure it like this in your .github/workflows/ci.yml:
91
+
94
92
  ```
95
93
  ...
96
94
 
97
95
  - run: pip install mkdocs-document-dates
98
96
  - run: mkdocs gh-deploy --force
99
- ```
97
+ ```
98
+ - Then update your Markdown files in MkDocs as normal, execute commands such as mkdocs build or directly git add, commit, and push
99
+ - Make sure you have installed python3 ahead of time and set environment variables
100
+ - Priority of time reads:
101
+ - `Front Matter` > `Cache file` > `Filesystem timestamp`
102
+ - 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
@@ -0,0 +1,13 @@
1
+ """MkDocs Document Dates Plugin."""
2
+
3
+ __version__ = '2.3.1'
4
+
5
+ from .hooks_installer import install
6
+
7
+ # 在包被导入时自动执行 hooks 安装
8
+ try:
9
+ result = install()
10
+ if not result:
11
+ print("Tip: Git hooks installation was skipped (probably because Git was not detected or not in the Git repository)")
12
+ except Exception as e:
13
+ print(f"Warning: Git hooks installation failed: {e}")
@@ -9,25 +9,23 @@ from datetime import datetime
9
9
  from pathlib import Path
10
10
 
11
11
  def find_mkdocs_projects():
12
- """查找当前 git 仓库中的所有 MkDocs 项目"""
13
12
  try:
14
13
  git_root = Path(subprocess.check_output(
15
14
  ['git', 'rev-parse', '--show-toplevel'],
16
15
  text=True, encoding='utf-8'
17
16
  ).strip())
18
-
17
+
19
18
  projects = []
20
19
  for config_file in git_root.rglob('mkdocs.y*ml'):
21
20
  if config_file.name.lower() in ('mkdocs.yml', 'mkdocs.yaml'):
22
21
  projects.append(config_file.parent)
23
-
22
+
24
23
  return projects
25
24
  except subprocess.CalledProcessError as e:
26
- print(f"查找 Git 仓库根目录失败: {e}", file=sys.stderr)
25
+ print(f"Failed to find the Git repository root: {e}", file=sys.stderr)
27
26
  return []
28
27
 
29
28
  def get_file_dates(file_path):
30
- """获取文件的创建和修改时间"""
31
29
  try:
32
30
  stat = os.stat(file_path)
33
31
  modified = datetime.fromtimestamp(stat.st_mtime)
@@ -49,12 +47,10 @@ def get_file_dates(file_path):
49
47
  return current_time.isoformat(), current_time.isoformat()
50
48
 
51
49
  def update_dates_cache():
52
- """更新文档时间缓存"""
53
- print("开始更新文档时间缓存...")
54
50
  for project_dir in find_mkdocs_projects():
55
51
  docs_dir = project_dir / 'docs'
56
52
  if not docs_dir.exists():
57
- print(f"文档目录不存在: {docs_dir}")
53
+ print(f"Document directory does not exist: {docs_dir}")
58
54
  continue
59
55
 
60
56
  dates_cache = {}
@@ -69,25 +65,24 @@ def update_dates_cache():
69
65
  "modified": modified
70
66
  }
71
67
  except Exception as e:
72
- print(f"处理文件 {md_file} 时出错: {e}")
68
+ print(f"Error processing file {md_file}: {e}")
73
69
 
74
70
  if not dates_cache:
75
71
  continue
76
72
 
77
73
  cache_file = docs_dir / '.dates_cache.json'
78
- print(f"正在写入缓存文件: {cache_file}")
79
74
  try:
80
75
  with open(cache_file, "w") as f:
81
76
  json.dump(dates_cache, f, indent=2, ensure_ascii=False)
82
77
  subprocess.run(["git", "add", str(cache_file)], check=True)
83
- print(f"缓存文件 {cache_file} 已更新.")
78
+ # print(f"The cache file {cache_file} has been updated")
84
79
  except Exception as e:
85
- print(f"写入缓存文件时出错: {e}", file=sys.stderr)
80
+ print(f"Error writing to cache file: {e}", file=sys.stderr)
86
81
  raise
87
82
 
88
83
  if __name__ == "__main__":
89
84
  try:
90
85
  update_dates_cache()
91
86
  except Exception as e:
92
- print(f"Hook 执行出错: {e}", file=sys.stderr)
87
+ print(f"Hook execution error: {e}", file=sys.stderr)
93
88
  sys.exit(1)
@@ -6,21 +6,18 @@ from pathlib import Path
6
6
  import platform
7
7
 
8
8
  def get_config_dir():
9
- """获取用户配置目录"""
10
- system = platform.system().lower()
11
- if system.startswith('win'):
9
+ if platform.system().lower().startswith('win'):
12
10
  return Path(os.getenv('APPDATA', str(Path.home() / 'AppData' / 'Roaming')))
13
- else: # macOS 和 Linux 统一使用 ~/.config
11
+ else:
14
12
  return Path.home() / '.config'
15
13
 
16
14
  def install():
17
- """安装 git hooks"""
18
15
  try:
19
16
  # 检查 git 是否可用
20
17
  try:
21
18
  subprocess.run(['git', '--version'], check=True, capture_output=True, encoding='utf-8')
22
19
  except (subprocess.CalledProcessError, FileNotFoundError):
23
- print("提示: 未检测到 Git,跳过 hooks 安装")
20
+ print("Tip: Git not detected, skip hooks installation")
24
21
  return False
25
22
 
26
23
  # 准备配置目录
@@ -28,49 +25,48 @@ def install():
28
25
  try:
29
26
  config_dir.mkdir(parents=True, exist_ok=True)
30
27
  except PermissionError:
31
- print(f"错误: 无权限创建目录: {config_dir}")
28
+ print(f"Error: No permission to create directory: {config_dir}")
32
29
  return False
33
30
  except Exception as e:
34
- print(f"错误: 创建目录失败: {config_dir}, 原因: {e}")
31
+ print(f"Error: Failed to create directory: {config_dir}, reason: {e}")
35
32
  return False
36
33
 
37
34
  hook_path = config_dir / 'pre-commit'
38
35
 
39
- # 复制 hook 文件
36
+ # 复制 hook 文件到配置目录
40
37
  source_hook = Path(__file__).parent / 'hooks' / 'pre-commit'
41
38
  if not source_hook.exists():
42
- print(f"错误: hook 文件不存在: {source_hook}")
39
+ print(f"Error: Source hook file does not exist: {source_hook}")
43
40
  return False
44
-
41
+
45
42
  try:
46
43
  shutil.copy2(source_hook, hook_path)
47
44
  except PermissionError:
48
- print(f"错误: 无权限复制文件到: {hook_path}")
45
+ print(f"Error: No permission to copy file to: {hook_path}")
49
46
  return False
50
47
  except Exception as e:
51
- print(f"错误: 复制文件失败, 原因: {e}")
48
+ print(f"Error: Failed to copy file, reason: {e}")
52
49
  return False
53
50
 
54
- # 设置文件权限(Unix-like 系统)
55
- if not platform.system().lower().startswith('win'):
56
- try:
57
- os.chmod(config_dir, 0o755)
58
- os.chmod(hook_path, 0o755)
59
- except OSError as e:
60
- print(f"警告: 设置权限时出错: {e}")
51
+ # 设置文件权限
52
+ try:
53
+ os.chmod(config_dir, 0o755)
54
+ os.chmod(hook_path, 0o755)
55
+ except OSError as e:
56
+ print(f"Warning: Error setting permissions: {e}")
61
57
 
62
- # 配置 git hooks 路径
58
+ # 配置全局 git hooks 路径
63
59
  try:
64
60
  subprocess.run(['git', 'config', '--global', 'core.hooksPath',
65
61
  str(config_dir)], check=True, encoding='utf-8')
66
- print(f"Git hooks 已安装到: {config_dir}")
62
+ # print(f"Git hooks are installed in the: {config_dir}")
67
63
  return True
68
64
  except subprocess.CalledProcessError as e:
69
- print(f"错误: 设置 git hooks 路径失败: {e}")
65
+ print(f"Error: Setting git hooks path failed: {e}")
70
66
  return False
71
67
 
72
68
  except Exception as e:
73
- print(f"安装 hooks 时出错: {e}")
69
+ print(f"Error installing hooks: {e}")
74
70
  return False
75
71
 
76
72
  if __name__ == '__main__':
@@ -2,7 +2,6 @@ from pathlib import Path
2
2
  import importlib.util
3
3
 
4
4
  def load_translations():
5
- """加载所有可用的翻译"""
6
5
  translations = {}
7
6
  translations_dir = Path(__file__).parent
8
7
 
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': 'الآن',
3
4
  'seconds_ago': 'منذ {} ثانية',
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': 'gerade jetzt',
3
4
  'seconds_ago': 'vor {} Sekunden',
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': 'just now',
3
4
  'seconds_ago': '{} seconds ago',
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': 'justo ahora',
3
4
  'seconds_ago': 'hace {} segundos',
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': 'à l\'instant',
3
4
  'seconds_ago': 'il y a {} secondes',
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': 'たった今',
3
4
  'seconds_ago': '{} 秒前',
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': '방금',
3
4
  'seconds_ago': '{} 초 전',
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': 'только что',
3
4
  'seconds_ago': '{} секунд назад',
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': '刚刚',
3
4
  'seconds_ago': '{} 秒前',
@@ -1,3 +1,4 @@
1
+ # -*- coding: utf-8 -*-
1
2
  translations = {
2
3
  'just_now': '剛剛',
3
4
  'seconds_ago': '{} 秒前',
@@ -23,11 +23,9 @@ class DocumentDatesPlugin(BasePlugin):
23
23
  self.translations = load_translations()
24
24
 
25
25
  def _get_css_content(self):
26
- """返回插件的 CSS 样式"""
27
26
  return DOCUMENT_DATES_CSS
28
27
 
29
28
  def on_config(self, config):
30
- """配置插件并添加必要的 CSS"""
31
29
  if 'extra_css' not in config:
32
30
  config['extra_css'] = []
33
31
 
@@ -45,8 +43,6 @@ class DocumentDatesPlugin(BasePlugin):
45
43
  return config
46
44
 
47
45
  def _get_date_info(self, created, modified):
48
- """格式化日期信息的 HTML"""
49
- # 获取翻译字典
50
46
  locale = self.config['locale']
51
47
  if locale not in self.translations:
52
48
  locale = 'en'
@@ -64,7 +60,6 @@ class DocumentDatesPlugin(BasePlugin):
64
60
  )
65
61
 
66
62
  def _insert_date_info(self, markdown, date_info):
67
- """根据配置将日期信息插入到合适的位置"""
68
63
  if not markdown.strip():
69
64
  return markdown
70
65
 
@@ -78,14 +73,13 @@ class DocumentDatesPlugin(BasePlugin):
78
73
  return f"{markdown}\n\n{date_info}"
79
74
 
80
75
  def on_page_markdown(self, markdown, page, config, files):
81
- """处理页面内容,添加日期信息"""
82
76
  file_path = Path(page.file.abs_src_path)
83
77
 
84
78
  if self._is_excluded(file_path, Path(config['docs_dir'])):
85
79
  return markdown
86
80
 
87
81
  # 获取文件时间
88
- created, modified = self._get_file_dates(file_path, config) # 传入 config
82
+ created, modified = self._get_file_dates(file_path, config)
89
83
 
90
84
  # 处理 front matter 中的时间
91
85
  created, modified = self._process_meta_dates(page.meta, created, modified)
@@ -97,19 +91,12 @@ class DocumentDatesPlugin(BasePlugin):
97
91
  return self._insert_date_info(markdown, date_info)
98
92
 
99
93
  def _is_excluded(self, file_path: Path, docs_dir: Path) -> bool:
100
- """检查文件是否在排除列表中"""
101
94
  for pattern in self.config['exclude']:
102
95
  if self._matches_exclude_pattern(file_path, docs_dir, pattern):
103
96
  return True
104
97
  return False
105
98
 
106
99
  def _matches_exclude_pattern(self, file_path: Path, docs_dir: Path, pattern: str) -> bool:
107
- """检查文件是否匹配排除模式
108
- 支持三种匹配模式:
109
- 1. 具体文件路径:支持多级目录,如 'private/temp.md'
110
- 2. 目录下所有文件:使用 '*' 通配符,如 'private/*',匹配包含子目录的所有文件
111
- 3. 指定目录下特定类型文件:如 'private/*.md',仅匹配当前目录下的特定类型文件
112
- """
113
100
  try:
114
101
  # 获取相对于 docs_dir 的路径
115
102
  rel_path = file_path.relative_to(docs_dir)
@@ -136,13 +123,11 @@ class DocumentDatesPlugin(BasePlugin):
136
123
  return False
137
124
 
138
125
  def _process_meta_dates(self, meta: dict, created: datetime, modified: datetime) -> tuple[datetime, datetime]:
139
- """处理 frontmatter 中的日期"""
140
126
  result_created = self._parse_meta_date(meta.get('created'), created)
141
127
  result_modified = self._parse_meta_date(meta.get('modified'), modified)
142
128
  return result_created, result_modified
143
129
 
144
130
  def _parse_meta_date(self, date_str: str | None, default_date: datetime) -> datetime:
145
- """解析 meta 中的日期字符串"""
146
131
  if not date_str:
147
132
  return default_date
148
133
 
@@ -151,10 +136,8 @@ class DocumentDatesPlugin(BasePlugin):
151
136
  except (ValueError, TypeError):
152
137
  return default_date
153
138
 
154
- def _get_file_dates(self, file_path, config): # 添加 config 参数
155
- """获取文件的创建时间和修改时间"""
139
+ def _get_file_dates(self, file_path, config):
156
140
  try:
157
- # 从传入的 config 中获取 docs_dir
158
141
  docs_dir = Path(config['docs_dir'])
159
142
  rel_path = str(Path(file_path).relative_to(docs_dir))
160
143
 
@@ -172,16 +155,16 @@ class DocumentDatesPlugin(BasePlugin):
172
155
  # 如果缓存不存在或文件不在缓存中,使用文件系统时间
173
156
  stat = os.stat(file_path)
174
157
  modified = datetime.fromtimestamp(stat.st_mtime)
175
-
158
+
176
159
  system = platform.system().lower()
177
- if system == 'darwin': # macOS
160
+ if system.startswith('win'): # Windows
161
+ created = datetime.fromtimestamp(stat.st_ctime)
162
+ elif system == 'darwin': # macOS
178
163
  try:
179
164
  created = datetime.fromtimestamp(stat.st_birthtime)
180
165
  except AttributeError:
181
166
  created = datetime.fromtimestamp(stat.st_ctime)
182
- elif system == 'windows': # Windows
183
- created = datetime.fromtimestamp(stat.st_ctime)
184
- else: # Linux 和其他系统
167
+ else: # Linux
185
168
  created = modified
186
169
 
187
170
  return created, modified
@@ -191,7 +174,6 @@ class DocumentDatesPlugin(BasePlugin):
191
174
  return current_time, current_time
192
175
 
193
176
  def _get_timeago(self, date):
194
- """将日期格式化为 timeago 格式"""
195
177
  now = datetime.now()
196
178
  diff = now - date
197
179
  seconds = diff.total_seconds()
@@ -233,7 +215,6 @@ class DocumentDatesPlugin(BasePlugin):
233
215
  return t['years_ago'].format(int(seconds / 31536000))
234
216
 
235
217
  def _get_formatted_date(self, date):
236
- """格式化日期,支持 timeago、date 和 datetime 格式"""
237
218
  if self.config['type'] == 'timeago':
238
219
  return self._get_timeago(date)
239
220
  elif self.config['type'] == 'datetime':
@@ -1,4 +1,3 @@
1
- """CSS 样式定义"""
2
1
 
3
2
  DOCUMENT_DATES_CSS = """
4
3
  .document-dates-plugin {
@@ -1,13 +1,13 @@
1
1
  Metadata-Version: 2.2
2
2
  Name: mkdocs-document-dates
3
- Version: 2.2.0
3
+ Version: 2.3.1
4
4
  Summary: A MkDocs plugin for displaying accurate document creation and last modification dates.
5
5
  Home-page: https://github.com/jaywhj/mkdocs-document-dates
6
6
  Author: Aaron Wang
7
7
  Classifier: Programming Language :: Python :: 3
8
8
  Classifier: License :: OSI Approved :: MIT License
9
9
  Classifier: Operating System :: OS Independent
10
- Requires-Python: >=3.6
10
+ Requires-Python: >=3.7
11
11
  Description-Content-Type: text/markdown
12
12
  License-File: LICENSE
13
13
  Requires-Dist: mkdocs>=1.0.0
@@ -26,12 +26,12 @@ English | [简体中文](README_zh.md)
26
26
 
27
27
 
28
28
 
29
- A MkDocs plugin for displaying **accurate** document creation and last modification dates.
29
+ A MkDocs plugin for displaying <mark>accurate</mark> document creation and last modification dates.
30
30
 
31
31
  ## Features
32
32
 
33
33
  - Automatically displays document creation and last modification times
34
- - No Git dependency, uses filesystem timestamps directly
34
+ - **No Git dependency**, uses filesystem timestamps directly
35
35
  - Supports manual date specification in `Front Matter`
36
36
  - Cross-platform support (Windows, macOS, Linux)
37
37
  - Support for multiple time formats (date, datetime, timeago)
@@ -40,6 +40,7 @@ A MkDocs plugin for displaying **accurate** document creation and last modificat
40
40
  - Material Design icons, Elegant styling
41
41
  - Lightweight with no extra dependencies
42
42
  - Multi-language support
43
+ - Support for CI/CD build systems (e.g. Github Actions)
43
44
 
44
45
  ## Installation
45
46
 
@@ -79,7 +80,7 @@ You can also manually specify the date of a Markdown document in its `Front Matt
79
80
  ```yaml
80
81
  ---
81
82
  created: 2023-01-01
82
- modified: 2023-12-31
83
+ modified: 2025-02-23
83
84
  ---
84
85
 
85
86
  # Document Title
@@ -89,33 +90,35 @@ modified: 2023-12-31
89
90
 
90
91
  ## Configuration Options
91
92
 
92
- - `type` : Date type (default: `date` )
93
+ - **type** : Date type (default: `date` )
93
94
  - `date` : Display date only
94
95
  - `datetime` : Display date and time
95
96
  - `timeago` : Display relative time (e.g., 2 minutes ago)
96
- - `locale` : Localization (default: `en` )
97
+ - **locale** : Localization (default: `en` )
97
98
  - Supports: `zh zh_tw en es fr de ar ja ko ru`
98
- - `date_format` : Date format (default: `%Y-%m-%d`)
99
+ - **date_format** : Date format (default: `%Y-%m-%d`)
99
100
  - Supports all Python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc.
100
- - `time_format` : Time format (default: `%H:%M:%S`)
101
- - `position` : Display position (default: `bottom`)
101
+ - **time_format** : Time format (default: `%H:%M:%S`)
102
+ - **position** : Display position (default: `bottom`)
102
103
  - `top` : Display after the first heading
103
104
  - `bottom` : Display at the end of the document
104
- - `exclude` : File exclusion list (default: [] )
105
+ - **exclude** : File exclusion list (default: [] )
105
106
  - Supports glob patterns, e.g., ["private/\*", "temp.md", "drafts/\*.md"]
106
107
 
107
108
  ## Notes
108
109
 
109
- - Creation time behavior varies across operating systems:
110
- - Windows: Uses file creation time
111
- - macOS: Uses file creation time (birthtime)
112
- - 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
113
110
  - It still works when using CI/CD build systems (e.g. Github Actions)
114
111
  - Used a cache file `.dates_cache.json` to solve this problem
115
- - You can configure it like this:
112
+ - You can configure it like this in your .github/workflows/ci.yml:
113
+
116
114
  ```
117
115
  ...
118
116
 
119
117
  - run: pip install mkdocs-document-dates
120
118
  - run: mkdocs gh-deploy --force
121
- ```
119
+ ```
120
+ - Then update your Markdown files in MkDocs as normal, execute commands such as mkdocs build or directly git add, commit, and push
121
+ - Make sure you have installed python3 ahead of time and set environment variables
122
+ - Priority of time reads:
123
+ - `Front Matter` > `Cache file` > `Filesystem timestamp`
124
+ - 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
@@ -7,7 +7,7 @@ try:
7
7
  except FileNotFoundError:
8
8
  long_description = "A MkDocs plugin for displaying accurate document creation and last modification dates."
9
9
 
10
- VERSION = '2.2.0'
10
+ VERSION = '2.3.1'
11
11
 
12
12
  setup(
13
13
  name="mkdocs-document-dates",
@@ -31,12 +31,12 @@ setup(
31
31
  'document-dates = mkdocs_document_dates.plugin:DocumentDatesPlugin',
32
32
  ],
33
33
  'console_scripts': [
34
- # 提供命令行工具,允许用户手动执行 hooks 安装
34
+ # 提供手动执行 hooks 安装的入口
35
35
  'mkdocs-document-dates-hooks=mkdocs_document_dates.hooks_installer:install'
36
36
  ],
37
37
  },
38
38
  package_data={
39
39
  'mkdocs_document_dates': ['hooks/*'],
40
40
  },
41
- python_requires=">=3.6",
41
+ python_requires=">=3.7",
42
42
  )
@@ -1,13 +0,0 @@
1
- """MkDocs Document Dates Plugin."""
2
-
3
- __version__ = '2.0.0'
4
-
5
- from .hooks_installer import install
6
-
7
- # 在包被导入时自动执行 hooks 安装
8
- try:
9
- result = install()
10
- if not result:
11
- print("提示: Git hooks 安装被跳过(可能是因为未检测到 Git 或不在 Git 仓库中)")
12
- except Exception as e:
13
- print(f"警告: Git hooks 安装失败: {e}")