Skip to content

Commit 35362f7

Browse files
timvinktimvink
committed
Update docs on customizing a theme, closes #53 
1 parent 12e4841 commit 35362f7

File tree

2 files changed

+56
-21
lines changed

2 files changed

+56
-21
lines changed

‎docs/howto/override-a-theme.md‎

Lines changed: 34 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# Override a theme
1+
# Customize a theme
22

33
You can [customize an existing theme](https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme) by overriding blocks or partials. You might want to do this because your theme is not natively supported, or you would like more control on the formatting. Below are some examples to get you started.
44

5-
## mkdocs theme
5+
## Example: default `mkdocs` theme
66

77
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.
88
Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides/content.html`:
@@ -39,9 +39,9 @@ Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides
3939
{% endif %}
4040
```
4141

42-
## mkdocs-material theme
42+
## Example: `mkdocs-material` theme
4343

44-
[mkdocs-material](https://squidfunk.github.io/mkdocs-material/) has native support for `git_revision_date_localized` and `git_created_date_localized`. You can [extend the mkdocs-material theme](https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme) by adding overriding the [`source-date.html`](https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-date.html) partial as follows:
44+
[mkdocs-material](https://squidfunk.github.io/mkdocs-material/) has native support for `git_revision_date_localized` and `git_created_date_localized`. If you want, you can customize further by [extending the mkdocs-material theme](https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme) and overriding the [`source-file.html`](https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-file.html) partial as follows:
4545

4646
=== "mkdocs.yml"
4747

@@ -51,13 +51,13 @@ Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides
5151
custom_dir: docs/overrides_material_theme
5252
```
5353

54-
=== "docs/overrides/partials/source-date.html"
54+
=== "docs/overrides/partials/source-file.html"
5555

5656
```html
5757
{% import "partials/language.html" as lang with context %}
5858

5959
<!-- Last updated date -->
60-
{% set label = lang.t("source.revision.date") %}
60+
{% set label = lang.t("source.file.date.updated") %}
6161
<hr />
6262
<div class="md-source-date">
6363
<small>
@@ -67,9 +67,9 @@ Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides
6767
{{ label }}: {{ page.meta.git_revision_date_localized }}
6868

6969
{% if page.meta.git_creation_date_localized %}
70-
<br />Created: {{ page.meta.git_creation_date_localized }}
70+
<br />{{ lang.t("source.file.date.created") }}: {{ page.meta.git_creation_date_localized }}
7171
{% endif %}
72-
72+
7373
<!-- mkdocs-git-revision-date-plugin -->
7474
{% elif page.meta.revision_date %}
7575
{{ label }}: {{ page.meta.revision_date }}
@@ -78,19 +78,36 @@ Then you can extend the base `mkdocs` theme by adding a new file `docs/overrides
7878
</div>
7979
```
8080

81-
## custom themes
81+
## Available variables
8282

83-
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:
83+
When customizing or [writing your own themes](https://www.mkdocs.org/user-guide/custom-themes/) `mkdocs-revision-date-localized-plugin` will make available the following jinja variables:
8484

85-
```django
86-
{% if page.meta.git_revision_date_localized %}
87-
Last update: {{ page.meta.git_revision_date_localized }}
88-
{% endif %}
89-
```
85+
- `page.meta.git_revision_date_localized`
86+
- `page.meta.git_creation_date_localized`
9087

91-
As a developer you might want access to more raw date formats that also do not have the `<span>` elements. You can also use:
88+
To insert these variables in a partial/block/template, use the jinja2 bracks `{{` and `}}`. The values of these variables depend on the plugin options specified, and are wrapped in `<span>` elements. For example, when using `type: timeago` (see [options](../options.md)):
89+
90+
=== "input"
91+
92+
```django
93+
{% if page.meta.git_revision_date_localized %}
94+
Last update: {{ page.meta.git_revision_date_localized }}
95+
{% endif %}
96+
```
97+
98+
=== "output"
99+
100+
```django
101+
Last update: <span class="timeago" datetime="2021-11-03T12:25:03+01:00" locale="en" timeago-id="5"></span>
102+
```
103+
104+
!!! info "Note"
105+
106+
When `type: timeago` option is used, `mkdocs-revision-date-localized-plugin` adds [timeago.js](https://timeago.org/) to your mkdocs website, which dynamically inserts a value between the `<span>` elements like `2 weeks ago`.
107+
108+
109+
As a developer you might want access to multiple 'raw' date types. These variables also do not have the `<span>` elements. You can use:
92110

93-
- `page.meta.git_revision_date_localized`
94111
- `page.meta.git_revision_date_localized_raw_date`
95112
- `page.meta.git_revision_date_localized_raw_datetime`
96113
- `page.meta.git_revision_date_localized_raw_iso_date`
@@ -99,7 +116,6 @@ As a developer you might want access to more raw date formats that also do not h
99116

100117
And if you've enable creation date in the config:
101118

102-
- `page.meta.git_creation_date_localized`
103119
- `page.meta.git_creation_date_localized_raw_date`
104120
- `page.meta.git_creation_date_localized_raw_datetime`
105121
- `page.meta.git_creation_date_localized_raw_iso_date`

‎tests/fixtures/basic_project/docs/overrides_material_theme/partials/source-date.html‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,26 @@
1+
<!--
2+
Copyright (c) 2016-2021 Martin Donath <[email protected]>
3+
Permission is hereby granted, free of charge, to any person obtaining a copy
4+
of this software and associated documentation files (the "Software"), to
5+
deal in the Software without restriction, including without limitation the
6+
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
7+
sell copies of the Software, and to permit persons to whom the Software is
8+
furnished to do so, subject to the following conditions:
9+
The above copyright notice and this permission notice shall be included in
10+
all copies or substantial portions of the Software.
11+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
12+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
13+
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
14+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
15+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
16+
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
17+
IN THE SOFTWARE.
18+
-->
19+
120
{% import "partials/language.html" as lang with context %}
221

322
<!-- Last updated date -->
4-
{% set label = lang.t("source.revision.date") %}
23+
{% set label = lang.t("source.file.date.updated") %}
524
<hr />
625
<div class="md-source-date">
726
<small>
@@ -11,9 +30,9 @@
1130
{{ label }}: {{ page.meta.git_revision_date_localized }}
1231

1332
{% if page.meta.git_creation_date_localized %}
14-
<br />Created: {{ page.meta.git_creation_date_localized }}
33+
<br />{{ lang.t("source.file.date.created") }}: {{ page.meta.git_creation_date_localized }}
1534
{% endif %}
16-
35+
1736
<!-- mkdocs-git-revision-date-plugin -->
1837
{% elif page.meta.revision_date %}
1938
{{ label }}: {{ page.meta.revision_date }}

0 commit comments

Comments
 (0)