Upgrade Highlight JS 10.x

[gquintana]

The current Highlight JS release is 9.18.3

asciidoctor/lib/asciidoctor.rb

Line 360 in 2f62cb1

HIGHLIGHT_JS_VERSION = '9.18.3'

This release has some rendering issues which are fixed in recent releases:
highlightjs/highlight.js#3063

The Highlight JS main author doesn't recommend using these releases 9.x anymore.

However, there is an easy workaround:

:highlightjsdir: https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.1

The 10.7 upgrade was transparent for me, but there may be some breaking changes though:
https://github.com/highlightjs/highlight.js/blob/main/VERSION_10_UPGRADE.md

[mojavelinux]

As you pointed out, there are some breaking changes, including requiring ES6. Therefore, this upgrade must be done in at least a minor release, perhaps even a major release. Fortunately, as you pointed out, there is a workaround since the path to highlight.js is configurable.

[rnett]

Highlight JS is now up to 11, which contains a number of improvements to highlighting that would be nice to have (for me, it's mostly that shell sessions are better supported). However it no-longer supports asciidoc callouts because the HTML-passthrough was removed. It would be extremely nice if asciidoctor could upgrade the default Highlight JS version and fix that.

[mojavelinux]

We understand that this is a desired feature, but we can't do it yet for reasons already stated.

However, the syntax highlighter is pluggable. So there's nothing preventing you from extending the highlightjs adapter and plugging in your own version of highlight.js. See https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/custom/#new

[bric3]

Just for information if you can control how syntax highlighting is initialized. It's possible to register the removed feature as a plugin as described in highlightjs/highlight.js#2889.

At this time, registering this plugin manually works (restores the callouts) with 11.6.0.

[mojavelinux]

That's great news, @bric3. Thanks for sharing!

[dhendriks]

This issue is almost 3 years old. Isn't that enough time for a new release that can switch to a new highlight.js version? highlight.js 9 is no longer supported, the documentation can't be found online anymore, it has security issues, bugs, etc. Seems to me it would be a good idea to upgrade.

[dhendriks]

And see asciidoctor/asciidoctorj#1258 for more practical reasons why I think it is time to upgrade.

[ggrossetie]

This issue is almost 3 years old. Isn't that enough time for a new release that can switch to a new highlight.js version?

Asciidoctor is an open-source project. Feel free to do the required work to ensure that we can safely upgrade while preserving existing features (backward compatibility) such as callouts.

highlight.js 9 is no longer supported, the documentation can't be found online anymore (...)

That's out of our control.

(...) it has security issues, bugs, etc. Seems to me it would be a good idea to upgrade.

We agree but nobody has come forward to do it.

[mojavelinux]

I have emphasized time and again that highlight.js 10 introduced breaking changes that cause some of the functionality provided by Asciidoctor to not work. If those can be addressed, then we can upgrade (in 2.1.x). Until then, we are sticking with highlight.js 9, which we know works.

You are also free to implement your own adapter and use whatever version and integration of highlight.js you want. See https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/custom/ (you could also extend the built-in adapter and customize it).

[mojavelinux]

This issue is almost 3 years old. Isn't that enough time for a new release that can switch to a new highlight.js version?

No, it's not enough justification for a new release. That assumes we live in a bubble where the only thing we have to worry about in the whole world is this particular integration. It's a far more complex story than that, and far more important issues to address. In open source, 3 years can go by in a blink of an eye with all the activity that occurs.

Having said that, I have put the offer on the table for how this can be addressed and someone will need to step up to do the work or else we will stay with highlight.js 9 indefinitely.