Feature: SEO- and user-friendly table of contents

[sjorek]

As groc's incomplete google site-search results prove, the current on-the-fly generated tables of contents is ignored by search-engines.

As an initial step towards a better (ajax-based ?!?) solution I changed the implementation to generate the TOC directly in the jade-template docPage.jade and restructured the behavior.coffee accordingly, hopefully without touching any existing functionality. This step made a split of the single-phase groc-process into a 2-phase groc-process necessary. As before phase 1 reads and parses all sources files to collect this information, but it does not render the jade-template yet. After this phase the TOC's data is generated from the infos collected as before. Now starting with phase 2 all the sources files from phase 1 will be rendered, but this time having the TOC's data in their context.

Other changes introduced by this commit:

1. ESC-key toggles the TOC on and off, without focusing the search-field
2. If the TOC is closed then Return- and TAB-key focus the search-field and open the TOC
3. If the TOC is open TAB-key focus and blurs the search-field, without closing the TOC
4. Beneath the existing nav ol.toc li.selected-class an additionally class nav ol.toc li.current has been introduced to permanently mark the current document.
5. You can use the rendered result with javascript disabled (not the best but surely enough), hence the search-engine actually sees the TOC's links.
6. The (for now unnecessary) JSON in behavior.coffee is cleaned before exported for the sake of privacy and file size.
7. Bugfix for multiple spaces in search-word. They don't get removed anymore, but collapse to a single space instead. This allows one to search two words.
8. Bugfix for matching search-results not being clickable and grayed out, because they had children which matched too (try “sty” in groc).
9. Bugfix for the missing removal of .matched-class from TOC-items.

[sjorek]

@kmdavis … I think I'll close this pull-request due to the lack of interest and more importantly, its bad design and behavior. Any objections ?

[kmdavis]

I wouldn't say there's lack of interest. I was planning to take a more detailed look at this next week. However, based on the description, I'd probably push for a purely ajax solution, as this would dovetail nicely with work I had planned for Gilt's internal documentation server. Here at Gilt we have hundreds of ui modules, and we run groc on each of them individually, but we'd like the search function to search all of the modules -- which would require either an ajax search/toc or our server could rewrite the search data on request.

[sjorek]

Although one might think the following notes are a bit off-topic, it is actually related to the initial motivation behind the SEO-friendly TOC.

@kmdavis I also have your comments about your gilt-setup with ajax and search in mind:

Has anyone (especially @kmdavis) ever thought about splitting groc into a client (rendering the html-docs) and a service delivering the (pre-parsed) sources? I know many of you want to get rid of the pygments dependency, and with the current groc-design I certainly agree with all of you. On the other side the suggested client-service-design could finally satisfy all of our diverse needs. I try to explain why, and please don't get the following thoughts wrong, because I still talk a lot about python (:hear_no_evil: :see_no_evil: :speak_no_evil:):

Using the pygments' formatter- und filter-api I created some plugins with grocin mind. They can be combined and make pygmentize spit out a JSON-stream of (raw) source-comments and (html- or whatever-formatted) source-code. A quick'n'dirty hack in groc worked surprisingly well as it made the util.splitSource-monster (~350 lines of code) and the SEGMENT / DIVIDER-magic in util.highlightCode completely obsolete. It produces markup with (correct!) line-numbers and my final experiments concentrated on hyperlinking keywords and definitions (aka ctags).

I have some experience with python's excellent twisted-framework. Writing a simple JSON-REST-like-service that runs locally on top of the same sources as groc and spits out nice and easily consumable JSON for groc, should be easy. The logical next step would be a rewrite of this service in node.js and voilá a modular groc-achitecture would have been born.

Pros:

• As a result of the client-/service-design, which is meant to run as a permanent service (at least for the time groc runs), the rendering speed of pygments and all other upcoming implementations will certainly raise.
• And a watch-mode might profit from this design as well.
• Other implementations like search-engines or code-outline generators can easily consume this service too.

Cons:

• certainly a more complex design …

Do you get, what I have in mind, what I talk about ? Should I explain some thing more thoroughly ? Is anyone interested in working samples ?

Btw. sorry, for writing that much again … 😊