Documentation

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
+Material for MkDocs exposes a simple text-only page-local hero via Metadata, as
-see on the current page when you scroll to the top. It's as simple 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.
 

docs/plugins/awesome-pages-plugin.md

@@ -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
-```

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
+```

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
+Markdown file was last updated at the bottom of each page.
-at the time of the build, so `mkdocs build` must be triggered from within a git
-repository.
 
 !!! 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`:

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