From acfe5102d2481e86057b315e7ffcbd62f5009810 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Mon, 9 Mar 2020 23:12:10 +0100 Subject: [PATCH] Reworked plugin documentation --- docs/extensions/metadata.md | 5 ++- docs/index.md | 2 +- docs/plugins/revision-date.md | 84 +++++++++++++++++++---------------- docs/plugins/search.md | 6 +-- 4 files changed, 52 insertions(+), 45 deletions(-) diff --git a/docs/extensions/metadata.md b/docs/extensions/metadata.md index e533fa1fe..91a4aed2c 100644 --- a/docs/extensions/metadata.md +++ b/docs/extensions/metadata.md @@ -6,8 +6,9 @@ source: metadata.md # Metadata -The [Metadata][1] extension makes it possible to add metadata to a document -which gives more control over the theme in a page-specific context. +[Metadata][1] is an extension included in the standard Markdown library that +makes it possible to control certain properties in a page-specific context, +e.g. the page title or description. [1]: https://python-markdown.github.io/extensions/meta_data/ diff --git a/docs/index.md b/docs/index.md index b023bf935..d23ba31de 100644 --- a/docs/index.md +++ b/docs/index.md @@ -19,7 +19,7 @@ Install the latest version of Material with `pip`: pip install mkdocs-material ``` -Append the following line to your project's `mkdocs.yml`: +Add the following line to `mkdocs.yml`: ``` yaml theme: diff --git a/docs/plugins/revision-date.md b/docs/plugins/revision-date.md index 06110cf52..2cb7a5ab7 100644 --- a/docs/plugins/revision-date.md +++ b/docs/plugins/revision-date.md @@ -1,72 +1,78 @@ # Revision date -[mkdocs-git-revision-date-localized-plugin][1] is an extension that shows the -date on which a Markdown file was last updated in _Git_ at the bottom of each -page. The date is extracted at the time of the build, so `mkdocs build` must -be triggered from within a Git repository. +The [mkdocs-git-revision-date-localized-plugin][1] is an extension that shows +the date on which a Markdown file was last updated in at the bottom of each +page. The date is extracted at the time of the build, so `mkdocs build` must be +triggered from within a git repository. + +!!! success "Bundled with the official Docker image" + + This plugin is already installed for your convenience when you use the + official [Docker image][2], so the installation step can be skipped. Read + the [getting started guide][3] to get up and running with Docker. [1]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin + [2]: https://hub.docker.com/r/squidfunk/mkdocs-material/ + [3]: ../getting-started.md#with-docker-recommended ## Installation -Install the plugin using `pip` with the following command: +Install the plugin using `pip`: ``` sh pip install mkdocs-git-revision-date-localized-plugin ``` -Next, add the following lines to your `mkdocs.yml`: +## Configuration + +Add the following lines to `mkdocs.yml`: ``` yaml plugins: - - search + - search # necessary for search to work - git-revision-date-localized ``` -!!! warning "Remember to re-add the `search` plugin" +Note that the date is printed according to the locale which is determined +through the [theme language][2] that was set in `mkdocs.yml`. - 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. + [2]: ../getting-started.md/#language -## Configuration +### Language -The date is automatically added at the bottom of each page, e.g.: +The language (i.e. locale) is deduced from the `theme.language` option. -``` -Last updated: 9 December, 2019 -``` +### Format -### Changing the language - -The date is printed according to the locale which is determined through the -[theme language][2] that was set in `mkdocs.yml`. - - [2]: https://squidfunk.github.io/mkdocs-material/getting-started/#language - -### Changing the format +> Default: `date` To change the date format, set the `type` parameter to one of `date`, -`datetime`, `iso_date`, `iso_datetime` or `timeago`, i.e.: - -``` gnuplot -28 November, 2019 # type: date -28 November, 2019 13:57:28 # type: datetime -2019-11-28 # type: iso_date -2019-11-28 13:57:26 # type: iso_datetime -20 hours ago # type: timeago -``` - -Example: +`datetime`, `iso_date`, `iso_datetime` or `timeago`, e.g.: ``` yaml plugins: + - search # necessary for search to work - git-revision-date-localized: - type: timeago + type: date ``` -Result: +The following formats are supported: +``` gnuplot +28 November, 2019 # type: date +28 November, 2019 13:57:28 # type: datetime +2019-11-28 # type: iso_date +2019-11-28 13:57:26 # type: iso_datetime +20 hours ago # type: timeago ``` -20 hours ago -``` + +## Usage + +When enabled, the respective date is automatically added at the bottom of each +page, e.g.: + +--- + + + Last updated: 9 December, 2019 + diff --git a/docs/plugins/search.md b/docs/plugins/search.md index 580993b1a..e74a3ae22 100644 --- a/docs/plugins/search.md +++ b/docs/plugins/search.md @@ -27,7 +27,7 @@ plugins: > Default: best match for `theme.language`, automatically set Material for MkDocs selects the (best-)matching stemmer for the given theme -language. Multilingual search can be activated in `mkdocs.yml` by explicitly +language. Multilingual search can be enabled in `mkdocs.yml` by explicitly defining the search language(s): ``` yaml @@ -66,8 +66,8 @@ The following language codes are supported: !!! warning "Only specify the languages you really need" Be aware that including support for other languages increases the general - JavaScript payload by around 20kb (without gzip) and by another 15-30kb per - language. + JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb + per language. ### Tokenization