search

bryanbraun / middleman-navtree

For building navigation trees & menus in Middleman.
MIT License
45 stars 17 forks source link

Add an option to keep the data file #5

Closed assimovt closed 9 years ago

assimovt commented 9 years ago

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.

bryanbraun commented 9 years ago

Thanks for writing out your thought process... this is an interesting approach.

I agree, if you're making a lot of changes to the tree, it doesn't make sense to maintain them in two places (tree.yml and config.rb).

The overhead of adding another config option with a condition seems pretty low to me. I like the idea of merging this pull request. I'm wondering, though, if there's a better name we can give to the option (than :data_file_keep, false) which makes it a little more clear what the resulting behavior is. Maybe something like :automatic_tree_updates, false or :update_mode, 'manual'? Maybe something else?

assimovt commented 9 years ago

automatic_tree_updates sounds better. Shall I push the change?

bryanbraun commented 9 years ago

Sure. Let's do automatic_tree_updates, with description text that says something like: The tree.yml file will be updated automatically when source files are changed. Also, if you can make the default value true in extension.rb, that would be great.

assimovt commented 9 years ago

@bryanbraun :shipit:

bryanbraun commented 9 years ago

Did some testing and everything works great. Merging this now, and I'll be pushing up a new version of the gem to rubygems shortly. Thanks!