[asciidoc] Missing asciidoctor.css if asciidoctor is specified

[farleylai]

It might be an extension from asciidoctor to specify image positions, e.g. [.left] and [.right] such that the image aligns with text side by side instead of top down. The instruction is translated into imageblock class with float style left or right. However, when asciidoctor is specified for asciidoc, the companion asciidoctor.css is not included in the generated html, resulting unexpected layout as follows:

The expected html layout generated by JBake I previously used is as follows:

The current workaround is to manually add the css and edit the template to link that css but the css may introduce conflicted styles with themes. Since asciidoctor is very popular and this layout feature is handy, any effort to fix/automate this would be appreciated.

[Kwpolska]

Since asciidoctor is very popular

[citation needed]

Asciidoctor’s default CSS is opinionated, and very likely to break when mixed with Nikola (we’ve already had to patch a great deal out of reST CSS). That said, it seems as if the role feature just assigns a class — which means you can use [.align-left] (which is provided by reST CSS) and get what you want. (.left.align-left should be enough for a file to be compatible with both Nikola and the default asciidoctor stylesheet.)

[farleylai]

Since asciidoctor is very popular

[citation needed]

The latest release of the original AsciiDoc was four years ago while asciidoctor is up to date in 2017. Comparing the number of stars on GibHub, asciidoctor vs. asciidoc is 1713 vs 266, not to mention the creator of AsciiDoc makes it clear on the website:

Asciidoctor provides a modern, compliant, and substantially faster implementation of the AsciiDoc processor written in Ruby. This implementation can also be run on the JVM (with AsciidoctorJ) or using JavaScript (with Asciidoctor.js). The Asciidoctor project now maintains the official definition of the AsciiDoc syntax.

Therefore, if there is anyone who claims to support AsciiDoc, the general assumption is likely to support what asciidoctor offers.

After manually adding the asciidoctor.css, I did notice some theme styles overridden like the footer and had to fix the unexpected conflicts. Nonetheless, I did not notice similar issues with JBake who supports AsciiDoc through asciidoctor even when switching themes. They must have made some effort to tame the opinionated css.

It is very good to know that rst provides similar support for image alignment. What about the checklist? In markdown, it is GitHub flavored. In AsciiDoc (by asciidoctor), it is official. I already have a bunch of documents in AsciiDoc at hand. To switch the format, I have to consider different syntax support in a comprehensive way though.

[Kwpolska]

I referred to AsciiDoctor’s popularity within the Nikola community, not the Asciidoc* community.

After manually adding the asciidoctor.css, I did notice some theme styles overridden like the footer and had to fix the unexpected conflicts. Nonetheless, I did not notice similar issues with JBake who supports AsciiDoc through asciidoctor even when switching themes. They must have made some effort to tame the opinionated css.

No, not really. They removed only a few of the most glaring styles (hN, a, pre, code) and left everything else in (including the #footer you mentioned earlier) — compare asciidoctor.css in their sample sites (from their download .zip) and http://themes.asciidoctor.org/stylesheets/asciidoctor.css.

We don’t have any asciidoc experts around, but if you want, you could contribute a minimal asciidoctor.css — we’ll be happy to include it alongside the plugin so that other users can benefit. Perhaps you could also ask asciidoctor devs to produce a smaller CSS that doesn’t conflict with everything else?

[farleylai]

The popularity I meant as an new external user in the very beginning refers to what it is in the world in the official sense with no regard to the Nikola or other 3rd party community. A poll may be initiated to understand the exact popularity in your community. What is concerned is the actual support for those who migrate from other toolchains. Any caveats would be appreciated.

No, not really. They removed only a few of the most glaring styles (hN, a, pre, code) and left everything else in (including the #footer you mentioned earlier) — compare asciidoctor.css in their sample sites (from their download .zip) and http://themes.asciidoctor.org/stylesheets/asciidoctor.css.

OK, I took a closer look at the stylesheets included in the generated html by JBake:

<link href="../css/bootstrap.min.css" rel="stylesheet">
<link href="../css/asciidoctor.css" rel="stylesheet">
<link href="../css/base.css" rel="stylesheet">
<link href="../css/prettify.css" rel="stylesheet">
...

The base.css overrides asciidoctor.css such as the footer which is similar to what I have done in custom.css to address the unexpectations. There is nothing else much but it might be theme specific. To be fair, the asciidoctor.css is meant to render the resulting html for standalone viewing but replaceable as long as the replacement satisfies all the necessary styles in the resulting html.

I am by no means an asciidoctor expert and it seems like a theme css wizard qualifies more for this task in terms of complete and general theme support. In the short term, with a careful review of the the asciidoctor.css, a replacement css either modifies or overrides would suffice given most users need only minimal theme customization. However, whenever a new format is to be supported, one is likely to repeat the same process. In the long term, a format converter such as pandoc that converts AsciiDoc to rst may be preferred to well support and there is no need to get hands dirty with css. AFAIK, the AsciiDoc reader for pandoc is not finished yet (jgm/pandoc#2100) and other conversion routes such as from latex/docbook to rst would lose something like the image alignment in my experiments. Nonetheless, the asciidotor library is able to extract the DOM for further manipulation.

I would like to contribute some in my spare time even though I have been away from web development for long, and if that is so far the best way to go. A theme/css guideline (required/must/should/important, overridable or not for each reserved style classes) at hand would be useful .