Create maven-site/doxia compliant module

[abelsromero]

What is this issue about?

• Bug report
• Feature request
• Question

Description

Current maven-site/doxia integration (AsciidoctorDoxiaParser) converts sources to Html (without header/footer) using Asciidoctor and embeds the result as-is. As a result the styles applied do not match with the maven site skins (simply the class value do not match) and other differences appear as seen in #166.
To generate a "maven-site valid" Html a proper module should be implemented that uses Asciidoctor AST alongside Doxia's Sink so that the the generation of Html is handled by Doxia.

Pros:

• Standard maven-site HTML
• Users get a good out-of-the-box experince (no need for post-customizations)
• Users can use maven skins (e.g. https://maven.apache.org/skins/maven-fluido-skin/)

Cons:

• We can only support structures available in the Sink interface. For example, AsciiDoc admonitions of table captions are not available natively, but not much research has been done yet.

This is scheduled for v3.0.0 not for breaking changes but because as part of 3.0.0 we will split the project in sub-modules, that way we can provide multiple doxia modules, one with current approach and another one with this.

[abelsromero]

Made an unsuccesful poc passing the asciidoctor html to html parser as suggested in #564 (comment) (/cc fyi @michael-o).

1. The Markdown parser ends up delegating into the Html parser which preserves htlml's class values, so even when the parser works and provides an overall html structure, it still uses the original styles.
2. Striping class elements to fix 1 improves it, but still shows some inconsistencies because Doxia's Html Parser still preserves some characteristics of the source Html, see differences in normal table (left) and AsciiDoc (right) because Asciidoctor uses <thead> element and the original doesn't (just <tr> with <th> inside).

Another affected element are admonitions since they lose the icon references in the class.

We could also explore having a custom Asciidoctor converter (or templates) adapted to what html parser expects which requires less effort but also makes as dependant on too many external elements outside of our control and may impact performace having to do 2 conversions per document.

[michael-o]

Let me have a look at this in the next couple of days. Currently busy with Maven Core ITs.

[michael-o]

@abelsromero Can you upload two outputs, before and after? I'd like to diff them.

[abelsromero]

Let me have a look at this in the next couple of days. Currently busy with Maven Core ITs.

This just just fyi, no need to worry. But this is my test branch https://github.com/abelsromero/asciidoctor-maven-plugin/tree/poc/use-html-parser-for-site-integration, just installing locally and running https://github.com/asciidoctor/asciidoctor-maven-examples/tree/main/asciidoc-maven-site-example in debug mode to see the results.
To me it's pretty clear that styles (at least in fluido skin) align with the generated html from Markdown. Markdown parser part builds a striped down HTML, and the the html parser just adds the css styles. It's better than what we have now, but not 100% equivalent.

edit: I am counting this won't be easy feat and months worth of work.

[michael-o]

BTW, have a look how the Markdown parser does the magic. All callbacks are actually called. Maybe you can steal from? If anything isn't right in Doxia, let me know. Now is the time to make things right. I am totally skimming and improving the entire subsystem.

[kriegaex]

Sorry, I do not understand this. I upgraded to asciidoctor-converter-doxia-module for my Maven site, hoping that tables would be rendered with grids, frames, headers and/or striped rows. But they look just as ugly as before:

Can anyone point me to a description of how to configure this correctly? I can also downgrade to 2.2.x, if there is an easy solution for it.

[abelsromero]

"hoping" confuses me, do you mean you did expect tables to be correct with asciidoctor-converter-doxia-module or that they where fine before?
Because asciidoctor-converter-doxia-module is the same as the previous asciidoctor-maven-plugin module which required additional CSS to show tables. If you did not have any extra CSS then nothing should have changed.

If you don't want to add custom styles, you can try asciidoctor-parser-doxia-module it's being tested for fluido-skin, others are not guaranteed to work perfectly.

[kriegaex]

"hoping" confuses me, do you mean you did expect tables to be correct with asciidoctor-converter-doxia-module

Yes, because in #166 there was discussion about table formatting, and my impression was that 3.0.0 would fix the problem existing in 2.2.x. I did not read everything in detail, because I simply lack the time to.

or that they where fine before?

No, if they were fine before, I would not have tried to ugrade in the first place.

Because asciidoctor-converter-doxia-module is the same as the previous asciidoctor-maven-plugin module which required additional CSS to show tables.

I do have additional CSS, because if you remember our previous discussion, I need that for the rouge source highlighter in my Maven site.

If you don't want to add custom styles, you can try asciidoctor-parser-doxia-module it's being tested for fluido-skin, others are not guaranteed to work perfectly.

I am not sure what that is or what exactly I need to do. Using Asciidoctor for Maven sites is quite confusing. Can you advise me what I need to do to fix my tables?

[abelsromero]

I am not sure what that is or what exactly I need to do. Using Asciidoctor for Maven sites is quite confusing. Can you advise me what I need to do to fix my tables?

No problem at all. With 3.0.0 we released 2 site modules: the converter and the parser (naming is hard 😓 )

1. If you already have something working and you don't want to change that 👉 using asciidoctor-converter-doxia-module. It has full support for all AsciiDoc syntax but you'd need to add custom CSS. Seems you already have that in place so maybe is the best for you. As always, if you have any issues please report them with an example/reproducer, for questions you'll get quicker answers at http://chat.asciidoctor.org/.

2. If you don't want to mess with CSS and you are willing to sacrifice some AsciiDoc features (for example: not multiple syntax-highlighters or adminitions) 👉 try the asciidoctor-parser-doxia-module. There's an example in the examples repo https://github.com/asciidoctor/asciidoctor-maven-examples/tree/main/asciidoc-maven-site-parser-example. Basic stuff like tables should work perfectly and if they don't, please do report. More AsciiDoc advanced stuff won't work, but could be made to wor if there's demand.