Merge pull request #605 from samhatfield/master

Updated documentation on pages configuration.

docs/user-guide/configuration.md

@@ -91,31 +91,14 @@ Set the remote branch to commit to when using `gh-deploy` to update Github Pages
 
 ### pages
 
-This is setting is used to determine the set of pages that should be built for the documentation.
-
-The setting should be a list.  Each row in the list represents information about a single page as a list of strings.  The first string represents the path of the documentation source file, and should be relative to the `docs_dir` setting.  Remaining strings represent the title of the page in the site navigation.
-
-Here's a simple example that would cause the build stage to create three pages:
+This setting is used to determine the set of pages that should be built for the documentation. For example, the following would create Introduction, User Guide and About pages, given the three source files `index.md`, `user-guide.md` and `about.md`, respectively.
 
     pages:
     - 'Introduction': 'index.md'
     - 'User Guide': 'user-guide.md'
-    - 'Abut': 'about.md'
+    - 'About': 'about.md'
 
-Assuming the `docs_dir` setting was left with the default value of `docs`, the source files for this site's build process would be `docs/index.md`, `docs/user-guide.md` and `docs/about.md`.
-
-If you have a lot of project documentation you might choose to use headings to break up your site navigation by category.  You can do so by including an extra string in the page configuration for any pages that require a navigation heading, like so:
-
-    pages:
-    - Introduction: 'index.md'
-    - User Guide:
-        - 'Creating a new Marshmallow project': 'user-guide/creating.md'
-        - 'Marshmallow API guide': 'user-guide/api.md'
-        - 'Configuring Marshmallow': 'user-guide/configuration.md'
-    - About:
-        - License: 'about/license.md'
-
-See also the section on [configuring pages and navigation](/user-guide/writing-your-docs/#configure-pages-and-navigation) for a more detailed breakdown.
+See the section on [configuring pages and navigation](/user-guide/writing-your-docs/#configure-pages-and-navigation) for a more detailed breakdown, including how to create sub-sections.
 
 ## Build directories
 
@@ -280,4 +263,4 @@ for that extension:
 [pymkd]: http://pythonhosted.org/Markdown/
 [smarty]: https://pythonhosted.org/Markdown/extensions/smarty.html
 [exts]:https://pythonhosted.org/Markdown/extensions/index.html
-[3rd]: https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions
+[3rd]: https://github.com/waylan/Python-Markdown/wiki/Third-Party-Extensions

docs/user-guide/writing-your-docs.md

@@ -14,7 +14,7 @@ A simple pages configuration looks like this:
     - '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 before the filename.
+With this example we will build two pages at the top level and they will automatically have their titles inferred from the filename. Assuming `docs_dir` has the default value, `docs`, the source files for this documentation would be `docs/index.md` and `docs/about.md`. To provide a custom name for these pages, they can be added before the filename.
 
     pages:
     - Home: 'index.md'
@@ -22,7 +22,7 @@ With this example we will build two pages at the top level and they will automat
 
 ### 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 slightly more complicated.
+Subsections can be created by listing related pages together under a section title. For example:
 
     pages:
     - Home: 'index.md'
@@ -33,7 +33,7 @@ To create a second level in the navigation and group topics, the category can be
         - 'License': 'about/license.md'
         - 'Release Notes': 'about/release-notes.md'
 
-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
+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.