From 2b37deb18853256fa3d64ed0af073c30dd7e0af4 Mon Sep 17 00:00:00 2001
From: Dougal Matthews <dougal@redhat.com>
Date: Sun, 26 Apr 2015 08:58:15 +0100
Subject: [PATCH] Add further documentation about the pages config

This change explicitly calls out how to do multi-level documentation.

Closes #475
---
 docs/index.md                        |  4 ----
 docs/user-guide/configuration.md     |  2 ++
 docs/user-guide/writing-your-docs.md | 32 ++++++++++++++++++++++++++++
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 030286d7..047f6a4e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -103,12 +103,10 @@ Let's also add a second page to our documentation:
 
 We'd like our documentation site to include some navigation headers, so we'll edit the configuration file and add some information about the order and title to use for out headers:
 
-```yaml
     site_name: MkLorum
     pages:
     - [index.md, Home]
     - [about.md, About]
-```
 
 Refresh the browser and you'll now see a navigation bar with `Home` and `About` headers.
 
@@ -116,12 +114,10 @@ Refresh the browser and you'll now see a navigation bar with `Home` and `About`
 
 While we're here can also change the configuration file to alter how the documentation is displayed.  Let's go ahead and change the theme.  Edit the `mkdocs.yml` file to the following:
 
-```yaml
     site_name: MkLorum
     pages:
     - [index.md, Home]
     - [about.md, About]
-    theme: readthedocs
 ```
 
 Refresh the browser again, and you'll now see the ReadTheDocs theme being used.
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
index 26290017..c7dff762 100644
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -107,6 +107,8 @@ If you have a lot of project documentation you might choose to use headings to b
     - ['user-guide/configuration.md', 'User Guide', 'Configuring Mashmallow']
     - ['about/license.md', 'About', 'License']
 
+See also the section on [configuring pages and navigation](/user-guide/writing-your-docs/#configure-pages-and-navigation) for a more detailed breakdown.
+
 ## Build directories
 
 
diff --git a/docs/user-guide/writing-your-docs.md b/docs/user-guide/writing-your-docs.md
index ed63cfbc..57620dd7 100644
--- a/docs/user-guide/writing-your-docs.md
+++ b/docs/user-guide/writing-your-docs.md
@@ -4,6 +4,38 @@ How to write and layout your markdown source files.
 
 ---
 
+## Configure Pages and Navigation
+
+The [pages configuration](/user-guide/configuration/#pages) in your `mkdocs.yml` defines which pages are built by MkDocs and how they appear in the documentation navigation. If not provided, the pages configuration will be automatically created by discovering all the Markdown files in the [documentation directory](/user-guide/configuration/#docs_dir).
+
+A simple pages configuration looks like this:
+
+    pages:
+    - 'index.md'
+    - 'about.md'
+
+With this example we will build two pages at the top level and they will automatically have their titles inferred from the filename. To provide a custom name for these pages, they can be added after the filename.
+
+    pages:
+    - ['index.md', 'Home']
+    - ['about.md', 'About MkDocs']
+
+### Multilevel documentation
+
+To create a second level in the navigation and group topics, the category can be provided before the page title. This is best demonstrated in a documentation project with more pages and is slighlt more complicated.
+
+    pages:
+    - ['index.md', 'Home']
+    - ['user-guide/writing-your-docs.md', 'User Guide', 'Writing your docs']
+    - ['user-guide/styling-your-docs.md', 'User Guide', 'Styling your docs']
+    - ['about/license.md', 'About', 'License']
+    - ['about/release-notes.md', 'About', 'Release Notes']
+
+With the above configuration we have three top level sections Home, User Guide and About. Then under User Guide we have two pages, Writing your docs and Styling your docs. Under the About section we also have two pages, License and Release Notes
+
+*Note:* At present MkDocs only supports a second level of navigation.
+
+
 ## File layout
 
 Your documentation source should be written as regular Markdown files, and placed in a directory somewhere in your project.  Normally this directory will be named `docs` and will exist at the top level of your project, alongside the `mkdocs.yml` configuration file.