Reworked plugin documentation

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
+[Metadata][1] is an extension included in the standard Markdown library that
-which gives more control over the theme in a page-specific context.
+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/
 

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:

docs/plugins/revision-date.md

@@ -1,53 +1,62 @@
 # Revision date
 
-[mkdocs-git-revision-date-localized-plugin][1] is an extension that shows the
+The [mkdocs-git-revision-date-localized-plugin][1] is an extension that shows
-date on which a Markdown file was last updated in _Git_ at the bottom of each
+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
+page. The date is extracted at the time of the build, so `mkdocs build` must be
-be triggered from within a Git repository.
+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
+  [2]: ../getting-started.md/#language
-    want to add the `search` plugin. MkDocs enables it by default if there is
-    no `plugins` entry set.
 
-## 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.
 
-```
+### Format
-Last updated: 9 December, 2019
-``` 
 
-### Changing the language
+> Default: `date`
-
-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
 
 To change the date format, set the `type` parameter to one of `date`,
-`datetime`, `iso_date`, `iso_datetime` or `timeago`, i.e.:
+`datetime`, `iso_date`, `iso_datetime` or `timeago`, e.g.:
+
+``` yaml
+plugins:
+  - search # necessary for search to work
+  - git-revision-date-localized:
+      type: date
+```
+
+The following formats are supported:
 
 ``` gnuplot
 28 November, 2019                      # type: date
@@ -57,16 +66,13 @@ To change the date format, set the `type` parameter to one of `date`,
 20 hours ago                           # type: timeago
 ```
 
-Example:
+## Usage
 
-``` yaml
+When enabled, the respective date is automatically added at the bottom of each
-plugins:
+page, e.g.:
-  - git-revision-date-localized:
-      type: timeago
-```
 
-Result:
+---
 
-```
+<small>
-20 hours ago
+  Last updated: 9 December, 2019
-```
+</small>

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
+    JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb
-    language.
+    per language.
 
 ### Tokenization