Asciidoctor :: Discussion

Toc rendering options in Asciidoctor.js

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

4 messages Options

abelsromero

Jul 25, 2015; 6:27pm

Toc rendering options in Asciidoctor.js

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?

These 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!

mojavelinux

Jul 26, 2015; 7:02am

Re: Toc rendering options in Asciidoctor.js

Administrator

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

... [show rest of quote]

Dan Allen | http://google.com/profiles/dan.j.allen

abelsromero

Jul 26, 2015; 9:24am

Re: Toc rendering options in Asciidoctor.js

Perfectly clear now.

From an inexperienced user point of view it's confusing to see that these options exists but they do not work. However, once you understand it’s an embedded document, disabling right and left makes sense. About ‘auto’ (blank) I agree with what’s stated in the issue (https://github.com/asciidoctor/asciidoctor/issues/1443) , if you enable the title and the toc is under it, it should definitely be shown.

Let me explain a bit why I’m bothered about this. The thing is I think Atom.io can be a good entry point for a lot of people for the following reasons:
* Great exposure thanks to GitHub popularity.
* Easy to install; both Atom.io and the asciidoctor packages, no need for ruby/rvm, Java, ...
Later on, if someone needs to work with big documents they can move to AsciidoctorFX for instance. But as a starter's tool, I think that offering a good initial user experience is very important (even if the target audience is developers enjoying hacking).

Btw, related to this subject, should we consider reviewing the usage of “showtitle” and “notitle” as well? When you read the documentation is clear that they apply to different scenarios, but having two options with opposite meanings it's weird to me. Wouldn’t it be easier to explain and maintain the same set of options with different default values depending on the scenario?
For instance, we could use showtitle always, but set it to true by default when footer_header is true, and false otherwise.

mojavelinux

Jul 26, 2015; 10:02pm

Re: Toc rendering options in Asciidoctor.js

Administrator

On Sun, Jul 26, 2015 at 3:24 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Perfectly clear now.

I think that offering a good initial user experience is very important (even if the target audience is developers enjoying hacking).

100% agreed.

Btw, related to this subject, should we consider reviewing the usage of “showtitle” and “notitle” as well? When you read the documentation is clear that they apply to different scenarios, but having two options with opposite meanings it's weird to me.

Actually, `showtitle` is the official attribute name and `notitle` is deprecated. We should gradually phase out mention of `notitle` as a negative attribute name is very confusing.

(There may still exist some bugs around the use of `showtitle`, but let's just identify those and get them fixed).

For instance, we could use showtitle always, but set it to true by default when footer_header is true, and false otherwise.

This is an open issue scheduled for 1.6.0. See https://github.com/asciidoctor/asciidoctor/issues/1149

Cheers,

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen