diff --git a/README.md b/README.md index 682dae8..b35b33d 100644 --- a/README.md +++ b/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 ----------- diff --git a/docs/img/level-example.png b/docs/img/level-example.png new file mode 100644 index 0000000..692459c Binary files /dev/null and b/docs/img/level-example.png differ diff --git a/docs/img/output-example.png b/docs/img/output-example.png new file mode 100644 index 0000000..cdb2a9a Binary files /dev/null and b/docs/img/output-example.png differ