Jekyll Plugin toc Problem

[Tom Swan]

Hello all -- This is my first post here and I'd like to say Hi and that I am a huge fan of asciiDoctor -- I do all of my writing with it, and my note taking, and I'm planning to convert some of my books to .adoc files for online re-publishing. I'd appreciate some help tracking the source of a problem I have generating tocs in Jekyll with the jekyll-asciidoctor plugin. Not sure if this is an asciiDoctor, plugin, or Jekyll issue, so I'm asking around. When I generate html directly `:toc: left` correctly positions the contents in a panel at left (or right). But when Jekyll creates the html using the ja plugin, the toc always appears under the header. I am using the asciidoctor.css stylesheet. Comparing the generated html files shows that, when Jekyll creates the file, the table is classed `toc` but the native html from asciiDoctor shows `toc2 toc-left`. PS: If it helps, we've been discussing this on Write the Docs (link below). http://forum.writethedocs.org/t/the-asciidoc-discussion/223?u=tomswan

[mojavelinux]

Tom,

On Fri, Dec 11, 2015 at 3:18 PM, Tom Swan [via Asciidoctor :: Discussion] <[hidden email]> wrote:

When I generate html directly `:toc: left` correctly positions the contents in a panel at left (or right). But when Jekyll creates the html using the ja plugin, the toc always appears under the header.

The Jekyll plugin creates an embeddable HTML document. In that scenario, the only toc position available are "preamble" and "macro". The first puts the toc in the preamble, the second at the location of the toc::[] macro. I usually recommend using the toc macro.

:toc: macro

toc::[]

I think it would be nice if the README for jekyll-asciidoc pointed this out.

Cheers,

-Dan

--

[Tom Swan]

Thanks Dan. So, are you saying that it's a limitation of the plugin, or that it cannot be done in Jekyll? If I hand modify the generated html the menu works perfectly. Do I somehow refer to the document's toc in a layout? I'm not that versed in html, css, and Jekyll, so I may be misunderstanding something basic. But I've hit a brick wall and nobody seems to have a solution. Thanks again. -- Tom

[mojavelinux]

Tom,

It's a limitation of how the plugin works by default. Of course, anything is possible if you are willing to dive deeper into the plugin and hack it.

Here's a bit more background to help you understand the problem domain. The styling of the sidebar toc relies on a certain document structure that Asciidoctor generates for a standalone document. This structure is not entirely present in the embeddable HTML output that is used in the Jekyll plugin. If you're willing to change the stylesheet, you can pull the toc out of the body (using CSS) and make it a sidebar toc. The default stylesheet alone isn't going to cover this case.

It's also possible to load the document a second time in the layout and render just the toc using the Asciidoctor API. I've never explored that approach, but in theory it is possible.

The long and short of it is that it requires hacking because this is not a scenario that is supported out of the box. However, I do think that it's a reasonable goal for either an enhancement to the plugin or a tutorial. It's all just HTML and CSS, so it can be modified to do whatever you want it to do.

Cheers,

-Dan

On Fri, Dec 11, 2015 at 3:52 PM, Tom Swan [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Thanks Dan. So, are you saying that it's a limitation of the plugin, or that it cannot be done in Jekyll? If I hand modify the generated html the menu works perfectly. Do I somehow refer to the document's toc in a layout? I'm not that versed in html, css, and Jekyll, so I may be misunderstanding something basic. But I've hit a brick wall and nobody seems to have a solution. Thanks again. -- Tom

www.tomswan.com

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Jekyll-Plugin-toc-Problem-tp4070p4074.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

[Tom Swan]

Thanks for explaining. It's been suggested that I try to find another static site generator more friendly to asciiDoc. If I could find an alternative, I'd rather that than mess with rewriting the Jekyll plug-in. I did hack the css and got it to work, but that approach seems too hit-or-miss for comfort. Too bad, because all other asciiDoctor features seem to work great in Jekyll; only the :toc: directive is broken.

[mojavelinux]

 It's been suggested that I try to find another static site generator more friendly to asciiDoc.

This is not a friendly / not-friendly issue. In fact, every static site generator that integrates AsciiDoc has the same behavior right now regarding the toc component. (I'm not aware of one that currently supports a sidebar toc).

The only exception is if the static site generator allows you to disable the layout for a page. In that case, you can allow Asciidoctor to convert to a standalone document (thus controlling the layout). We do this for the Asciidoctor User Manual right now. http://asciidoctor.org/docs/user-manual

 I did hack the css and got it to work, but that approach seems too hit-or-miss for comfort.

I think creating a website necessitates knowing CSS (either you or someone on your team). So I'd say you are following the right path (at least, that's what I would do).

Too bad, because all other asciiDoctor features seem to work great in Jekyll; only the :toc: directive is broken.

It's not broken. It just doesn't apply to this mode. I'd say it is working as designed. I think it's important to understand that, because then you understand the flexibility of the converters. You can get any output you want. What works and what doesn't only depends on the original design goals of the converter. This wasn't a design goal of embeddable HTML, so it doesn't work as you expect it to.

...having said that, I do encourage you to open an issue in the jekyll-asciidoc repository to discuss supporting a sidebar toc with embeddable HTML. Through changes to the plugin, CSS and/or converter templates, it's possible to get something working out of the box. Here's one possible layout: https://developers.openshift.com/en/getting-started-overview.html

Cheers,

-Dan

--

[Tom Swan]

mojavelinux wrote

>

> It's not broken. It just doesn't apply to this mode. I'd say it is working
> as designed.

> ...having said that, I do encourage you to open an issue in the
> jekyll-asciidoc repository to discuss supporting a sidebar toc with
>embeddable HTML.

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

Sure I get your point, but it's such a useful feature it's a shame that it doesn't work the same for a standalone document vs one in a Jekyll site. I know I'm not the only one who would like sticky sidebar tocs!

I did open an issue for the plugin as you suggested. And I may want to open another concerning code highlighting, which again seems to work only with standalone asciidoctor, and not in Jekyll, although I'm not certain if I may be missing a key step here.

Thanks for your thoughts on the toc subject. I don't understand, however, why this should be handled in css since that's already being done in asciidoctor.css, no? Does the plugin not generate the toc2 and toc-left (toc-right) class values for some reason? Is that the problem?  Or must I extract the html headers and build the toc separately? That would then conflict with the :toc: directive in the standalone documents.

This boils down to a single goal: being able to use the same .adoc documents standalone and in Jekyll sites with similar results. Any concrete examples and suggestions that can help me accomplish that will be most welcome! Thank you.

[mojavelinux]

Thanks for submitting the issue, Tom! I added some information to the issue to help get development started.

> code highlighting, which again seems to work only with standalone asciidoctor, and not in Jekyll

To make code highlighting work with Jekyll, you need to set the following two attributes in the AsciiDoc document header:

:source-highlighter: pygments

:pygments-css: style

Alternatively, you can define these attributes in the _config.yml file as follows so they are applied globally:

asciidoctor:

  attributes:

    - source-highlighter=pygments

    - pygments-css=style

    - hardbreaks!

This puts the style information for source highlighting directly in the HTML. If you don't set the pygments-css attribute, then you need to provide your own stylesheet for Pygments. (It would be a nice feature for the Jekyll plugin to do automatically).

For more info, see https://github.com/asciidoctor/jekyll-asciidoc#configuration-optional. It certainly could be explained more clearly.

>  I don't understand why the [toc placement] should be handled in css since that's already being done in asciidoctor.css, no? 

asciidoctor.css is specifically designed for the standalone HTML. It's not really designed to be used with sites (embeddable HTML). What we need is a dedicated stylesheet that can serve that use case. We don't currently have one. (See https://github.com/asciidoctor/asciidoctor-stylesheet-factory/issues/18).

>  That would then conflict with the :toc: directive in the standalone documents. 

There are ways to set the toc conditionally, either by moving the declaration outside of the document or by using preprocessor conditionals. To cite an example:

ifdef::env-jekyll[:toc: macro]

ifndef::env-jekyll[:toc: left]

> This boils down to a single goal: being able to use the same .adoc documents standalone and in Jekyll sites with similar results.

I agree that is a good goal. It's up to the Jekyll AsciiDoc plugin to rise to this challenge because it's not something that the Asciidoctor processor can do all by itself. The plugin exists to fill in these gaps.

-Dan

On Mon, Dec 14, 2015 at 1:59 PM, Tom Swan [via Asciidoctor :: Discussion] <[hidden email]> wrote:

mojavelinux wrote

>

> It's not broken. It just doesn't apply to this mode. I'd say it is working
> as designed.

> ...having said that, I do encourage you to open an issue in the
> jekyll-asciidoc repository to discuss supporting a sidebar toc with
>embeddable HTML.

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

Sure I get your point, but it's such a useful feature it's a shame that it doesn't work the same for a standalone document vs one in a Jekyll site. I know I'm not the only one who would like sticky sidebar tocs!

I did open an issue for the plugin as you suggested. And I may want to open another concerning code highlighting, which again seems to work only with standalone asciidoctor, and not in Jekyll, although I'm not certain if I may be missing a key step here.

Thanks for your thoughts on the toc subject. I don't understand, however, why this should be handled in css since that's already being done in asciidoctor.css, no? Does the plugin not generate the toc2 and toc-left (toc-right) class values for some reason? Is that the problem?  Or must I extract the html headers and build the toc separately? That would then conflict with the :toc: directive in the standalone documents.

This boils down to a single goal: being able to use the same .adoc documents standalone and in Jekyll sites with similar results. Any concrete examples and suggestions that can help me accomplish that will be most welcome! Thank you.

www.tomswan.com

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Jekyll-Plugin-toc-Problem-tp4070p4090.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

--

[Tom Swan]

All great info -- thank you Dan! Code highlighting is now working. -- Tom

[mojavelinux]

Great news!

-Dan