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.
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/PKG-INFO +46 -31
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/README.md +44 -29
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/cache_manager.py +7 -7
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/plugin.py +42 -48
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/config/user.config.css +2 -6
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/config/user.config.js +10 -5
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/core.js +26 -77
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/PKG-INFO +46 -31
- mkdocs_document_dates-3.1.5/mkdocs_document_dates.egg-info/requires.txt +1 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/setup.py +2 -2
- mkdocs_document_dates-3.1.3/mkdocs_document_dates.egg-info/requires.txt +0 -1
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/LICENSE +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/__init__.py +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/hooks/pre-commit +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/hooks_installer.py +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/core.css +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/timeago-load.js +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/timeago.full.min.js +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/core/timeago.min.js +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/ar.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/de.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/en.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/es.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/fr.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/ja.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/ko.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/ru.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/zh.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/languages/zh_TW.json +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/backdrop.css +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/light.css +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/material.css +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/popper.min.js +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/scale.css +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/shift-away.css +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/tippy.css +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/static/tippy/tippy.umd.min.js +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/SOURCES.txt +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/dependency_links.txt +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/entry_points.txt +0 -0
- {mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/top_level.txt +0 -0
- {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
|
+
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.
|
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
|
-
-
|
39
|
-
- Support for manually specifying time and author
|
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
|
78
|
-
date_format: '%Y-%m-%d' # Date format
|
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
|
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
|
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
|
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
|
-
|
130
|
-
|
131
|
-
|
132
|
-
|
133
|
-
|
134
|
-
|
135
|
-
|
136
|
-
|
137
|
-
|
138
|
-
|
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
|
+

|
147
|
+

|
148
|
+

|
149
|
+

|
150
|
+

|
151
|
+
|
152
|
+

|
153
|
+

|
154
|
+

|
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
|
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
|
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,
|
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
|
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
|
171
|
-
- Ease of use
|
172
|
-
- Simplicity
|
173
|
-
- Personalization
|
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
|
-
-
|
12
|
-
- Support for manually specifying time and author
|
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
|
51
|
-
date_format: '%Y-%m-%d' # Date format
|
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
|
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
|
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
|
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
|
-
|
103
|
-
|
104
|
-
|
105
|
-
|
106
|
-
|
107
|
-
|
108
|
-
|
109
|
-
|
110
|
-
|
111
|
-
|
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
|
+

|
120
|
+

|
121
|
+

|
122
|
+

|
123
|
+

|
124
|
+
|
125
|
+

|
126
|
+

|
127
|
+

|
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
|
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
|
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,
|
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
|
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
|
144
|
-
- Ease of use
|
145
|
-
- Simplicity
|
146
|
-
- Personalization
|
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)
|
{mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/cache_manager.py
RENAMED
@@ -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
|
-
|
60
|
-
if
|
61
|
-
return datetime.fromisoformat(
|
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=
|
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
|
-
|
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
|
-
|
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)
|
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)
|
250
|
-
|
251
|
-
|
252
|
-
|
253
|
-
|
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
|
-
|
291
|
-
if
|
292
|
-
return datetime.fromisoformat(
|
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
|
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
|
-
|
401
|
-
|
402
|
-
for line in git_log_result.stdout.
|
403
|
-
if not line or line in
|
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
|
-
|
408
|
-
|
409
|
-
|
410
|
-
|
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(
|
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,
|
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
|
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
|
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
|
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' ?
|
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', {
|
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
|
-
...
|
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
|
90
|
-
return { tippyInstances, observer };
|
90
|
+
await executeHooks('afterInit', { tippyInstances });
|
91
91
|
}
|
92
92
|
|
93
|
-
|
94
|
-
|
95
|
-
|
96
|
-
|
97
|
-
|
98
|
-
|
99
|
-
|
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
|
-
|
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
|
-
|
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
|
};
|
{mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates.egg-info/PKG-INFO
RENAMED
@@ -1,6 +1,6 @@
|
|
1
1
|
Metadata-Version: 2.4
|
2
2
|
Name: mkdocs-document-dates
|
3
|
-
Version: 3.1.
|
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.
|
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
|
-
-
|
39
|
-
- Support for manually specifying time and author
|
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
|
78
|
-
date_format: '%Y-%m-%d' # Date format
|
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
|
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
|
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
|
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
|
-
|
130
|
-
|
131
|
-
|
132
|
-
|
133
|
-
|
134
|
-
|
135
|
-
|
136
|
-
|
137
|
-
|
138
|
-
|
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
|
+

|
147
|
+

|
148
|
+

|
149
|
+

|
150
|
+

|
151
|
+
|
152
|
+

|
153
|
+

|
154
|
+

|
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
|
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
|
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,
|
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
|
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
|
171
|
-
- Ease of use
|
172
|
-
- Simplicity
|
173
|
-
- Personalization
|
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)
|
@@ -0,0 +1 @@
|
|
1
|
+
mkdocs>=1.1.0
|
@@ -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.
|
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.
|
47
|
+
'mkdocs>=1.1.0',
|
48
48
|
],
|
49
49
|
classifiers=[
|
50
50
|
"Programming Language :: Python :: 3",
|
@@ -1 +0,0 @@
|
|
1
|
-
mkdocs>=1.0.0
|
File without changes
|
{mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/__init__.py
RENAMED
File without changes
|
{mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/hooks/pre-commit
RENAMED
File without changes
|
{mkdocs_document_dates-3.1.3 → mkdocs_document_dates-3.1.5}/mkdocs_document_dates/hooks_installer.py
RENAMED
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|
File without changes
|