mkdocs-document-dates 3.1.3__tar.gz → 3.1.5__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 (42) hide show
  1. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/PKG-INFO +46 -31
  2. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/README.md +44 -29
  3. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/cache_manager.py +7 -7
  4. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/plugin.py +42 -48
  5. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/config/user.config.css +2 -6
  6. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/config/user.config.js +10 -5
  7. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/core.js +26 -77
  8. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/PKG-INFO +46 -31
  9. mkdocs_document_dates-3.1.5/mkdocs_document_dates.egg-info/requires.txt +1 -0
  10. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/setup.py +2 -2
  11. mkdocs_document_dates-3.1.3/mkdocs_document_dates.egg-info/requires.txt +0 -1
  12. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/LICENSE +0 -0
  13. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/__init__.py +0 -0
  14. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/hooks/pre-commit +0 -0
  15. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/hooks_installer.py +0 -0
  16. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/core.css +0 -0
  17. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/timeago-load.js +0 -0
  18. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/timeago.full.min.js +0 -0
  19. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/timeago.min.js +0 -0
  20. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/ar.json +0 -0
  21. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/de.json +0 -0
  22. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/en.json +0 -0
  23. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/es.json +0 -0
  24. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/fr.json +0 -0
  25. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/ja.json +0 -0
  26. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/ko.json +0 -0
  27. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/ru.json +0 -0
  28. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/zh.json +0 -0
  29. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/zh_TW.json +0 -0
  30. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/backdrop.css +0 -0
  31. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/light.css +0 -0
  32. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/material.css +0 -0
  33. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/popper.min.js +0 -0
  34. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/scale.css +0 -0
  35. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/shift-away.css +0 -0
  36. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/tippy.css +0 -0
  37. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/tippy.umd.min.js +0 -0
  38. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/SOURCES.txt +0 -0
  39. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/dependency_links.txt +0 -0
  40. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/entry_points.txt +0 -0
  41. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/top_level.txt +0 -0
  42. {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/setup.cfg +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mkdocs-document-dates
3
- Version: 3.1.3
3
+ Version: 3.1.5
4
4
  Summary: An easy-to-use, lightweight MkDocs plugin for displaying the exact creation time, last modification time and author info of markdown documents.
5
5
  Home-page: https://github.com/jaywhj/mkdocs-document-dates
6
6
  Author: Aaron Wang
@@ -12,7 +12,7 @@ Classifier: Operating System :: OS Independent
12
12
  Requires-Python: >=3.7
13
13
  Description-Content-Type: text/markdown
14
14
  License-File: LICENSE
15
- Requires-Dist: mkdocs>=1.0.0
15
+ Requires-Dist: mkdocs>=1.1.0
16
16
  Dynamic: author
17
17
  Dynamic: author-email
18
18
  Dynamic: classifier
@@ -35,8 +35,8 @@ An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark>
35
35
 
36
36
  ## Features
37
37
 
38
- - Work in any environment, for Git-less environments, CI/CD environments (e.g. GitHub Actions), one-person collaboration, multi-person collaboration, etc
39
- - Support for manually specifying time and author info in `Front Matter`
38
+ - Always display exact meta-info of the document for any environment (no-Git, Git, all CI/CD build systems, etc)
39
+ - Support for manually specifying time and author in `Front Matter`
40
40
  - Support for multiple time formats (date, datetime, timeago)
41
41
  - Support for document exclusion mode
42
42
  - Flexible display position (top or bottom)
@@ -74,15 +74,14 @@ plugins:
74
74
  - document-dates:
75
75
  position: top # Display position: top (after title) bottom (end of document), default: bottom
76
76
  type: date # Date type: date datetime timeago, default: date
77
- locale: en # Localization: zh zh_TW en es fr de ar ja ko ru, default: en
78
- date_format: '%Y-%m-%d' # Date format, supports all python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
79
- time_format: '%H:%M:%S' # Time format (valid only if type=datetime)
77
+ locale: en # Localization: en zh zh_TW es fr de ar ja ko ru, default: en
78
+ date_format: '%Y-%m-%d' # Date format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
79
+ time_format: '%H:%M:%S' # Time format strings (valid only if type=datetime)
80
80
  exclude: # List of excluded files
81
81
  - temp.md # Exclude specific file
82
82
  - private/* # Exclude all files in private directory, including subdirectories
83
- - drafts/*.md # Exclude all markdown files in the current directory drafts, but not subdirectories
84
83
 
85
- show_author: true # Show author or not: true false, default: true
84
+ show_author: true # Show author or not, default: true
86
85
 
87
86
  ```
88
87
 
@@ -90,7 +89,7 @@ plugins:
90
89
 
91
90
  The plugin will automatically get the exact time of the document, will automatically cache the creation time, but of course, you can also specify it manually in `Front Matter`
92
91
 
93
- Priority: `Front Matter` > `Cache Files` > `File System Timestamps`
92
+ Priority order: `Front Matter` > `Cache Files` > `File System Timestamps`
94
93
 
95
94
  ```yaml
96
95
  ---
@@ -108,7 +107,7 @@ modified: 2025-02-23
108
107
 
109
108
  The plugin will automatically get the author of the document, will parse the email and make a link, also you can specify it manually in `Front Matter`
110
109
 
111
- Priority: `Front Matter` > `Git Author Info` > `PC Username`
110
+ Priority order: `Front Matter` > `Git Author` > `site_author (mkdocs.yml)` > `PC Username`
112
111
 
113
112
  ```yaml
114
113
  ---
@@ -124,26 +123,42 @@ email: e-name@gmail.com
124
123
 
125
124
  ## Customization
126
125
 
127
- The plugin supports deep customization, such as icon style, font style, theme color, animation type, dividing line, etc. All of it can be customized by modifying the code in the corresponding file (I've already written the code and comments, you just need to turn on the switch and change the value):
126
+ The plugin supports deep customization, such as **icon style, font style, theme color, animation type, dividing line**, etc. All of it can be customized by modifying the preset values in the corresponding file (I've already written the code and comments, you just need to turn on the switch and change the value):
128
127
 
129
- - Style & Theme: `docs/assets/document_dates/user.config.css`
130
- - Properties & Animations: `docs/assets/document_dates/user.config.js`
131
- - Localized languages: `docs/assets/document_dates/languages/` , refer to the template file `en.json` for any additions or modifications
132
- - timeago.js localization: `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
133
- - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
134
- - In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
135
- ```yaml
136
- extra_javascript:
137
- - assets/document_dates/core/timeago.full.min.js
138
- - assets/document_dates/core/timeago-load.js
139
- ```
128
+ | Function: | Location: |
129
+ | :----------------------: | ---------------------------------------- |
130
+ | **Style & Theme** | `docs/assets/document_dates/user.config.css` |
131
+ | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
132
+ | **Localized languages** | `docs/assets/document_dates/languages/` <br />refer to the template file `en.json` for any additions or modifications |
133
+
134
+ **Tip**: when `type: timeago` is set, timeago.js is enabled to render time dynamically, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
135
+
136
+ - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
137
+ - In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
138
+ ```yaml
139
+ extra_javascript:
140
+ - assets/document_dates/core/timeago.full.min.js
141
+ - assets/document_dates/core/timeago-load.js
142
+ ```
143
+
144
+ **Demo Images**:
145
+
146
+ ![01-default-w](mkdocs_document_dates/demo_images/01-default-w.png)
147
+ ![02-change-icon](mkdocs_document_dates/demo_images/02-change-icon.png)
148
+ ![02-change-icon-color](mkdocs_document_dates/demo_images/02-change-icon-color.png)
149
+ ![04-default-pop-up](mkdocs_document_dates/demo_images/04-default-pop-up.png)
150
+ ![05-change-theme](mkdocs_document_dates/demo_images/05-change-theme.png)
151
+
152
+ ![06-change-theme](mkdocs_document_dates/demo_images/06-change-theme.png)
153
+ ![07-pop-up-from-top](mkdocs_document_dates/demo_images/07-pop-up-from-top.png)
154
+ ![08-pop-up-from-bottom](mkdocs_document_dates/demo_images/08-pop-up-from-bottom.png)
140
155
 
141
156
  ## Other Tips
142
157
 
143
- - In order to get the exact creation time, a separate cache file is used to store the creation time of the file, located in the doc folder (hidden by default), please don't delete it:
158
+ - In order to always get the exact creation time, a separate cache file is used to store the creation time of the document, located in the docs folder (hidden by default), please don't delete it:
144
159
  - `docs/.dates_cache.jsonl`, cache file
145
160
  - `docs/.gitattributes`, merge mechanism for cache file
146
- - The Git Hooks mechanism is used to automatically trigger the storing of the cache (on each git commit), and the cached file is automatically committed along with it. In addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
161
+ - The Git Hooks mechanism is used to automatically trigger the storing of the cache (on each git commit), and the cached file is automatically committed along with it, in addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
147
162
 
148
163
  <br />
149
164
 
@@ -152,11 +167,11 @@ The plugin supports deep customization, such as icon style, font style, theme co
152
167
  A dispensable, insignificant little plug-in, friends who have time can take a look \^\_\^
153
168
 
154
169
  - **Origin**:
155
- - Because [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin), a great project. When I used it at the end of 2024, I found that I couldn't use it locally because my mkdocs documentation was not included in git management, then I don't understand why not read the file system time, but to use the git time, and raised an issue to the author, but didn't get a reply for about a week (the author had a reply later, nice guy, I guess he was busy at the time), and then I thought, there is nothing to do during the Chinese New Year, and now AI is so hot, why not with the help of the AI try it out for myself, it was born, born in February 2025
170
+ - Because [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin), a great project. When I used it at the end of 2024, I found that I couldn't use it locally because my mkdocs documentation was not included in git management, I don't understand why not read the file system time, but to use the git time, and the filesystem time is more accurate, then raised an issue to the author, but didn't get a reply for about a week (the author had a reply later, nice guy, I guess he was busy at the time), and then I thought, there is nothing to do during the Chinese New Year, and now AI is so hot, why not with the help of the AI try it out for myself, it was born, born in February 2025
156
171
  - **Iteration**:
157
172
  - After development, I understood why not use filesystem time, because files will be rebuilt when they go through git checkout or clone, resulting in the loss of original timestamp information, and there are many solutions:
158
173
  - Method 1: Use the last git commit time as the last update time, and the first git commit time as the creation (there is a margin of error, but it's acceptable), mkdocs-git-revision-date-localized-plugin does this
159
- - Method 2: You can cache the original time, and then read the cache subsequently. The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is simple, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
174
+ - Method 2: You can cache the original time in advance, and then read the cache subsequently. The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is easier, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
160
175
  - **Difficulty**:
161
176
  1. When to read and store original time? This is just a plugin for mkdocs, with very limited access and permissions, mkdocs provides only build and serve, so in case a user commits directly without executing build or serve (e.g., when using a CI/CD build system), then you won't be able to retrieve the time information of the file, not to mention caching it!
162
177
  - Let's take a straight shot: the Git Hooks mechanism was found, prompted by the AI, which can trigger a custom script when a specific git action occurs, such as every time commit is performed
@@ -167,10 +182,10 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
167
182
  4. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
168
183
  - Workaround: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
169
184
  - **Improve**:
170
- - Since it has been re-developed, it will be designed in the direction of **excellent products**, and the pursuit of the ultimate **ease of use, simplicity and personalization**
171
- - Ease of use: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc
172
- - Simplicity: no unnecessary configurations, the less the simpler, e.g. git account information, repo information, etc., are not required
173
- - Personalization: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
185
+ - Since it's a newly developed plugin, it will be designed in the direction of **excellent products**, and the pursuit of the ultimate **ease of use, simplicity and personalization**
186
+ - **Ease of use**: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc
187
+ - **Simplicity**: no unnecessary configuration, no Git dependencies, no CI/CD configuration dependencies, no other package dependencies
188
+ - **Personalization**: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
174
189
  - In addition, it has good compatibility and extensibility, and works well in WIN7, mobile devices, old Safari, etc
175
190
  - **The Last Secret**:
176
191
  - Programming is a hobby, and I'm a marketer of 8 years (Feel free to leave a comment)
@@ -8,8 +8,8 @@ An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark>
8
8
 
9
9
  ## Features
10
10
 
11
- - Work in any environment, for Git-less environments, CI/CD environments (e.g. GitHub Actions), one-person collaboration, multi-person collaboration, etc
12
- - Support for manually specifying time and author info in `Front Matter`
11
+ - Always display exact meta-info of the document for any environment (no-Git, Git, all CI/CD build systems, etc)
12
+ - Support for manually specifying time and author in `Front Matter`
13
13
  - Support for multiple time formats (date, datetime, timeago)
14
14
  - Support for document exclusion mode
15
15
  - Flexible display position (top or bottom)
@@ -47,15 +47,14 @@ plugins:
47
47
  - document-dates:
48
48
  position: top # Display position: top (after title) bottom (end of document), default: bottom
49
49
  type: date # Date type: date datetime timeago, default: date
50
- locale: en # Localization: zh zh_TW en es fr de ar ja ko ru, default: en
51
- date_format: '%Y-%m-%d' # Date format, supports all python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
52
- time_format: '%H:%M:%S' # Time format (valid only if type=datetime)
50
+ locale: en # Localization: en zh zh_TW es fr de ar ja ko ru, default: en
51
+ date_format: '%Y-%m-%d' # Date format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
52
+ time_format: '%H:%M:%S' # Time format strings (valid only if type=datetime)
53
53
  exclude: # List of excluded files
54
54
  - temp.md # Exclude specific file
55
55
  - private/* # Exclude all files in private directory, including subdirectories
56
- - drafts/*.md # Exclude all markdown files in the current directory drafts, but not subdirectories
57
56
 
58
- show_author: true # Show author or not: true false, default: true
57
+ show_author: true # Show author or not, default: true
59
58
 
60
59
  ```
61
60
 
@@ -63,7 +62,7 @@ plugins:
63
62
 
64
63
  The plugin will automatically get the exact time of the document, will automatically cache the creation time, but of course, you can also specify it manually in `Front Matter`
65
64
 
66
- Priority: `Front Matter` > `Cache Files` > `File System Timestamps`
65
+ Priority order: `Front Matter` > `Cache Files` > `File System Timestamps`
67
66
 
68
67
  ```yaml
69
68
  ---
@@ -81,7 +80,7 @@ modified: 2025-02-23
81
80
 
82
81
  The plugin will automatically get the author of the document, will parse the email and make a link, also you can specify it manually in `Front Matter`
83
82
 
84
- Priority: `Front Matter` > `Git Author Info` > `PC Username`
83
+ Priority order: `Front Matter` > `Git Author` > `site_author (mkdocs.yml)` > `PC Username`
85
84
 
86
85
  ```yaml
87
86
  ---
@@ -97,26 +96,42 @@ email: e-name@gmail.com
97
96
 
98
97
  ## Customization
99
98
 
100
- The plugin supports deep customization, such as icon style, font style, theme color, animation type, dividing line, etc. All of it can be customized by modifying the code in the corresponding file (I've already written the code and comments, you just need to turn on the switch and change the value):
99
+ The plugin supports deep customization, such as **icon style, font style, theme color, animation type, dividing line**, etc. All of it can be customized by modifying the preset values in the corresponding file (I've already written the code and comments, you just need to turn on the switch and change the value):
101
100
 
102
- - Style & Theme: `docs/assets/document_dates/user.config.css`
103
- - Properties & Animations: `docs/assets/document_dates/user.config.js`
104
- - Localized languages: `docs/assets/document_dates/languages/` , refer to the template file `en.json` for any additions or modifications
105
- - timeago.js localization: `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
106
- - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
107
- - In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
108
- ```yaml
109
- extra_javascript:
110
- - assets/document_dates/core/timeago.full.min.js
111
- - assets/document_dates/core/timeago-load.js
112
- ```
101
+ | Function: | Location: |
102
+ | :----------------------: | ---------------------------------------- |
103
+ | **Style & Theme** | `docs/assets/document_dates/user.config.css` |
104
+ | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
105
+ | **Localized languages** | `docs/assets/document_dates/languages/` <br />refer to the template file `en.json` for any additions or modifications |
106
+
107
+ **Tip**: when `type: timeago` is set, timeago.js is enabled to render time dynamically, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
108
+
109
+ - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
110
+ - In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
111
+ ```yaml
112
+ extra_javascript:
113
+ - assets/document_dates/core/timeago.full.min.js
114
+ - assets/document_dates/core/timeago-load.js
115
+ ```
116
+
117
+ **Demo Images**:
118
+
119
+ ![01-default-w](mkdocs_document_dates/demo_images/01-default-w.png)
120
+ ![02-change-icon](mkdocs_document_dates/demo_images/02-change-icon.png)
121
+ ![02-change-icon-color](mkdocs_document_dates/demo_images/02-change-icon-color.png)
122
+ ![04-default-pop-up](mkdocs_document_dates/demo_images/04-default-pop-up.png)
123
+ ![05-change-theme](mkdocs_document_dates/demo_images/05-change-theme.png)
124
+
125
+ ![06-change-theme](mkdocs_document_dates/demo_images/06-change-theme.png)
126
+ ![07-pop-up-from-top](mkdocs_document_dates/demo_images/07-pop-up-from-top.png)
127
+ ![08-pop-up-from-bottom](mkdocs_document_dates/demo_images/08-pop-up-from-bottom.png)
113
128
 
114
129
  ## Other Tips
115
130
 
116
- - In order to get the exact creation time, a separate cache file is used to store the creation time of the file, located in the doc folder (hidden by default), please don't delete it:
131
+ - In order to always get the exact creation time, a separate cache file is used to store the creation time of the document, located in the docs folder (hidden by default), please don't delete it:
117
132
  - `docs/.dates_cache.jsonl`, cache file
118
133
  - `docs/.gitattributes`, merge mechanism for cache file
119
- - The Git Hooks mechanism is used to automatically trigger the storing of the cache (on each git commit), and the cached file is automatically committed along with it. In addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
134
+ - The Git Hooks mechanism is used to automatically trigger the storing of the cache (on each git commit), and the cached file is automatically committed along with it, in addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
120
135
 
121
136
  <br />
122
137
 
@@ -125,11 +140,11 @@ The plugin supports deep customization, such as icon style, font style, theme co
125
140
  A dispensable, insignificant little plug-in, friends who have time can take a look \^\_\^
126
141
 
127
142
  - **Origin**:
128
- - Because [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin), a great project. When I used it at the end of 2024, I found that I couldn't use it locally because my mkdocs documentation was not included in git management, then I don't understand why not read the file system time, but to use the git time, and raised an issue to the author, but didn't get a reply for about a week (the author had a reply later, nice guy, I guess he was busy at the time), and then I thought, there is nothing to do during the Chinese New Year, and now AI is so hot, why not with the help of the AI try it out for myself, it was born, born in February 2025
143
+ - Because [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin), a great project. When I used it at the end of 2024, I found that I couldn't use it locally because my mkdocs documentation was not included in git management, I don't understand why not read the file system time, but to use the git time, and the filesystem time is more accurate, then raised an issue to the author, but didn't get a reply for about a week (the author had a reply later, nice guy, I guess he was busy at the time), and then I thought, there is nothing to do during the Chinese New Year, and now AI is so hot, why not with the help of the AI try it out for myself, it was born, born in February 2025
129
144
  - **Iteration**:
130
145
  - After development, I understood why not use filesystem time, because files will be rebuilt when they go through git checkout or clone, resulting in the loss of original timestamp information, and there are many solutions:
131
146
  - Method 1: Use the last git commit time as the last update time, and the first git commit time as the creation (there is a margin of error, but it's acceptable), mkdocs-git-revision-date-localized-plugin does this
132
- - Method 2: You can cache the original time, and then read the cache subsequently. The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is simple, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
147
+ - Method 2: You can cache the original time in advance, and then read the cache subsequently. The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is easier, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
133
148
  - **Difficulty**:
134
149
  1. When to read and store original time? This is just a plugin for mkdocs, with very limited access and permissions, mkdocs provides only build and serve, so in case a user commits directly without executing build or serve (e.g., when using a CI/CD build system), then you won't be able to retrieve the time information of the file, not to mention caching it!
135
150
  - Let's take a straight shot: the Git Hooks mechanism was found, prompted by the AI, which can trigger a custom script when a specific git action occurs, such as every time commit is performed
@@ -140,10 +155,10 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
140
155
  4. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
141
156
  - Workaround: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
142
157
  - **Improve**:
143
- - Since it has been re-developed, it will be designed in the direction of **excellent products**, and the pursuit of the ultimate **ease of use, simplicity and personalization**
144
- - Ease of use: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc
145
- - Simplicity: no unnecessary configurations, the less the simpler, e.g. git account information, repo information, etc., are not required
146
- - Personalization: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
158
+ - Since it's a newly developed plugin, it will be designed in the direction of **excellent products**, and the pursuit of the ultimate **ease of use, simplicity and personalization**
159
+ - **Ease of use**: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc
160
+ - **Simplicity**: no unnecessary configuration, no Git dependencies, no CI/CD configuration dependencies, no other package dependencies
161
+ - **Personalization**: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
147
162
  - In addition, it has good compatibility and extensibility, and works well in WIN7, mobile devices, old Safari, etc
148
163
  - **The Last Secret**:
149
164
  - Programming is a hobby, and I'm a marketer of 8 years (Feel free to leave a comment)
@@ -56,9 +56,9 @@ def get_git_first_commit_time(file_path):
56
56
  # git log --reverse --format="%aI" --date=iso -- {file_path} | head -n 1
57
57
  result = subprocess.run(['git', 'log', '--reverse', '--format=%aI', '--', file_path], capture_output=True, text=True)
58
58
  if result.returncode == 0:
59
- commits = result.stdout.strip().split('\n')
60
- if commits and commits[0]:
61
- return datetime.fromisoformat(commits[0]).replace(tzinfo=None)
59
+ first_line = result.stdout.partition('\n')[0].strip()
60
+ if first_line:
61
+ return datetime.fromisoformat(first_line).replace(tzinfo=None)
62
62
  except Exception as e:
63
63
  logging.info(f"Error getting git first commit time for {file_path}: {e}")
64
64
  return None
@@ -163,7 +163,7 @@ def update_cache():
163
163
  cmd = ["git", "ls-files", "*.md"]
164
164
  result = subprocess.run(cmd, cwd=docs_dir, capture_output=True, text=True, check=True)
165
165
  tracked_files = result.stdout.splitlines() if result.stdout else []
166
-
166
+
167
167
  if not tracked_files:
168
168
  logging.info(f"No tracked markdown files found in {docs_dir}")
169
169
  continue
@@ -175,17 +175,17 @@ def update_cache():
175
175
  # 读取新的JSONL缓存文件(如果存在)
176
176
  jsonl_cache_file = docs_dir / '.dates_cache.jsonl'
177
177
  jsonl_dates_cache = read_jsonl_cache(jsonl_cache_file)
178
-
178
+
179
179
  # 根据 git已跟踪的文件来更新
180
180
  for file_path in tracked_files:
181
181
  try:
182
182
  rel_path = file_path
183
183
  full_path = docs_dir / rel_path
184
-
184
+
185
185
  # 如果文件已在JSONL缓存中,跳过
186
186
  if rel_path in jsonl_dates_cache:
187
187
  continue
188
-
188
+
189
189
  # 处理新文件或迁移旧JSON缓存
190
190
  if rel_path in json_dates_cache:
191
191
  jsonl_dates_cache[rel_path] = json_dates_cache[rel_path]
@@ -6,7 +6,6 @@ import logging
6
6
  import subprocess
7
7
  from datetime import datetime
8
8
  from pathlib import Path
9
- from typing import Union, List
10
9
  from mkdocs.plugins import BasePlugin
11
10
  from mkdocs.config import config_options
12
11
 
@@ -38,7 +37,7 @@ class Author:
38
37
  class DocumentDatesPlugin(BasePlugin):
39
38
  config_scheme = (
40
39
  ('type', config_options.Type(str, default='date')),
41
- ('locale', config_options.Type(str, default='en')),
40
+ ('locale', config_options.Type(str, default=None)),
42
41
  ('date_format', config_options.Type(str, default='%Y-%m-%d')),
43
42
  ('time_format', config_options.Type(str, default='%H:%M:%S')),
44
43
  ('position', config_options.Type(str, default='bottom')),
@@ -59,7 +58,13 @@ class DocumentDatesPlugin(BasePlugin):
59
58
  self.is_git_repo = False
60
59
 
61
60
  def on_config(self, config):
62
-
61
+ try:
62
+ # 设置 locale 在无配置时跟随主题语言
63
+ if not self.config['locale']:
64
+ self.config['locale'] = config['theme']['language']
65
+ except Exception:
66
+ self.config['locale'] = 'en'
67
+
63
68
  # 检查是否为 Git 仓库
64
69
  try:
65
70
  check_git = subprocess.run(['git', 'rev-parse', '--is-inside-work-tree'], capture_output=True, text=True)
@@ -127,7 +132,7 @@ class DocumentDatesPlugin(BasePlugin):
127
132
  https://unpkg.com/tippy.js@6/themes/material.css
128
133
  """
129
134
  # 复制静态资源到用户目录
130
- dest_dir = docs_dir_path / 'assets/document_dates'
135
+ dest_dir = docs_dir_path / 'assets' / 'document_dates'
131
136
  dest_dir.mkdir(parents=True, exist_ok=True)
132
137
 
133
138
  for dir_name in ['tippy', 'core']:
@@ -138,7 +143,7 @@ class DocumentDatesPlugin(BasePlugin):
138
143
  # 复制配置文件模板到用户目录(如果不存在)
139
144
  config_files = ['user.config.css', 'user.config.js']
140
145
  for config_file in config_files:
141
- source_config = Path(__file__).parent / 'static/config' / config_file
146
+ source_config = Path(__file__).parent / 'static' / 'config' / config_file
142
147
  target_config = dest_dir / config_file
143
148
  if not target_config.exists():
144
149
  shutil.copy2(source_config, target_config)
@@ -175,10 +180,14 @@ class DocumentDatesPlugin(BasePlugin):
175
180
  return config
176
181
 
177
182
  def on_page_markdown(self, markdown, page, config, files):
178
- # 获取文件的绝对路径和相对路径
179
183
  file_path = page.file.abs_src_path
180
- rel_path = page.file.src_path
181
-
184
+ # 获取相对路径,src_uri 总是以"/"分隔
185
+ rel_path = getattr(page.file, 'src_uri', None)
186
+ if not rel_path:
187
+ rel_path = page.file.src_path
188
+ if os.sep != '/':
189
+ rel_path = rel_path.replace(os.sep, '/')
190
+
182
191
  # 检查是否需要排除
183
192
  if self._is_excluded(rel_path):
184
193
  return markdown
@@ -199,7 +208,11 @@ class DocumentDatesPlugin(BasePlugin):
199
208
  if not author:
200
209
  author = self._get_git_authors(file_path)
201
210
  if not author:
202
- author = self._get_local_author()
211
+ # mkdocs.yml 中的 site_author
212
+ if config.get('site_author'):
213
+ author = Author(name=config.get('site_author'))
214
+ else:
215
+ author = self._get_local_author()
203
216
 
204
217
  # 生成日期和作者信息 HTML
205
218
  info_html = self._generate_html_info(created, modified, author)
@@ -240,37 +253,21 @@ class DocumentDatesPlugin(BasePlugin):
240
253
  logging.error(f"Error loading language file {locale_file}: {str(e)}")
241
254
 
242
255
 
243
- def _is_excluded(self, rel_path) -> bool:
256
+ def _is_excluded(self, rel_path):
244
257
  for pattern in self.config['exclude']:
258
+ # if fnmatch.fnmatch(rel_path, pattern):
245
259
  if self._matches_exclude_pattern(rel_path, pattern):
246
260
  return True
247
261
  return False
248
262
 
249
- def _matches_exclude_pattern(self, rel_path, pattern) -> bool:
250
- try:
251
- # 情况1:匹配具体文件路径
252
- if '*' not in pattern:
253
- return rel_path == pattern
254
-
255
- # 情况2:匹配目录下所有文件(包含子目录)
256
- if pattern.endswith('/*'):
257
- return rel_path.startswith(pattern[:-1])
258
-
259
- # 情况3:匹配指定目录下的特定类型文件(不包含子目录)
260
- if '*.' in pattern:
261
- pattern_path = Path(pattern)
262
- rel_path_obj = Path(rel_path)
263
- pattern_dir = pattern_path.parent
264
- pattern_suffix = pattern_path.name[1:] # 去掉 * 号
265
- return (rel_path_obj.parent == pattern_dir and
266
- rel_path_obj.name.endswith(pattern_suffix))
263
+ def _matches_exclude_pattern(self, rel_path, pattern):
264
+ if '*' not in pattern:
265
+ return rel_path == pattern
266
+ else:
267
+ return rel_path.startswith(pattern.partition('*')[0])
267
268
 
268
- return False
269
- except ValueError:
270
- return False
271
269
 
272
-
273
- def _find_meta_date(self, meta: dict, field_names: list) -> Union[datetime, None]:
270
+ def _find_meta_date(self, meta, field_names):
274
271
  for field in field_names:
275
272
  if field in meta:
276
273
  try:
@@ -287,9 +284,9 @@ class DocumentDatesPlugin(BasePlugin):
287
284
  # git log --reverse --format="%aI" --date=iso -- {file_path} | head -n 1
288
285
  result = subprocess.run(['git', 'log', '--reverse', '--format=%aI', '--', file_path], capture_output=True, text=True)
289
286
  if result.returncode == 0:
290
- commits = result.stdout.strip().split('\n')
291
- if commits and commits[0]:
292
- return datetime.fromisoformat(commits[0]).replace(tzinfo=None)
287
+ first_line = result.stdout.partition('\n')[0].strip()
288
+ if first_line:
289
+ return datetime.fromisoformat(first_line).replace(tzinfo=None)
293
290
  except Exception as e:
294
291
  logging.warning(f"Error getting git first commit time for {file_path}: {e}")
295
292
  return None
@@ -379,7 +376,7 @@ class DocumentDatesPlugin(BasePlugin):
379
376
  logging.warning(f"Error processing author meta: {e}")
380
377
  return None
381
378
 
382
- def _get_git_authors(self, file_path: str) -> Union[Author, List[Author], None]:
379
+ def _get_git_authors(self, file_path):
383
380
  if not self.is_git_repo:
384
381
  return None
385
382
  try:
@@ -397,19 +394,16 @@ class DocumentDatesPlugin(BasePlugin):
397
394
  if git_log_result.returncode != 0 or not git_log_result.stdout.strip():
398
395
  return None
399
396
 
400
- authors = []
401
- unique_entries = set()
402
- for line in git_log_result.stdout.strip().splitlines():
403
- if not line or line in unique_entries:
397
+ # 使用字典去重和存储作者
398
+ authors_map = {}
399
+ for line in git_log_result.stdout.splitlines():
400
+ if not line.strip() or line in authors_map:
404
401
  continue
405
- unique_entries.add(line)
406
402
  name, email = line.split('|')
407
- authors.append(Author(name=name, email=email))
408
-
409
- if not authors:
410
- return None
411
-
412
- return authors[0] if len(authors) == 1 else authors
403
+ authors_map[line] = Author(name=name, email=email)
404
+
405
+ authors = list(authors_map.values())
406
+ return authors[0] if len(authors) == 1 else authors or None
413
407
  except Exception as e:
414
408
  logging.warning(f"Failed to get git author info: {str(e)}")
415
409
  return None
@@ -3,7 +3,7 @@
3
3
  */
4
4
  /*
5
5
  .document-dates-plugin {
6
- color: rgba(142, 142, 142, 0.7);
6
+ color: rgba(109, 157, 204, 0.7);
7
7
  font-size: 0.75rem;
8
8
  }
9
9
  .document-dates-plugin .material-icons {
@@ -13,7 +13,7 @@
13
13
  /* Customized icons, just change the icon name.
14
14
  Google Fonts Icons (2500+): https://fonts.google.com/icons
15
15
 
16
- add_circle: add_circle, add_circle, note_add, add
16
+ add_circle: add_circle, add_circle, note_add, more_time
17
17
  update: update, check_circle, task, refresh
18
18
  person: person, account_circle
19
19
  group: group, groups */
@@ -50,10 +50,6 @@
50
50
  including theme, arrow, font, color, background color, etc
51
51
  */
52
52
 
53
- /* .tippy-box {
54
- font-size: 12px;
55
- } */
56
-
57
53
  /* Demo of the custom theme 'sorrel' and 'sublime', you can configure it in user.config.js (optional) */
58
54
  /*
59
55
  .tippy-box[data-theme~='sorrel'] {
@@ -1,8 +1,14 @@
1
1
  /*
2
- Configuration Override
2
+ Configuration Overrides for Tooltip
3
3
  see: https://atomiks.github.io/tippyjs/
4
4
  */
5
5
 
6
+ /* Configure one by one: */
7
+ // tippy_config.theme.light = 'tomato';
8
+ // tippy_config.tooltip.placement = 'top';
9
+ // tippy_config.tooltip.arrow = false;
10
+
11
+ /* Or, override all configuration items: */
6
12
  /*
7
13
  DocumentDates.setConfig({
8
14
  theme: {
@@ -27,11 +33,10 @@ DocumentDates.setConfig({
27
33
  });
28
34
  */
29
35
 
30
-
31
36
  /*
32
- Hook System
33
- The hook system allows users to execute custom logic at specific times,
34
- such as adding custom interactions before initialization and after initialization.
37
+ Hook System of Tooltip
38
+ The hook system allows you to execute custom logic at specific times,
39
+ such as adding custom interactions before the tooltip initialization and after initialization.
35
40
  */
36
41
 
37
42
  /*
@@ -20,7 +20,16 @@ const defaultConfig = {
20
20
  }
21
21
  };
22
22
 
23
- let config = { ...defaultConfig };
23
+ let tippy_config = { ...defaultConfig };
24
+
25
+ // Configuration API
26
+ function setConfig(newConfig) {
27
+ tippy_config = {
28
+ ...defaultConfig,
29
+ ...newConfig
30
+ };
31
+ }
32
+
24
33
 
25
34
 
26
35
  // Hook System
@@ -45,27 +54,19 @@ async function executeHooks(hookName, context) {
45
54
  }
46
55
  }
47
56
 
48
- // Configuration API
49
- function setConfig(newConfig) {
50
- config = {
51
- ...defaultConfig,
52
- ...newConfig
53
- };
54
- }
55
-
56
57
  // Theme management
57
58
  function getCurrentTheme() {
58
59
  const scheme = (document.body && document.body.getAttribute('data-md-color-scheme')) || 'default';
59
- return scheme === 'slate' ? config.theme.dark : config.theme.light;
60
+ return scheme === 'slate' ? tippy_config.theme.dark : tippy_config.theme.light;
60
61
  }
61
62
 
62
63
  // Main initialization
63
64
  async function init() {
64
- await executeHooks('beforeInit', { config });
65
+ await executeHooks('beforeInit', { tippy_config });
65
66
 
66
67
  // Configure the properties of the Tooltip here, available documents: https://atomiks.github.io/tippyjs/
67
68
  const tippyInstances = tippy('[data-tippy-content]', {
68
- ...config.tooltip,
69
+ ...tippy_config.tooltip,
69
70
  theme: getCurrentTheme() // Initialize Tooltip's theme based on Material's light/dark color scheme
70
71
  });
71
72
 
@@ -86,80 +87,28 @@ async function init() {
86
87
  attributeFilter: ['data-md-color-scheme']
87
88
  });
88
89
 
89
- await executeHooks('afterInit', { tippyInstances, observer });
90
- return { tippyInstances, observer };
90
+ await executeHooks('afterInit', { tippyInstances });
91
91
  }
92
92
 
93
-
94
-
95
- const INSTANCE_KEY = Symbol('DocumentDatesInstance');
96
-
97
- class InitManager {
98
- constructor() {
99
- this.initPromise = null;
100
- }
101
-
102
- getInstance() {
103
- if (window[INSTANCE_KEY]) {
104
- return Promise.resolve(window[INSTANCE_KEY]);
93
+ // Singleton Initialization
94
+ const initManager = (() => {
95
+ let initialized = false;
96
+ return {
97
+ initialize() {
98
+ if (initialized) return;
99
+ init();
100
+ initialized = true;
105
101
  }
106
- return this.initialize();
107
- }
108
-
109
- initialize() {
110
- if (this.initPromise) {
111
- return this.initPromise;
112
- }
113
-
114
- this.initPromise = init().then(instance => {
115
- window[INSTANCE_KEY] = instance;
116
- return instance;
117
- });
118
-
119
- return this.initPromise;
120
- }
121
- }
122
-
123
- const initManager = new InitManager();
124
-
125
- function setupInitializationTrigger() {
126
- function checkAndInit() {
127
- if (document.querySelector('[data-tippy-content]')) {
128
- initManager.getInstance();
129
- return true;
130
- }
131
- return false;
132
- }
133
-
134
- if (document.readyState !== 'loading') {
135
- if (checkAndInit()) return;
136
- }
137
-
138
- document.addEventListener('DOMContentLoaded', () => {
139
- if (checkAndInit()) return;
140
-
141
- const observer = new MutationObserver((mutations) => {
142
- if (checkAndInit()) {
143
- observer.disconnect();
144
- }
145
- });
146
-
147
- observer.observe(document.body, {
148
- childList: true,
149
- subtree: true,
150
- attributes: true,
151
- attributeFilter: ['data-tippy-content']
152
- });
153
- });
154
- }
102
+ };
103
+ })();
155
104
 
156
- setupInitializationTrigger();
105
+ // Entrance
106
+ document.addEventListener('DOMContentLoaded', initManager.initialize);
157
107
 
158
108
 
159
109
 
160
110
  // Export API
161
111
  window.DocumentDates = {
162
- init: () => initManager.getInstance(),
163
112
  registerHook,
164
113
  setConfig
165
114
  };
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mkdocs-document-dates
3
- Version: 3.1.3
3
+ Version: 3.1.5
4
4
  Summary: An easy-to-use, lightweight MkDocs plugin for displaying the exact creation time, last modification time and author info of markdown documents.
5
5
  Home-page: https://github.com/jaywhj/mkdocs-document-dates
6
6
  Author: Aaron Wang
@@ -12,7 +12,7 @@ Classifier: Operating System :: OS Independent
12
12
  Requires-Python: >=3.7
13
13
  Description-Content-Type: text/markdown
14
14
  License-File: LICENSE
15
- Requires-Dist: mkdocs>=1.0.0
15
+ Requires-Dist: mkdocs>=1.1.0
16
16
  Dynamic: author
17
17
  Dynamic: author-email
18
18
  Dynamic: classifier
@@ -35,8 +35,8 @@ An easy-to-use, lightweight MkDocs plugin for displaying the <mark>exact</mark>
35
35
 
36
36
  ## Features
37
37
 
38
- - Work in any environment, for Git-less environments, CI/CD environments (e.g. GitHub Actions), one-person collaboration, multi-person collaboration, etc
39
- - Support for manually specifying time and author info in `Front Matter`
38
+ - Always display exact meta-info of the document for any environment (no-Git, Git, all CI/CD build systems, etc)
39
+ - Support for manually specifying time and author in `Front Matter`
40
40
  - Support for multiple time formats (date, datetime, timeago)
41
41
  - Support for document exclusion mode
42
42
  - Flexible display position (top or bottom)
@@ -74,15 +74,14 @@ plugins:
74
74
  - document-dates:
75
75
  position: top # Display position: top (after title) bottom (end of document), default: bottom
76
76
  type: date # Date type: date datetime timeago, default: date
77
- locale: en # Localization: zh zh_TW en es fr de ar ja ko ru, default: en
78
- date_format: '%Y-%m-%d' # Date format, supports all python datetime format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
79
- time_format: '%H:%M:%S' # Time format (valid only if type=datetime)
77
+ locale: en # Localization: en zh zh_TW es fr de ar ja ko ru, default: en
78
+ date_format: '%Y-%m-%d' # Date format strings, e.g., %Y-%m-%d, %b %d, %Y, etc
79
+ time_format: '%H:%M:%S' # Time format strings (valid only if type=datetime)
80
80
  exclude: # List of excluded files
81
81
  - temp.md # Exclude specific file
82
82
  - private/* # Exclude all files in private directory, including subdirectories
83
- - drafts/*.md # Exclude all markdown files in the current directory drafts, but not subdirectories
84
83
 
85
- show_author: true # Show author or not: true false, default: true
84
+ show_author: true # Show author or not, default: true
86
85
 
87
86
  ```
88
87
 
@@ -90,7 +89,7 @@ plugins:
90
89
 
91
90
  The plugin will automatically get the exact time of the document, will automatically cache the creation time, but of course, you can also specify it manually in `Front Matter`
92
91
 
93
- Priority: `Front Matter` > `Cache Files` > `File System Timestamps`
92
+ Priority order: `Front Matter` > `Cache Files` > `File System Timestamps`
94
93
 
95
94
  ```yaml
96
95
  ---
@@ -108,7 +107,7 @@ modified: 2025-02-23
108
107
 
109
108
  The plugin will automatically get the author of the document, will parse the email and make a link, also you can specify it manually in `Front Matter`
110
109
 
111
- Priority: `Front Matter` > `Git Author Info` > `PC Username`
110
+ Priority order: `Front Matter` > `Git Author` > `site_author (mkdocs.yml)` > `PC Username`
112
111
 
113
112
  ```yaml
114
113
  ---
@@ -124,26 +123,42 @@ email: e-name@gmail.com
124
123
 
125
124
  ## Customization
126
125
 
127
- The plugin supports deep customization, such as icon style, font style, theme color, animation type, dividing line, etc. All of it can be customized by modifying the code in the corresponding file (I've already written the code and comments, you just need to turn on the switch and change the value):
126
+ The plugin supports deep customization, such as **icon style, font style, theme color, animation type, dividing line**, etc. All of it can be customized by modifying the preset values in the corresponding file (I've already written the code and comments, you just need to turn on the switch and change the value):
128
127
 
129
- - Style & Theme: `docs/assets/document_dates/user.config.css`
130
- - Properties & Animations: `docs/assets/document_dates/user.config.js`
131
- - Localized languages: `docs/assets/document_dates/languages/` , refer to the template file `en.json` for any additions or modifications
132
- - timeago.js localization: `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
133
- - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
134
- - In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
135
- ```yaml
136
- extra_javascript:
137
- - assets/document_dates/core/timeago.full.min.js
138
- - assets/document_dates/core/timeago-load.js
139
- ```
128
+ | Function: | Location: |
129
+ | :----------------------: | ---------------------------------------- |
130
+ | **Style & Theme** | `docs/assets/document_dates/user.config.css` |
131
+ | **Properties & Functions** | `docs/assets/document_dates/user.config.js` |
132
+ | **Localized languages** | `docs/assets/document_dates/languages/` <br />refer to the template file `en.json` for any additions or modifications |
133
+
134
+ **Tip**: when `type: timeago` is set, timeago.js is enabled to render time dynamically, `timeago.min.js` only contains English and Chinese by default, if you need to load other languages, you can configure it as below (choose one):
135
+
136
+ - In `user.config.js`, refer to [the demo commented out](https://github.com/jaywhj/mkdocs-document-dates/blob/main/mkdocs_document_dates/static/config/user.config.js) at the bottom, translate it into your local language
137
+ - In `mkdocs.yml`, add the following two lines to configure the full version of `timeago.full.min.js` to load all languages at once
138
+ ```yaml
139
+ extra_javascript:
140
+ - assets/document_dates/core/timeago.full.min.js
141
+ - assets/document_dates/core/timeago-load.js
142
+ ```
143
+
144
+ **Demo Images**:
145
+
146
+ ![01-default-w](mkdocs_document_dates/demo_images/01-default-w.png)
147
+ ![02-change-icon](mkdocs_document_dates/demo_images/02-change-icon.png)
148
+ ![02-change-icon-color](mkdocs_document_dates/demo_images/02-change-icon-color.png)
149
+ ![04-default-pop-up](mkdocs_document_dates/demo_images/04-default-pop-up.png)
150
+ ![05-change-theme](mkdocs_document_dates/demo_images/05-change-theme.png)
151
+
152
+ ![06-change-theme](mkdocs_document_dates/demo_images/06-change-theme.png)
153
+ ![07-pop-up-from-top](mkdocs_document_dates/demo_images/07-pop-up-from-top.png)
154
+ ![08-pop-up-from-bottom](mkdocs_document_dates/demo_images/08-pop-up-from-bottom.png)
140
155
 
141
156
  ## Other Tips
142
157
 
143
- - In order to get the exact creation time, a separate cache file is used to store the creation time of the file, located in the doc folder (hidden by default), please don't delete it:
158
+ - In order to always get the exact creation time, a separate cache file is used to store the creation time of the document, located in the docs folder (hidden by default), please don't delete it:
144
159
  - `docs/.dates_cache.jsonl`, cache file
145
160
  - `docs/.gitattributes`, merge mechanism for cache file
146
- - The Git Hooks mechanism is used to automatically trigger the storing of the cache (on each git commit), and the cached file is automatically committed along with it. In addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
161
+ - The Git Hooks mechanism is used to automatically trigger the storing of the cache (on each git commit), and the cached file is automatically committed along with it, in addition, the installation of Git Hooks is automatically triggered when the plugin is installed, without any manual intervention!
147
162
 
148
163
  <br />
149
164
 
@@ -152,11 +167,11 @@ The plugin supports deep customization, such as icon style, font style, theme co
152
167
  A dispensable, insignificant little plug-in, friends who have time can take a look \^\_\^
153
168
 
154
169
  - **Origin**:
155
- - Because [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin), a great project. When I used it at the end of 2024, I found that I couldn't use it locally because my mkdocs documentation was not included in git management, then I don't understand why not read the file system time, but to use the git time, and raised an issue to the author, but didn't get a reply for about a week (the author had a reply later, nice guy, I guess he was busy at the time), and then I thought, there is nothing to do during the Chinese New Year, and now AI is so hot, why not with the help of the AI try it out for myself, it was born, born in February 2025
170
+ - Because [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin), a great project. When I used it at the end of 2024, I found that I couldn't use it locally because my mkdocs documentation was not included in git management, I don't understand why not read the file system time, but to use the git time, and the filesystem time is more accurate, then raised an issue to the author, but didn't get a reply for about a week (the author had a reply later, nice guy, I guess he was busy at the time), and then I thought, there is nothing to do during the Chinese New Year, and now AI is so hot, why not with the help of the AI try it out for myself, it was born, born in February 2025
156
171
  - **Iteration**:
157
172
  - After development, I understood why not use filesystem time, because files will be rebuilt when they go through git checkout or clone, resulting in the loss of original timestamp information, and there are many solutions:
158
173
  - Method 1: Use the last git commit time as the last update time, and the first git commit time as the creation (there is a margin of error, but it's acceptable), mkdocs-git-revision-date-localized-plugin does this
159
- - Method 2: You can cache the original time, and then read the cache subsequently. The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is simple, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
174
+ - Method 2: You can cache the original time in advance, and then read the cache subsequently. The cache can be in Front Matter of the source document or in a separate file, I chose the latter. Storing in Front Matter makes sense and is easier, but this will modify the source content of the document, although it doesn't have any impact on the body, but I still want to ensure the originality of the data!
160
175
  - **Difficulty**:
161
176
  1. When to read and store original time? This is just a plugin for mkdocs, with very limited access and permissions, mkdocs provides only build and serve, so in case a user commits directly without executing build or serve (e.g., when using a CI/CD build system), then you won't be able to retrieve the time information of the file, not to mention caching it!
162
177
  - Let's take a straight shot: the Git Hooks mechanism was found, prompted by the AI, which can trigger a custom script when a specific git action occurs, such as every time commit is performed
@@ -167,10 +182,10 @@ A dispensable, insignificant little plug-in, friends who have time can take a lo
167
182
  4. How can I ensure that a single cache file does not conflict when collaborating with multi-person?
168
183
  - Workaround: use JSONL (JSON Lines) instead of JSON, and with the merge strategy 'merge=union'
169
184
  - **Improve**:
170
- - Since it has been re-developed, it will be designed in the direction of **excellent products**, and the pursuit of the ultimate **ease of use, simplicity and personalization**
171
- - Ease of use: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc
172
- - Simplicity: no unnecessary configurations, the less the simpler, e.g. git account information, repo information, etc., are not required
173
- - Personalization: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
185
+ - Since it's a newly developed plugin, it will be designed in the direction of **excellent products**, and the pursuit of the ultimate **ease of use, simplicity and personalization**
186
+ - **Ease of use**: don't let users do things manually if you can, e.g., auto-install Git Hooks, auto-cache, auto-commit, provide customized templates, etc
187
+ - **Simplicity**: no unnecessary configuration, no Git dependencies, no CI/CD configuration dependencies, no other package dependencies
188
+ - **Personalization**: almost everything can be customized, whether it's icons, styles, themes, or features, it's all fully customizable
174
189
  - In addition, it has good compatibility and extensibility, and works well in WIN7, mobile devices, old Safari, etc
175
190
  - **The Last Secret**:
176
191
  - Programming is a hobby, and I'm a marketer of 8 years (Feel free to leave a comment)
@@ -30,7 +30,7 @@ try:
30
30
  except FileNotFoundError:
31
31
  long_description = "An easy-to-use, lightweight MkDocs plugin for displaying the exact creation time, last modification time and author info of markdown documents."
32
32
 
33
- VERSION = '3.1.3'
33
+ VERSION = '3.1.5'
34
34
 
35
35
  setup(
36
36
  name="mkdocs-document-dates",
@@ -44,7 +44,7 @@ setup(
44
44
  url="https://github.com/jaywhj/mkdocs-document-dates",
45
45
  packages=find_packages(),
46
46
  install_requires=[
47
- 'mkdocs>=1.0.0',
47
+ 'mkdocs>=1.1.0',
48
48
  ],
49
49
  classifiers=[
50
50
  "Programming Language :: Python :: 3",