You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[MkDocs](https://www.mkdocs.org/) plugin that enables displaying the date of the last git modification of a page. The plugin uses [babel](https://github.com/python-babel/babel/tree/master/babel) and [timeago.js](https://github.com/hustcc/timeago.js) to provide different localized date formats. Initial fork from [mkdocs-git-revision-date-plugin](https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin).
(*Example when used together with the [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme*)
16
16
@@ -32,146 +32,26 @@ plugins:
32
32
33
33
> If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin. MkDocs enables it by default if there is no `plugins` entry set.
34
34
35
+
If you use the [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) theme, you should already see the last revision on the bottom of your pages.
36
+
35
37
### Note when using build environments
36
38
37
39
This plugin needs access to the last commit that touched a specific file to be able to retrieve the date. By default many build environments only retrieve the last commit, which means you might need to:
38
-
<details>
39
-
<summary>Change your CI settings</summary>
40
-
41
-
- github actions: set `fetch_depth` to `0` ([docs](https://github.com/actions/checkout))
42
-
- gitlab runners: set `GIT_DEPTH` to `0` ([docs](https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone))
43
-
- bitbucket pipelines: set `clone: depth: full` ([docs](https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/))
44
-
</details>
45
-
46
-
47
-
## Usage
48
-
49
-
### In supported themes
50
-
51
-
- [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) offers native support for this plugin, see [setup instructions](https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#revision-date-localized)
52
-
53
-
### In markdown pages
54
-
55
-
In your markdown files you can use the `{{ git_revision_date_localized }}` tag anywhere you'd like:
56
-
57
-
```django hljs
58
-
Last update: {{ git_revision_date_localized }}
59
-
```
60
-
61
-
### Extending existing themes
62
-
63
-
You can [customize an existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme) by overriding blocks or partials and using the `page.meta.git_revision_date_localized` tag.
64
-
65
-
To add a revision date to the default `mkdocs` theme, add a `overrides/partials` folder to your `docs` folder and update your `mkdocs.yml` file:
66
-
67
-
```yml
68
-
theme:
69
-
name: mkdocs
70
-
custom_dir: docs/overrides
71
-
```
72
-
73
-
And then add a new file `docs/overrides/content.html` with the following content:
74
40
75
41
<details>
76
-
<summary>content.html</summary>
77
-
78
-
```html
79
-
<!-- Overwrites content.html base mkdocs theme, taken from
<li>github actions: set <code>fetch_depth</code> to <code>0</code> (<a href="https://github.com/actions/checkout">docs</a>)</li>
45
+
<li>gitlab runners: set <code>GIT_DEPTH</code> to <code>0</code> (<a href="https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone">docs</a>)</li>
46
+
<li>bitbucket pipelines: set <code>clone: depth: full</code> (<a href="https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/">docs</a>)</li>
47
+
</ul>
96
48
</details>
97
49
98
-
99
-
100
-
### In custom themes
101
-
102
-
When writing your own [custom themes](https://www.mkdocs.org/user-guide/custom-themes/) you can use the `page.meta.git_revision_date_localized` jinja tag, like so for example:
103
-
104
-
```django hljs
105
-
{% if page.meta.git_revision_date_localized %}
106
-
Last update: {{ page.meta.git_revision_date_localized }}
107
-
{% endif %}
108
-
```
109
-
110
-
You can style the output using CSS: the date outputs are always wrapped in `<span class='git-revision-date-localized-plugin git-revision-date-localized-plugin-{type}></span>` (where `{type}` is replaced with the `type` option set in the plugin).
111
50
112
-
## Options
51
+
## Documentation
113
52
114
-
You can customize the plugin by setting options in `mkdocs.yml`. For example:
115
-
116
-
```yml
117
-
plugins:
118
-
- git-revision-date-localized:
119
-
type: timeago
120
-
timezone: Europe/Amsterdam
121
-
locale: en
122
-
fallback_to_build_date: false
123
-
enable_creation_date: true
124
-
exclude:
125
-
- index.md
126
-
```
127
-
128
-
### `type`
129
-
130
-
Default is `date`. To change the date format, set the `type` parameter to one of `date`, `datetime`, `iso_date`, `iso_datetime` or `timeago`. Example outputs:
131
-
132
-
```bash
133
-
28 November, 2019 # type: date (default)
134
-
28 November, 2019 13:57:28 # type: datetime
135
-
2019-11-28 # type: iso_date
136
-
2019-11-28 13:57:26 # type: iso_datetime
137
-
20 hours ago # type: timeago
138
-
```
139
-
140
-
### `timezone`
141
-
142
-
Default is `UTC`. Specify a time zone database name ([reference](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)). This option is especially relevant when using `type: datetime` and `type: iso_datetime`. Note that when using [timeago](http://timeago.yarp.com/) (with `type: timeago`) any difference in time zones between server and client will be handled automatically.
143
-
144
-
### `locale`
145
-
146
-
Default is `None`. Specify a two letter [ISO639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code to display dates in your preferred language.
147
-
148
-
- When not set, this plugin will look for `locale` or `language` options set in your theme. If also not set, the fallback is English (`en`)
149
-
- When used in combination with `type: date` or `type: datetime`, translation is done using [babel](https://github.com/python-babel/babel) which supports [these locales](http://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html)
150
-
- When used in combination with `type: timeago` then [timeago.js](https://github.com/hustcc/timeago.js) is added to your website, which supports [these locales](https://github.com/hustcc/timeago.js/tree/master/src/lang). If you specify a locale not supported by timeago.js, the fallback is English (`en`)
151
-
152
-
### `fallback_to_build_date`
153
-
154
-
Default is `false`. If set to `true` the plugin will use the time at `mkdocs build` instead of the file's last git revision date *when git is not available*. This means the revision date will be incorrect, but this can be acceptable if you want your project to also successfully build in environments with no access to GIT.
155
-
156
-
### `enable_creation_date`
157
-
158
-
Default is `false`. If set to `true`, you will be able to use `{{git_creation_date_localized}}` in markdown files and `page.meta.git_creation_date_localized` in page templates.
159
-
160
-
### `exclude`
161
-
162
-
Default is empty. Specify a list of page source paths (one per line) that should not have a revision date included (excluded from processing by this plugin). This can be useful for example to remove the revision date from the front page. The source path of a page is relative to your `docs/` folder. You can also use [globs](https://docs.python.org/3/library/glob.html) instead of full source paths. To exclude `docs/subfolder/page.md` specify in your `mkdocs.yml` a line under `exclude:` with `- subfolder/page.md`. Some examples:
163
-
164
-
```yaml
165
-
# mkdocs.yml
166
-
plugins:
167
-
- git-revision-date-localized:
168
-
exclude:
169
-
- index.md
170
-
- subfolder/page.md
171
-
- another_page.md
172
-
- folder/*
173
-
```
53
+
See [timvink.github.io/mkdocs-git-revision-date-localized-plugin](https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/index.html).
174
54
175
55
## Contributing
176
56
177
-
Contributions are very welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before putting in any work.
57
+
Contributions are very welcome! Please read [CONTRIBUTING.md](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/blob/master/CONTRIBUTING.md) before putting in any work.
You can customize the plugin by setting options in `mkdocs.yml`. For example:
4
+
5
+
```yaml
6
+
plugins:
7
+
- git-revision-date-localized:
8
+
type: timeago
9
+
timezone: Europe/Amsterdam
10
+
locale: en
11
+
fallback_to_build_date: false
12
+
enable_creation_date: true
13
+
exclude:
14
+
- index.md
15
+
```
16
+
17
+
## `type`
18
+
19
+
Default is `date`. To change the date format, set the `type` parameter to one of `date`, `datetime`, `iso_date`, `iso_datetime` or `timeago`. Example outputs:
20
+
21
+
```
22
+
28 November, 2019 # type: date (default)
23
+
28 November, 2019 13:57:28 # type: datetime
24
+
2019-11-28 # type: iso_date
25
+
2019-11-28 13:57:26 # type: iso_datetime
26
+
20 hours ago # type: timeago
27
+
```
28
+
29
+
## `timezone`
30
+
31
+
Default is `UTC`. Specify a time zone database name ([reference](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)). This option is especially relevant when using `type: datetime` and `type: iso_datetime`. Note that when using [timeago](http://timeago.yarp.com/) (with `type: timeago`) any difference in time zones between server and client will be handled automatically.
32
+
33
+
## `locale`
34
+
35
+
Default is `None`. Specify a two letter [ISO639](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code to display dates in your preferred language.
36
+
37
+
- When not set, this plugin will look for `locale` or `language` options set in your theme. If also not set, the fallback is English (`en`)
38
+
- When used in combination with `type: date` or `type: datetime`, translation is done using [babel](https://github.com/python-babel/babel) which supports [these locales](http://www.unicode.org/cldr/charts/latest/supplemental/territory_language_information.html)
39
+
- When used in combination with `type: timeago` then [timeago.js](https://github.com/hustcc/timeago.js) is added to your website, which supports [these locales](https://github.com/hustcc/timeago.js/tree/master/src/lang). If you specify a locale not supported by timeago.js, the fallback is English (`en`)
40
+
41
+
Example outputs:
42
+
43
+
```
44
+
27 April, 2021 # `locale: en` with `type: date` (default)
45
+
27 April, 2021 13:11:28 # `locale: en` with `type: datetime`
46
+
2 weeks ago # `locale: en` with `type: timeago`
47
+
27 de marzo de 2021 # `locale: es` with `type: date`
48
+
27 de marzo de 2021 13:57:28 # `locale: es` with `type: datetime`
49
+
hace 2 semanas # `locale: es` with `type: timeago`
50
+
```
51
+
52
+
## `fallback_to_build_date`
53
+
54
+
Default is `false`. If set to `true` the plugin will use the time at `mkdocs build` instead of the file's last git revision date *when git is not available*. This means the revision date will be incorrect, but this can be acceptable if you want your project to also successfully build in environments with no access to GIT.
55
+
56
+
## `enable_creation_date`
57
+
58
+
Default is `false`. If set to `true`, you will be able to use <code>\{\{ git_creation_date_localized }}</code> in markdown files and `page.meta.git_creation_date_localized` in page templates.
59
+
60
+
!!! Warning "not yet supported by Cmkdocs-material"
61
+
62
+
This feature was recently added, and native support for it has yet to be decided & implemented. See [!50](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/pull/50) for updates.
63
+
You can add support manually as described in [usage](usage.md#mkdocs-material-theme).
64
+
65
+
66
+
## `exclude`
67
+
68
+
Default is empty. Specify a list of page source paths (one per line) that should not have a revision date included (excluded from processing by this plugin). This can be useful for example to remove the revision date from the front page. The source path of a page is relative to your `docs/` folder. You can also use [globs](https://docs.python.org/3/library/glob.html) instead of full source paths. To exclude `docs/subfolder/page.md` specify in your `mkdocs.yml` a line under `exclude:` with `- subfolder/page.md`. Some examples:
0 commit comments