Roq Plugin AsciiDoc Java version ignores admonition blocks

[janwesterkamp]

Hi,

when trying to use admonition blocks in AsciiDoc in combination with the Java version of the plugin, they are ignored:

[WARNING]
====
An admonition block may contain complex content.
====

will result in:

An admonition block may contain complex content.

The JRuby version of the plugin is not affected, so it can be used as a workaround.
But the icon font symbol is not shown here too - this might need some configuration or additional fixing...

[rmannibucau]

Hi @janwesterkamp , did you try the syntax $level: ...?

[janwesterkamp]

With the JRuby version I tried to add this:

First i activated the icon font below the head line of the document:

= Headline
:icons: font

Then I added the unicode symbol:

:tip-caption: 💡

or this code:

:tip-caption: pass:[💡]

To render this with an icon:

[TIP]
It's possible to use Unicode glyphs as admonition icons.

But the icon is not showing up in th JRuby version, while nothing but the text is shown in the Java version.

[janwesterkamp]

Hi @janwesterkamp , did you try the syntax $level: ...?

Hi @rmannibucau, not yet - do you have a link to the AsciiDoc reference, whereit's documented how to use this syntax - because I could not find it there yet?

[rmannibucau]

here it is https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/ , the block syntax is just the example syntax which is handle as example, not sure it would be good to make them too specific to admonition outside the visitor/renderer

[janwesterkamp]

here it is https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/ , the block syntax is just the example syntax which is handle as example, not sure it would be good to make them too specific to admonition outside the visitor/renderer

Understand, but I tried the inline variant now too (with JRuby version):

WARNING: Wolpertingers are known to nest in server racks.
Enter at your own risk.

The only difference to the block variant is the width of the rendered box, where I would like to see the icon font logo - it's a little bit smaller than in the block variant, but in both cases nothin is shown inside the box, only the 2nd part with the text.

An additional test with exact the same text shows the same width for the ícon box, so no change because of the variant, inline or block.

[rmannibucau]

@janwesterkamp did the PR for the block support, the icons attribute is not supported as of today (you can check io.yupiik.asciidoc.renderer.html.AsciidoctorLikeHtmlRenderer#visitAdmonition), have to admit I use 100% of the time bootstrap cause asciidoc default css rendering poorly integrates in most websites I'm working on so it often ends as (sharing the cs version cause i have it handy but it is 1-1 in java):

    public override void VisitAdmonition(Admonition element)
    {
        string name = Enum.GetName(element.Level)!;
        builder
            .Append(" <div class=\"alert alert-")
            .Append(
                element.Level switch
                {
                    Admonition.AdmonitionLevel.Note => "info",
                    Admonition.AdmonitionLevel.Tip => "success",
                    Admonition.AdmonitionLevel.Important => "primary",
                    Admonition.AdmonitionLevel.Warning => "warning",
                    Admonition.AdmonitionLevel.Caution => "danger",
                    _ => "secondary",
                }
            )
            .Append("\" role=\"alert\">");
        builder
            .Append(" <h4 class=\"alert-heading\"><b>")
            .Append(char.ToUpperInvariant(name[0]))
            .Append(name[1..])
            .Append("</b></h4>\n");
        VisitElement(element.Content);
        builder.Append(" </div>\n");
    }

I guess icons are supportable (it is just a matter of reporting most of 'icons' test of https://github.com/asciidoctor/asciidoctor/blob/main/lib/asciidoctor/converter/html5.rb either in AsciidoctorLikeHtmlRenderer or a subclass (FontAsciidoctorLikeHtmlRenderer?).

One reason to not have supported it was the fact it still relies on fontawesome 4 whereas we are at version 6 so a full text default renderer is way more robust in time but it can be fancy as using bootstrap or any icon with subclasses or decorators very easily.

[janwesterkamp]

@rmannibucau, I agree, having a text as a default would be nice as a first step, but using icons would solve another issue: i18n
When unsing other languages than English, icons give a nice shortcut solving i18n.

But thanks so far, I am happy to test it, when it's integrated here in Roq.
I checked your PR, the tools-maven-plugin is used here for the AsciiDoc Java rendering? Good to know about that there is a Java alternative to the JRuby rendering! I will have a look on it...

[rmannibucau]

@janwesterkamp yes, ruby solution was way too slow to be usable on some serious websites with java extensions and was bringing way too much deps.
The i18n is naturally solved by having a custom renderer.
Think one bad habit we all have with asciidoctor is to think it covers all possible renderings (font, text, custom font, ...) but concretely it was often a blocker if you need anything more than the default using legacy version for backward compat (was not working well with font awesome 6 at all for ex).
Here the idea is to get a common html rendering customizable at need so literally you can render anything you want (including font, bootstrap, etc) and bonus being up to date with your app stack.
So ultimately a renderer in roq is not shocking for me.

[ia3andy]

So in the end, we would need a way to provide an Asciidoc Renderer as beans in qute-web-asciidoc, then it'll be a matter of adding it as a plugin or directly in your app.

@mcruzdev up to the task?

[ia3andy]

@rmannibucau it would be nice to have ways to customise AsciidoctorLikeHtmlRenderer with post processors on the different visitors or whatever you see fit. Maybe it's already possible but I preferred to ask first?

[ia3andy]

Another idea would be to use templates/formatters for the html snippets and allow to override each of them individually?

[ia3andy]

On CommonMark they allow using what they call Extension for this:
https://github.com/commonmark/commonmark-java?tab=readme-ov-file#extensions

[rmannibucau]

@ia3andy the intent was to not do the same mistake than asciidoctorj with pre/post processors (then you need post-post processors etc). There the model can be rewritten first or with a decorator pattern. So standard usage is to decorate the visitors and if not sufficient rewrite the model before calling the composite visitor.

On the template idea we could do a handlebars (https://www.yupiik.io/fusion/fusion/handlebars.html) template but the thing is that html is just one particular rendering case.

I'm not sure what you are trying to achieve so my answer is quite generic but as of today you can do that, there is just no default visitor relying on yupiik handlebars but it is quite easy to do.

The only intent of AsciidoctorLikeHtmlRenderer was to mainly be able to reuse asciidoctor.css, not to be generic (even if at some point it is).

To use the template solution in minisite for example, it can look tempting but be more complex to manage (in particular in time) so I'm quite mitigated on that.

If you have some concrete use cases we can refine the analyzis if not sufficient.