Merge pull request #14 from cjsheets/dev

updated instructions

README.md

@@ -30,22 +30,47 @@ theme:
 How to use
 ----------
 
-You have a couple folder/document-structure options when using this theme.
+Similar to [readthedocs.io](https://docs.readthedocs.io/en/latest/), this theme is built
+assuming a flat file structure.
 
-## Default Settings
+### File Structure
 
-Both ReadTheDocs and MkDocs use a "long-page" document structure. There is no nesting of pages. See [user-guide/instructions/](http://readthedocs.sheets.ch/user-guide/instructions/) as an example.
+Right now, your documentation can only use the first two file levels. I'm working on 
+adding support for a 3rd level. 
 
-Collapsing is based on top-level headings in each page.
+![Code structure](docs/img/level-example.png)
+
+In the example above, MkDocs will be a linked-page on the sidebar (to index.md) while UserGuide
+will be a category containing the pages nested under it (ex. Instructions which contains instructions.md)
+
+![Code output](docs/img/output-example.png)
+
+
+**Note:** If you don't declare your doc-structure explicitly in mkdocs.yml, each folder is considered a file level.
+
+### Collapsing
+
+The dropdown menu is controlled by heading levels.
 
 ```
-# Page Title   <-- Top level heading
+# Page Title    <-- H1
 
 content, content, content
+
+## Section      <-- H2
+
+### Section     <-- H3
 ```
 
+The rules for headings are essentially:
 
+* If there is only one H1, it will be ignored and the page/file name will be the root dropdown element
+  * Having 2 sub-menus with no choices was a wierd experience 
+  * See [MkDocs](http://readthedocs.sheets.ch/) for an example
+* If there are multiple H1, they each become dropdown elements
+  * See [user-guide/instructions](http://readthedocs.sheets.ch/user-guide/instructions/) for an example
 
+There is currently no support for H3+ dropdowns. I'm working on adding support to the next version.
 
 
 Considerations
@@ -57,7 +82,6 @@ Considerations
 For further discussion, see [this issue](https://github.com/mkdocs/mkdocs/issues/588#issuecomment-341931422).
 
 
-
 Development
 -----------