feat: navigation icons for toc sidebar

[nicorikken]

Icons can be invoked using nav-home, nav-up, nav-down, nav-prev and nav-next. It does require support for Awesomefont which can be triggered using the icons:font attribute.

I'm eager to receive feedback on this, as I guess it can benefit from better checking and Ruby coding style in general. It basically does what it's supposed to do, but can probably be improved.

My main inspiration for the navigation icons was the Debian Maintainers guide

[nicorikken]

Some ideas for improvement:

• [x] Bigger icons
• [x] Icons spread evenly across the width of the sidebar
• [ ] Intelligent handling of links, for both cross-references <<../index.adoc#section>> and for external links. (if this is feasible for a postprocessor).
• [ ] Support similar icons at the bottom of the page (TOC, footer, or using an inline macro lik [NAVICONS])
• [x] Handle the case where Awesomefont support is not present (either text-only, or by adding the Awesomefont support)

[nicorikken]

Apparently it is ok to add css, as I see in the view-result processor. Also I'll try using the flexbox CSS for distributing the available icons evenly across the width of the sidebar.

[nicorikken]

I just created an improvement on the previous code using some CSS. Now the icons are spread evenly across the width of the TOC, also rendering neatly for smaller screen-sizes. Normal page:

Smartphone size:

[nicorikken]

@mojavelinux Am I able to trigger the intelligent link handling in Asciidoctor from the postprocessor? Such that <<index.adoc#,index>> and link:http://asciidoctor.org/[asciidoctor homepage] in the attributes are resolved to URL's? Otherwise I'll have to do duplicate work.

[nicorikken]

I did some refactoring on the extension, and I drew a lot of inspiration from the talk around PR #7

• The code is now more modular and more DRY.
• It uses the DocInfoProcessor for neatly inserting the CSS and back-up FontAwesome script.
• It has basic support for link:url[desc] and <<url#attr,desc>> syntax, although the latter seems to be failing.
• The descriptions are rendered as the HTML title= attribute, which appears on hover as a tooltip.
• It has an initial try on block macro processing, but it seems like I'm messing things up. It now uses a fixes HTML render, but this needs to link into another processor based on document attributes.

Normal page:

Smartphone:

Discussion Ideally I'd like to have the links defined globally on the page by default, and have them locally defined if needed. So if attributes are set globally, there is no real need to set any info on rendering, I can just trigger navicons, so something like [navicons] would do, but this doesn't seem to be valid Asciidoctor syntax. It needs some source like below, even though no clear data-uri exsists in this case. (see #7)

chart::<data-uri>[<type>,<x-label>,<y-label>,<width>,<height>]

chart[<type>,<x-label>,<y-label>,<width>,<height>]
....
January,February,March,April,May,June,July
28,48,40,19,86,27,90
65,59,80,81,56,55,40
....

TODO

• [ ] Complete the link and crossreference syntax support
• [ ] Define a proper syntax for inserting NavIcons, and local link-overrides.
• [ ] Rename to a different namespace. navicons seems best for now.
• [ ] Ideally have Asciidoctor handle the links, and perhaps even try to read the file to extract a description (could be a different extension, if the links are processed properly).
• [ ] Bring support for named links, again referring to the Debian Maintainers' Guide, which seems better suited for placement in the page, rather than in the TOC. Another solution could be to have it appear dynamically using a hover effect. The now used Flexbox style could be of help to solve both solutions neatly.

[nicorikken]

Just found an additional explicit usecase when reading about GNU Make which lists navigational icons for each section, even though it is a single page. The links to contents and index are particularly interesting. I could add explicit support for it.

[nicorikken]

Regarding manual placement, the manual placement of the table of contents using toc::[] is a good exemplary equivalent syntax. Then something like nav::[] could be sufficient.

[ggrossetie]

Nice work @nicorikken !

Regarding manual placement, the manual placement of the table of contents using toc::[] is a good exemplary equivalent syntax. Then something like nav::[] could be sufficient.

Indeed I think you should mimic TOC placement instead of using a block macro. I think it doesn't make any sense to have multiple navigation bars on one document ?

[nicorikken]

Thanks! Still need to finish and polish it though. One could make the case for navigations inside a single file, like in the GNU Make manual I linked earlier. However, having such icons in place enables a document to be split up in multiple pages. So sticking with file-global settings and the option of manual placement should suffice.

[ggrossetie]

One could make the case for navigations inside a single file, like in the GNU Make manual I linked earlier.

Yep but I think this should be another extension section-nav ? Otherwise you may end up handling too much edge cases inside a single extension.

[ggrossetie]

I did a quick review to better understand where you are heading. I'm just throwing ideas, feel free to do differently :wink:

[nicorikken]

Thanks for all the comments, I'll take them into account when I do my next session of hacking on this code.

[nicorikken]

@Mogztter Your comments triggered me to get coding this morning. The implementation is now much cleaner, incorporates manual placement, and the cross-references are now properly supported (using < and > instead of < and > in regexes).

Improvements I would still like to make:

• [ ] Enable local link definitions inside the macro, like you suggested, like: nav::[home="link:http://asciidoctor.org[]", next="", prev="", up="", down=""] and nav::["link:http://asciidoctor.org[]", "<<post2.adoc#>>", "<<post0.adoc#>>"]
• [ ] Support different sets of icons, or even a custom stylesheet. The multiple icons supported by asciidoctor-pdf are an inspiration in this regard.

[mojavelinux]

I think this is extension is too complex for the lab, which is meant to serve as a reference for getting started with extensions. If someone is interested in the functionality this extension provides, I would encourage them to set this up as a separate extension project and publish it.