From f12af6c02442b8513c997783d85f250639b2930e Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 1 Aug 2020 20:21:42 +0200 Subject: [PATCH] Added documentation for including revision dates --- docs/deprecations.md | 13 ++-- docs/setup/adding-a-git-repository.md | 93 +++++++++++++++++++++++++++ docs/setup/setting-up-site-search.md | 4 +- mkdocs.yml | 2 +- 4 files changed, 105 insertions(+), 7 deletions(-) diff --git a/docs/deprecations.md b/docs/deprecations.md index d17111834..d80a52f8c 100644 --- a/docs/deprecations.md +++ b/docs/deprecations.md @@ -25,13 +25,18 @@ redirect: /path/to/new/file --- ``` -The [mkdocs-redirects][2] plugin provides the ability to define redirect -mappings via `mkdocs.yml`, which is considered to be a much better solution to -achieve the same result: +The [redirects][2] plugin provides the ability to define redirect mappings via +`mkdocs.yml`, which is considered to be a much better solution to achieve the +same result. It can be installed with `pip`: + +``` +pip install mkdocs-redirects +``` + +Redirect mappings can then be added to `mkdocs.yml`: ``` yaml plugins: - - search - redirects: redirect_maps: path/to/old/file.md: path/to/new/file.md diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index 587bec46b..aff39a97c 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -98,3 +98,96 @@ behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`: [7]: https://about.gitlab.com/ [8]: https://bitbucket.org/ [9]: https://www.mkdocs.org/user-guide/configuration/#edit_uri + +### Revision date + +[:octicons-file-code-24: Source][10] · +[:octicons-cpu-24: Plugin][11] + +The [git-revision-date][11] plugin adds support for displaying the date a +document was _last updated_ at the bottom of each page. It can be installed +with `pip`: + +``` +pip install mkdocs-git-revision-date-plugin +``` + +Then, add the following to `mkdocs.yml`: + +``` yaml +plugins: + - git-revision-date +``` + +The following options are supported: + +`enabled_if_env`{: #enabled_if_env } + +: :octicons-milestone-24: Default: _none_ – This option defines whether the + date is actually extracted from git, which makes it possible to disable + extraction for cases when the repository is not available: + + ``` yaml + plugins: + - git-revision-date: + enabled_if_env: CI + ``` + +_Material for MkDocs doesn't provide official support for the other options of +this plugin, so they may be supported but can also yield weird results. Use +them at your own risk._ + + [10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-date.html + [11]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin + +### Revision date, localized + +[:octicons-file-code-24: Source][10] · +[:octicons-cpu-24: Plugin][12] + +Similarly, the [git-revision-date-localized][12] plugin adds support for adding +a localized _last updated_ date at the bottom of each page. It can be installed +with `pip`: + +``` +pip install mkdocs-git-revision-date-localized-plugin +``` + +Then, add the following to `mkdocs.yml`: + +``` yaml +plugins: + - git-revision-date-localized +``` + +The following options are supported: + +`type`{: #type } + +: :octicons-milestone-24: Default: `date` – This option allows to change the + format of the date to be displayed. Valid values are `date`, `datetime`, + `iso_date`, `iso_datetime` and `timeago`: + + ``` yaml + plugins: + - git-revision-date-localized: + type: date + ``` + +`fallback_to_build_date`{: #fallback_to_build_date } + +: :octicons-milestone-24: Default: `false` – This option specifies whether + the time when `mkdocs build` was executed should be used as a fallback when + the git repository is not available: + + ``` yaml + plugins: + - git-revision-date-localized: + fallback_to_build_date: true + ``` + +_Material for MkDocs doesn't provide official support for the other options of +this plugin, so they may be supported but can also yield weird results. Use +them at your own risk._ + + [12]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin diff --git a/docs/setup/setting-up-site-search.md b/docs/setup/setting-up-site-search.md index a85b352a7..527a81640 100644 --- a/docs/setup/setting-up-site-search.md +++ b/docs/setup/setting-up-site-search.md @@ -133,12 +133,12 @@ them at your own risk._ ### Offline search -[:octicons-file-code-24: Source][8] · +[:octicons-file-code-24: Source][8] · [:octicons-cpu-24: Plugin][9] · :octicons-beaker-24: Experimental If you distribute your documentation as `*.html` files, the built-in search will not work out-of-the-box due to the restrictions modern browsers impose for -security reasons. This can be mitigated with the [localsearch plugin][9] in +security reasons. This can be mitigated with the [localsearch][9] plugin in combination with @squidfunk's [iframe-worker][10] polyfill. For setup instructions, refer to the [official documentation][11]. diff --git a/mkdocs.yml b/mkdocs.yml index fb871f4ad..1a71c820c 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,7 +77,7 @@ plugins: extensions/pymdown.md: reference/admonitions.md plugins/search.md: setup/setting-up-site-search.md # plugins/minification.md: - # plugins/revision-date.md: + plugins/revision-date.md: setup/adding-a-git-repository.md #revision-date # plugins/awesome-pages.md: releases/4.md: upgrading.md #upgrading-from-4x-to-5x releases/5.md: upgrading.md #upgrading-from-3x-to-4x