stackabletech/documentation

Callouts don't work with highlightjs

fhennig opened this issue · 5 comments

fhennig commented

A Callout is the little number in a circle to annotate source code listings. I've noticed that these don't work on source blocks with highlighting enabled, sadly. It seems like highlightjs is breaking them. I'm unsure what a fix could be.

Here's an example of what it looks like broken: https://docs.stackable.tech/druid/stable/usage.html#_s3_deep_storage

nightkr commented

This seems to be related to our custom UI bundle, switching back to Antora's default bundle seems to "fix" it.

fhennig commented

A bit of research results:

  • The breaking commit seems to be this one: stackabletech/documentation-ui@d5c3d38 Highlight.js was upgraded here, from v10 to v11 with some breaking changes.
  • Callouts work in code blocks without highlighting, i.e. if only [source] instead of i.e. [source,yaml] is used.
  • The default Antora UI has not yet upgraded to highlightjs 11, they are still at v9.

It seems to be that the new highlightjs is breaking the callouts. Downgrading to the latest minor version of v10 (v10.7) fixes this.

Edit: "HTML Passthru" was deprecated entirely, without replacement: highlightjs/highlight.js#2889 https://highlightjs.readthedocs.io/en/latest/upgrade-11.html#feature-removal

This is the feature that we relied on to get the callouts in, they are HTML tags put there by asciidoc. No-one stepped up and developed the necessary plugin.

possible paths forward (in my opinion):

  • I would suggest to downgrade back to 10.7 and stay at that version for a while. We should have a look at upgrading this again in half a year or so, and wait on what antora does for their Default UI, as they are going to face the same problem. I'd suggest to just use their solution (possibly migrating to a different highlighter)
  • We could also try to integrate a custom plugin, but I don't thing it's worth it, we don't need the latest highlighjs features I'd say.
fhennig commented

We decided to downgrade to v10 and look at this again when Antora upgrades highlightjs in the Default UI

stefano-ottolenghi commented

FYI: Same here. I raised an issue on the default Antora UI Bundle, hopefully it will come onto their radars at some point https://gitlab.com/antora/antora-ui-default/-/issues/203

fhennig commented

Hey, thanks for raising the issue there. I'm interested in seeing how it'll go!