From b0c2c4390a4a0f8644784d6f536ff389ca7de486 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 20 Mar 2020 16:47:47 +0100 Subject: [PATCH] Documentation --- docs/extensions/metadata.md | 8 +-- docs/plugins/awesome-pages-plugin.md | 68 ------------------------- docs/plugins/awesome-pages.md | 76 ++++++++++++++++++++++++++++ docs/plugins/revision-date.md | 9 ++-- mkdocs.yml | 2 +- 5 files changed, 87 insertions(+), 76 deletions(-) delete mode 100644 docs/plugins/awesome-pages-plugin.md create mode 100644 docs/plugins/awesome-pages.md diff --git a/docs/extensions/metadata.md b/docs/extensions/metadata.md index 91a4aed2c..9154d02c5 100644 --- a/docs/extensions/metadata.md +++ b/docs/extensions/metadata.md @@ -43,12 +43,12 @@ source: file.js ... ``` -See the next section which covers the metadata that is supported by Material. +See the next section which covers the supported metadata. ### Setting a hero -Material exposes a simple text-only page-local hero via Metadata, as you can -see on the current page when you scroll to the top. It's as simple as: +Material for MkDocs exposes a simple text-only page-local hero via Metadata, as +you can see on the current page when you scroll to the top. It's as simple as: ``` markdown hero: Set heroes with metadata @@ -78,7 +78,7 @@ source: metadata.md ### Redirecting to another page It's sometimes necessary to move documents around in the navigation tree and -redirect user from the old URL to the new one. The `redirect` meta-tag allows +redirect users from the old URL to the new one. The `redirect` meta-tag allows to create a redirection from the current document to the address specified in the tag. diff --git a/docs/plugins/awesome-pages-plugin.md b/docs/plugins/awesome-pages-plugin.md deleted file mode 100644 index aa579e1ff..000000000 --- a/docs/plugins/awesome-pages-plugin.md +++ /dev/null @@ -1,68 +0,0 @@ -# Awesome Pages Plugin - -[mkdocs-awesome-pages-plugin][1] is an extension that that simplifies configuring page titles and their order. - - [1]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/ - -## Installation - -Install the plugin using `pip` with the following command: - -``` sh -pip install mkdocs-awesome-pages-plugin -``` - -Next, add the following lines to your `mkdocs.yml`: - -``` yaml -plugins: - - search - - awesome-pages -``` - -!!! 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 - - -### Set Directory Title - -Create a YAML file named `.pages` in a directory and set the `title` to override the title of that directory in the navigation: - -```yaml -title: Page Title -``` - -### Arrange Pages - -Create a YAML file named `.pages` in a directory and set the `arrange` attribute to change the order of how child pages appear in the navigation. This works for actual pages as well as subdirectories. - -```yaml -title: Page Title -arrange: - - page1.md - - page2.md - - subdirectory -``` - -### Hide Directory - -Create a YAML file named `.pages` in a directory and set the `hide` attribute to `true` to hide the directory, including all sub-pages and sub-sections, from the navigation: - -```yaml -hide: true -``` - -### Collapse Pages - -This plugin supports collapsing directories that contain a single page - -If you want to enable or disable collapsing of a single page, without applying the setting recursively, create a YAML file called `.pages` in the directory and set `collapse` to `true` or `false`: - -```yaml -collapse: true -``` \ No newline at end of file diff --git a/docs/plugins/awesome-pages.md b/docs/plugins/awesome-pages.md new file mode 100644 index 000000000..4d6ae3969 --- /dev/null +++ b/docs/plugins/awesome-pages.md @@ -0,0 +1,76 @@ +# Awesome pages + +The [mkdocs-awesome-pages-plugin][1] omits the need to specify all pages in the +`nav` entry of `mkdocs.yml` and gives you control over page visibility, titles +and order on a directory level. + +!!! 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/lukasgeiter/mkdocs-awesome-pages-plugin/ + [2]: https://hub.docker.com/r/squidfunk/mkdocs-material/ + [3]: ../getting-started.md#with-docker-recommended + +## Installation + +Install the plugin using `pip`: + +``` sh +pip install mkdocs-awesome-pages-plugin +``` + +## Configuration + +Add the following lines to `mkdocs.yml`: + +``` yaml +plugins: + - search # necessary for search to work + - awesome-pages +``` + +## Usage + +If the `nav` entry in `mkdocs.yml` is omitted, MkDocs will automatically include +all pages in a specific order. This plugin allows for more fine-grained control +on a per-directory basis. In order to configure behavior for a specific +directory, create a YAML file named `.pages` in it and set one of the following +options. + +### Setting a directory title + +The directory title, which is shown as part of the navigation, can be set with: + +``` yaml +title: Lorem ipsum dolor sit amet +``` + +### Changing the order of pages + +The order of pages and subsections can be configured with: + +``` yaml +arrange: + - page-1.md + - page-2.md + - subdirectory +``` + +### Excluding a directory + +A directory can be hidden (i.e. excluded) with: + +``` yaml +hide: true +``` + +### Collapsing single-page directories + +Directories which contain a single page can be collapsed with: + +``` yaml +collapse: true +``` diff --git a/docs/plugins/revision-date.md b/docs/plugins/revision-date.md index bdd3978f6..84a60c84c 100644 --- a/docs/plugins/revision-date.md +++ b/docs/plugins/revision-date.md @@ -1,9 +1,7 @@ # Revision date The [mkdocs-git-revision-date-localized-plugin][1] will add the date on which a -Markdown file was last updated 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. +Markdown file was last updated at the bottom of each page. !!! success "Bundled with the official Docker image" @@ -15,6 +13,11 @@ repository. [2]: https://hub.docker.com/r/squidfunk/mkdocs-material/ [3]: ../getting-started.md#with-docker-recommended +!!! warning "Requirements" + + The date is extracted at the time of the build, so `mkdocs build` must be + triggered from within a git repository. + ## Installation Install the plugin using `pip`: diff --git a/mkdocs.yml b/mkdocs.yml index 2d38e75f1..d90dbb0ec 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -132,9 +132,9 @@ nav: - PyMdown: extensions/pymdown.md - Plugins: - Search: plugins/search.md - - Pages: plugins/awesome-pages-plugin.md - Minification: plugins/minification.md - Revision date: plugins/revision-date.md + - Awesome pages: plugins/awesome-pages.md - Releases: - Material for MkDocs 5: releases/5.md - Material for MkDocs 4: releases/4.md