Login  Register

Re: Toc rendering options in Asciidoctor.js

Posted by mojavelinux on Jul 26, 2015; 7:02am
URL: https://discuss.asciidoctor.org/Toc-rendering-options-in-Asciidoctor-js-tp3564p3568.html

Abel,

I'm looking forward to your improvements!

To answer your question, I'll explain how it works today. Keep in mind, I'm merely explaining the current situation. The option to improve the behavior is always on the table.

The allowed values for the `toc` attribute depend on whether you are converting to a standalone HTML document (header_footer: true) or embeddable HTML (header_footer: false). The allowed values for the `toc` attribute when converting to embeddable HTML are a subset of the values when converting to a standalone HTML document. The values that only apply to the standalone HTML document are `auto` (the default value if blank), `left` and `right`.

The reason `left` and `right` are only available when converting to a standalone HTML document is two-fold.

1. We need a slot in the HTML structure to put the left and right toc, which is only available when making a standalone HTML document.
2. Embeddable HTML is intended to be inserted anywhere inside another HTML document and therefore we can't assume we have access to the HTML viewport to place the left and right toc.

(Also remember that below the medium-sized screen breakpoint, the left and right toc will return to the center).

These differences need to be better explained in the User Manual. See http://asciidoctor.org/docs/user-manual/#table-of-contents-summary

The preview in the Atom editor uses the embeddable HTML (`header_footer: false`). Therefore, it has a limited number of toc placement options. The embeddable HTML is used in the Atom preview because the viewport itself is an HTML document. It's also slightly faster for us to produce the embeddable HTML because it doesn't have to prepare the HTML head.

I've proposed recognizing all toc values as a fallback when converting to embeddable HTML. See https://github.com/asciidoctor/asciidoctor/issues/1443

In general, I think the right solution is making the embeddable HTML as functional as it can be so that we don't end up losing important features just because we aren't converting to a standalone HTML document.

I hope that helps answer your questions.

Cheers!

-Dan

p.s. We do plan to change the header_footer value to something like embeddable to make the intention more clear. See https://github.com/asciidoctor/asciidoctor/issues/1444

On Sat, Jul 25, 2015 at 12:27 PM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Hi,

Related to this conversation (https://github.com/asciidoctor/atom-asciidoc-preview/issues/99), I’ve been working to ease the configuration of the different toc options. I have a prototype working, but ‘auto’, ‘left’ and ‘right’ options don’t work.
In the issue Dan mentions that there are three possible options (off, preamble and macro), innocently I thought he may had slipped but now I think he didn’t.
I tested those options with asciidoctorj and they work perfectly, so what I missing?

This are the options passed to Asciidoctor.js:
platform=opal platform-opal env=browser env-browser source-highlighter=highlight.js icons=font@ numbered! showtitle compat-mode=@ toc=right toc2!



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Toc-rendering-options-in-Asciidoctor-js-tp3564.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--