From c44ea77172a6dbc37cb346eb5b15daf2d5097e4d Mon Sep 17 00:00:00 2001 From: Martin B Date: Wed, 18 Dec 2019 17:13:17 +0100 Subject: [PATCH] Separated plugin documentation from extensions (#1390) * Create minify-html.md * Rename docs/minify-html.md to docs/plugins/minify-html.md * Create search.md * Update and rename docs/extensions/revision-date.md to docs/plugins/revision-date.md * Update getting-started.md * Update mkdocs.yml --- docs/getting-started.md | 34 ++++++------------- docs/plugins/minify-html.md | 32 +++++++++++++++++ docs/{extensions => plugins}/revision-date.md | 9 ++++- docs/plugins/search.md | 20 +++++++++++ mkdocs.yml | 5 ++- 5 files changed, 74 insertions(+), 26 deletions(-) create mode 100644 docs/plugins/minify-html.md rename docs/{extensions => plugins}/revision-date.md (82%) create mode 100644 docs/plugins/search.md diff --git a/docs/getting-started.md b/docs/getting-started.md index 5859a64a8..ba2d91d03 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -688,36 +688,22 @@ Material theme including more information regarding installation and usage: ## Plugins -MkDocs's plugin architecture makes it possible to add pre- or post-processing -steps that sit between the theme and your documentation. A great example of a -third-party plugin is the [mkdocs-minify-plugin][32] which strips all whitespace -from the generated documentation. +MkDocs's plugin architecture makes it possible to add pre- or post-processing steps that sit between the theme and your documentation. For more information, see the following list of plugins tested and supported by the Material theme including more information regarding installation and usage: -Install it with `pip`: +* [Minify HTML][32] +* [Revision date][33] +* [Search][34] -``` sh -pip install mkdocs-minify-plugin -``` - -Enable it with the following lines in your `mkdocs.yml`: - -``` yaml -plugins: - - search - - minify: - minify_html: true -``` - -The MkDocs wiki contains a [list of all available plugins][33]. +The MkDocs wiki contains a [list of all available plugins][35]. !!! warning "Remember to re-add the `search` plugin" - 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. + If you have no `plugins` entry in your config file yet, you'll likely also want to add the `search` plugin when adding additional plugins. MkDocs enables it by default if there is no `plugins` entry set. - [32]: https://github.com/byrnereese/mkdocs-minify-plugin - [33]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins + [32]: plugins/minify-html.md + [33]: plugins/revision-date.md + [34]: plugins/search.md + [35]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins ## Full example diff --git a/docs/plugins/minify-html.md b/docs/plugins/minify-html.md new file mode 100644 index 000000000..9766efd53 --- /dev/null +++ b/docs/plugins/minify-html.md @@ -0,0 +1,32 @@ +# Minify HTML + +[mkdocs-minify-plugin][1] is an extension that minifies HTML by stripping all whitespace from the generated documentation. + + [1]: https://github.com/byrnereese/mkdocs-minify-plugin + +## Installation + +Install the plugin using `pip` with the following command: + +``` sh +pip install mkdocs-minify-plugin +``` + +Next, add the following lines to your `mkdocs.yml`: + +``` yaml +plugins: + - search + - minify: + minify_html: true +``` + +!!! warning "Remember to re-add the `search` plugin" + + 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. + +## Usage + +The output is automatically minified by the plugin. diff --git a/docs/extensions/revision-date.md b/docs/plugins/revision-date.md similarity index 82% rename from docs/extensions/revision-date.md rename to docs/plugins/revision-date.md index 8f70ae051..bd256a6ba 100644 --- a/docs/extensions/revision-date.md +++ b/docs/plugins/revision-date.md @@ -9,7 +9,7 @@ be triggered from within a Git repository. ## Installation -Install the plugin with the following command: +Install the plugin using `pip` with the following command: ``` sh pip install mkdocs-git-revision-date-localized-plugin @@ -19,9 +19,16 @@ Next, add the following lines to your `mkdocs.yml`: ``` yaml plugins: + - search - git-revision-date-localized ``` +!!! warning "Remember to re-add the `search` plugin" + + 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. + ## Usage The date is automatically added at the bottom of each page, e.g.: diff --git a/docs/plugins/search.md b/docs/plugins/search.md new file mode 100644 index 000000000..7347f1028 --- /dev/null +++ b/docs/plugins/search.md @@ -0,0 +1,20 @@ +# Search + +MkDocs enables the search plugin by default if there is no `plugins` entry set in `mkdocs.yml`. If additional plugins are installed, the `search` plugin must be added to your `mkdocs.yml`. See [Site search][1] for more information about how to use search with Material. + + [1]: ../getting-started.md#site-search + +## Installation + +Add the following lines to your `mkdocs.yml`: + +``` yaml +plugins: + - search +``` + +!!! warning "Remember to re-add the `search` plugin" + + 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. diff --git a/mkdocs.yml b/mkdocs.yml index 4ae4b0ecf..22687dde2 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,7 +120,10 @@ nav: - Metadata: extensions/metadata.md - Permalinks: extensions/permalinks.md - PyMdown: extensions/pymdown.md - - Revision date: extensions/revision-date.md + - Plugins: + - Minify HTML: plugins/minify-html.md + - Revision date: plugins/revision-date.md + - Search: plugins/search.md - Specimen: specimen.md - Customization: customization.md - Compliance with GDPR: compliance.md