Callouts don't work with highlightjs

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

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

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.

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

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

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

Navigation Menu

Repository navigation

Callouts don't work with highlightjs #232

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Callouts don't work with highlightjs #232

Description

Activity

nightkr commented on Aug 23, 2022

fhennig commented on Sep 13, 2022

fhennig commented on Sep 19, 2022

stefano-ottolenghi commented on Feb 13, 2023

fhennig commented on Feb 15, 2023

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions