How to override listing/source block default syntax highlighting via highlightjs 11

[blackace72]

Description

Previously in version 2.9.8, I was able to "override" syntax highlighting within source blocks by using text spans and built-in roles. For example, when I wrote this in my asciidoc:

[source,python,subs="+quotes"]
----
def [user-var]#my_function#(bull):

How about [user-var]#now?#

# in a comment [user-var]#testing#

----

this would be the resulting output in 2.9.8 (the bottom block in the picture uses aforementioned asciidoc source code):

However, now I am using version 3.0.1 and this doesn't occur anymore. In fact, when inspecting the text in the rendered preview using developer tools, it appears that the text-spans are just swallowed up:

3.0.1 rendering of syntax highlighting

(when inspecting the elements of the second block):

I know previously in 2.9.8 I had asciidoc.use_asciidoctor_js: false in my JSON config, and now it is completely irrelevant (i.e. you must use asciidoctor_js), so I believe it might be a limitation of asciidoctor_js.

Is there actually a way to get the desired behavior with this newer version, or is it a limitation?

System Information

Version: 1.69.1 (Universal)
Commit: b06ae3b2d2dbfe28bca3134cc6be65935cdfea6a
Date: 2022-07-12T08:21:51.333Z
Electron: 18.3.5
Chromium: 100.0.4896.160
Node.js: 16.13.2
V8: 10.0.139.17-electron.0
OS: Darwin arm64 21.4.0

To Reproduce

Steps to reproduce the issue:

1. Create a stylesheet to link to the asciidoc-vscode extension. Within it, add two statements:

.user-var {color: #82a0ff !important; text-transform: uppercase !important; font-style: italic;}
.user-var * {color: #82a0ff !important; text-transform: uppercase !important; font-style: italic;}

2. Put the stylesheet within the workspace of your asciidoc files, and entrust that workspace; link the stylesheet within extension settings
3. Create a new asciidoc file testing_file.adoc inside the workspace.
4. In version 2.9.8, write the following within the document:

= Testing
:source-highlighter: highlight.js
:highlightjs-theme: dracula


Normal python source code:

[source,python]
----
def my_function(bull):

How about now?

# in a comment testing
----

Let's try python with user-defined stuff:

[source,python,subs="+quotes"]
----
def [user-var]#my_function#(bull):

How about [user-var]#now?#

# in a comment [user-var]#testing#

----

5. Render a preview and notice the results
6. Switch to extension version 3.0.1 and repeat steps 4 & 5, but with:

- :highlightjs-theme: dracula
+ :highlightjs-theme: base16/dracula

[ggrossetie]

This "feature" has been removed from Highlight.js 11:

• https://highlightjs.readthedocs.io/en/latest/upgrade-11.html#feature-removal
• Deprecate HTML auto-merging from core (plugin may be needed) highlightjs/highlight.js#2889

[ggrossetie]

In my opinion, you should create a custom syntax highlighter for Highlight.js or use/create a new syntax highlighter adapter for Prism: https://docs.asciidoctor.org/asciidoctor/latest/syntax-highlighting/custom/#new which seems to support this feature: https://prismjs.com/plugins/keep-markup/

[blackace72]

Thank you for the suggestion. I am trying to understand the source code enough to get things going. If you don't mind, I have a question regarding the file asciidoctParser.js. It has a constructor functions in its class, with a apsArbiter = null parameter, like so:

//asciidocParser.js
class AsciidocParser {
    constructor(extensionUri, apsArbiter = null, errorCollection = null) {
        this.errorCollection = errorCollection;
        this.apsArbiter = apsArbiter;
        /*...*/
        }
    }

I am not sure what this is for. And further down in the file, there is this function:

confirmAsciidoctorExtensionsTrusted() {
        return __awaiter(this, void 0, void 0, function* () {
            /*...*/
            return this.apsArbiter.confirmAsciidoctorExtensionsTrustMode(extensionsCount);
        });

I am confused as to how the confirmAsciidoctorExtensionsTrustMode() function can be called on this null property?

[ggrossetie]

null is the default value not the actual value:

asciidoctor-vscode/src/asciidocEngine.ts

Line 28 in e6035b2

this.ad = new AsciidocParser(this.extensionPreviewResourceProvider.extensionUri, this.apsArbiter, this.errorCollection)

[blackace72]

Are we able use a syntax highlight adapter within the .asciidoctor/lib (the way we enable/register extensions)?

I see there is a npm package called asciidoctor-prism-extension. I installed that within the .asciidoctor workspace (i.e. it's now in this location: asciidoctor/node_modules/asciidoctor-prism-extension).

I then tried to register it the same way I registered the asciidoctor-emoji extension/package as shown in the docs;
i.e. I created a file .asciidoctor/lib/testing_emoji.js, then put this inside testing_emoji.js:

module.exports = require('asciidoctor-emoji');

However, this same method didn't work for enabling the asciidoctor-prism-extension package, because the main file (index.js in this case) uses some notation with $$:

https://github.com/thom4parisot/asciidoctor-prism-extension/blob/448b8a11f1a08bfb2ed8e88f78434101cd3a919b/index.js#L92-L97

Is there anything I can change the $$ strings to in order to make this work? Or maybe syntax highlighters can't be registered within .asciidoctor/lib?

[ggrossetie]

Yes it's possible but you will need to hook on the register function:

/* global Opal */
const PrismExtension = require('asciidoctor-prism-extension')

// fixme: add additional Prism languages...
Prism.languages.python = /* ... */

// fixme: add KeepMarkup plugin
Prism.plugins.KeepMarkup = /* ... */

module.exports.register = function register (_) {
    Opal.Asciidoctor.SyntaxHighlighter.register('prism', PrismExtension)
}

Don't forget to include a Prism theme in your custom stylesheet and set the source-highlighter:

= Prism
:source-highlighter: prism

[source,python,subs="+quotes"]
----
def #my_function#(bull):

How about #now?#

# in a comment #testing#
----

Here's the result: