Either bypass processing a code block, or support embedded markup?

[ghannington-Rocket]

Background to this issue

Yesterday, the proprietary DITA-to-HTML software that I use unexpectedly changed from using highlight.js to react-syntax-highlighter.

(Whether the implementation of react-syntax-highlighter in that software still uses highlight.js "under the hood", as the react-syntax-highlighter docs put it, I couldn't currently say. I've only just started reading about react-syntax-highlighter.)

This unexpected change has broken some code blocks in my docs. 😒 "Broken", in the sense that code blocks in the HTML now omit content that, in the DITA source, is wrapped in embedded markup. The content of the code block is now incomplete; garbled.

One problem here is that these code blocks used to bypass the automated syntax highlighting by highlight.js.

That is, if a DITA <codeblock> element specified a "bogus" outputclass attribute value such as "language-plain-text-xyz", then that value would get passed through to the class attribute of the HTML <pre> element; highlight.js wouldn't recognize that value as a supported language, and would not perform syntax highlighting on the contents.

I used that technique to deliberately bypass syntax highlighting, just to support embedded markup that italicized placeholder variables in code blocks. Yes. in some cases, I use code blocks for code where some values are represented by placeholder variables that are described in the surrounding text. You could argue that this is a semantically inappropriate use of code blocks, because placeholder variables aren't actual code.

In HTML, and also in PDF (the same DITA gets transformed to HTML and PDF), I want placeholder variables to be rendered in italics. You could say that's the real cause of the problem here: me wanting those variables to be rendered in italics. (Can't I just be happy wrapping such variables in angle brackets instead?)

I used to be able to bypass highlight.js, "manually" insert markup to perform syntax highlighting using the hljs-* class attribute values (defined in CSS), and also use the DITA <varname> element. Example DITA source:

<codeblock scale="100" outputclass="language-plaintext-xyz"><ph outputclass="hljs-attr">connect:</ph>
  <ph outputclass="hljs-attr">enabled:</ph> <ph outputclass="hljs-literal"><varname>boolean</varname></ph> <ph outputclass="hljs-comment"># Default at this level: false</ph>
</codeblock>

Is this madness? To apply all that syntax-highlighting markup manually, just so that I can render the placeholder variable "boolean" in italics? Perhaps. But, it worked: in HTML, I got color syntax highlighting with placeholder variables in italics; in PDF, while I didn't get color syntax highlighting, at least placeholder variables were in italics.

I always knew using those hljs-* class names was perilous. But I can see that the CSS file used by the proprietary docs build software still contains those hljs-* classes (although, the colors are different to the colors now used by react-syntax-highlighter; maybe that tells me it's not using highlight.js under the hood).

If I could only bypass react-syntax-highlighter processing of a code block, as I used to be able to bypass highlight.js processing, then there's a chance that my manually-marked-up code blocks would return to their former state, with all content intact.

Specific questions for this issue

• (How) can I instruct react-syntax-highlighter to bypass processing a code block? I understand that this might be a difficult question to answer directly; especially, in the context of the DITA source markup. I'm using a "black box" to transform DITA source to HTML; I don't expect anyone reading this to know the internal workings of that black box. A more specific question, then, perhaps more answerable: are there any attribute values of, say, an HTML <pre> element that would cause react-syntax-highlighter to bypass processing the contents of that element?

• Can I have my cake and eat it too? That is, does react-syntax-highlighter support embedded markup? If so, how? Or, similarly but not quite the same: is there some way that I can give a hint to react-syntax-highlighter that some content in a code block is a placeholder variable, and so, should be rendered accordingly (in italics)? Although, I realize that, if I have to forgo embedded markup, then PDF output (where react-syntax-highlighter is not involved) will not have italicized placeholder variables. That would be a problem for me, and for users who prefer PDF to HTML (such users exist in significant numbers).

Or... given the background I've described, any other advice anyone is willing to offer me. 🙂