Posted by abelsromero on Jul 26, 2015; 9:24am
URL: https://discuss.asciidoctor.org/Toc-rendering-options-in-Asciidoctor-js-tp3564p3569.html

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.