Bookmark-able and Navigate-able ToC

[jaredmcateer]

This request addresses Issue #7 by creating a linked ToC and named anchors for headers. The ToC is quite a bit bigger than before which makes me hesitant to submit this pull request but what the heck.

[addyosmani]

@jaredmcateer whoa.

This is a crazy awesome piece of work. Thanks for taking all the time to make this navigatable and bookmarkable. I would love to be able to merge this today but as you mentioned, the ToC has gotten a little bigger since I imagine you started working on this.

How about this? I plan on stabalizing the ToC by this weekend so that most of the changes are only within individual chapters. I would like to keep this PR open so that either you, I or someone else can finish off the work of updating it then to reflect the latest.

Let me know if you'd like to work on it but thank you very much regardless. Great work!

[jaredmcateer]

I'd love to help out

[oriolgual]

May I suggest using git-scribe? It would enable to export the book in multiple formats (PDF, epub, mobi, etcc) and it has a build-in ToC generator, plus many other benefits.

https://github.com/schacon/git-scribe

I can help moving the current content to asciidoc also.

[addyosmani]

@oriolgual I love the idea of using git-scribe. I haven't personally had a lot of experience with it in the past so any help moving the content over would be much appreciated. I think as per the previous reply, we'll need to wait until the book contents have stabalized so we can have a period where we hold off on new changes/merges until the switch has been made.

Is there a way for us to automatically convert markdown -> asciidoc? I ask because there currently seem to be people that like the idea of having the choice to read the book from the main markdown README as well.

[oriolgual]

I don't really know a way to do a Markdown -> AsciiDoc convertion, but if what you'd like is people reading the book straightfully, we couold output the git-scribe to html, publish it at github-pages (for example) and just linking the generated HTML in the readme. What do you think?

[addyosmani]

@oriolgual that would work!

[redouane]

@oriolgual yeah, we'd love that!

[oriolgual]

So do you want me to wait until the book has a more defined ToC or should I send a pull request converting the current contents to git-scribe right-away?

Continuing the writing in git-scribe/asciidoc it's pretty straightforward since it's very similar to markdown.

[addyosmani]

@oriolgual

At the moment I'm trying to decide wether it would make more sense to move to git-scribe or invest some time in pandoc instead (see http://johnmacfarlane.net/pandoc/). Have you heard of/used it before?

One of the benefits to pandoc is that is seems to work well as a conversion engine directly from markdown. I'm still very much open to git-scribe, but my only concern is whether this might put off some people from contributing (right now we're getting new PRs in everyday) and most people seem to be able to get around markdown without any complaints.

If we're able to nail down a solution to use this week/soon, I don't mind freezing PRs and new making new additions until a conversion has been wrapped up.

[addyosmani]

@jaredmcateer would you like to take a shot at re-linking? We won't be adding any new sections for the next few days and most updates will be to existing sections.

[jaredmcateer]

Absolutely I'll take a look tomorrow.

[addyosmani]

As there aren't a huge number of sections still left to add navigation to, I'll probably take care of this myself shortly. Closing this for now.