bryanbraun/middleman-navtree — pull request #5 by assimovt (2014-12-23 20:43:35+00:00)
Title: Add an option to keep the data file

This PR addresses the problem reported in issue #1. I have tried a number of ways to achieve a sane Table of Contents for our documentation. This solution seemed to be the most elegant out of these options:

**Directory indexes**

I have tried to follow a convention of having ```index.md``` in each directory and using its page title. This worked pretty well, since I was able to define directory titles easily as any other page. However, it forced me to create unnecessary index files. Also, I was ordering the files and directories with number prefixes, which screws up the URLs.

**Overriding directory titles**

Then, I have patched the extension to override directory titles with an option, as was suggested in the issue. This also worked well, apart from the fact that I would have to maintain the titles in the ```config.rb```, which did not feel right. Additionally, it had the same problem of ordering items in the tree and ugly URLs.

**Manual tree file (this PR)**

Finally, I have decided the most usable way is to keep the data file with the tree and let maintain it manually. This allowed me to choose the directory titles, have a custom order, and keep nice URLs. It also serves as a good internal doc.