Asciidoctor: CSS classes used by asciidoctor are undocumented and hard to integrate with other solutions

[Kwpolska]

There is no documentation regarding CSS used by asciidoctor. The existing stylesheet factory expects users to start with 1421 lines of Sass and an entire CSS framework (Foundation). All the existing themes in the factory take said SCSS file and change a few colors/fonts/borders. This is fine for standalone usage, but it’s not easy to integrate well with other solutions (eg. static site generators) that may already be using some other framework (Bootstrap, some newer version of Foundation, MDL, whatever). Even if one looks at the final CSS, there is no indication which styles are:

1. asciidoctor.scss features
2. asciidoctor.scss pretty things
3. Foundation features that asciidoctor depends on/expects to exist (at least .left / .right) 🤨
4. Foundation unused declarations

All in all, this makes integrating asciidoctor with anything hard, especially for people with no asciidoc(tor) expertise.

cc @farleylai / via getnikola/plugins#254

[mojavelinux]

I'm actually starting to work on something like this for Antora, which also needs its own stylesheet for AsciiDoc.

In an ideal case, we'd create such a style guide for the proposed semantic HTML converter (see #242). That way, we don't have to go through this twice and the HTML would be more suited for styling with CSS.

We have the HTML we have now because Asciidoctor had to match the output of AsciiDoc Python to gain acceptance. But now that HTML is kind of a legacy hold over and we want to make it better.

There's no reason you have to Foundation to style the HTML (or even the stylesheet factory). I choose to use Foundation to make it easier for me to create a default stylesheet. At the time, it did make it easier. But now even I am thinking about starting from scratch on a new stylesheet that doesn't pull in Foundation.

[mgielda]

I think there would be many who'd support this kind of decoupling; asciidoc(tor) happens to be a good syntax (with parsers) which could potentially be reused even more widely if it was more generic, the semantic HTML converter is a very good idea too.

[mojavelinux]

I've always said it's one of the key goals of Asciidoctor. And it's one of the top features for 2.0, which is in the planning stages. The only limitation thus far has been resources because it's not a small change. But with proper planning, we can manage it.