Allow markup in highlighted code block

[KyleMit]

Follow up to #15 add syntax highlighting

Allow pre-escaped code to include markup that will be preserved when adding syntax highlighting

For example, in github and stackoverflow, you can include html tags in pre-escaped code blocks:

<pre><code>&lt;a href="<b>url</b>"&gt; Link &lt;/a&gt;
</code></pre>

Which renders like this (with a bold tag around "url")

<a href="url"> Link </a>

So ideally, this markdown code sandbox would work

This might not be well equipped for markdown-it

References:

• How can I trigger highlight function for markdown code block with four whitespace #515
• Highlight function not called for all code blocks #130
• How to add syntax highlighting to indented code blocks using github flavored markdown

Maybe markdown-it-highlightjs will work with raw code blocks

[KyleMit]

Possible syntax:

```js raw
CONST token = "<mark>your_token</mark>"
```

The way markdown-it hands off rendering to the fenced code block, it will parse any information that occurs after the initial ``` and will pass language like this:

langName = info.split(/\s+/g)[0];

Which means we cannot add spaces before any potential additional parameters - which breaks most language recognition in markdown rendering for github and vscode

If we do have to delimit with a character, I tried following the language tag with each of the following special chars |/,.-1?*_%$# in github, and the only one that was still correctly formatted was using the , like this:

```js,raw
CONST token = "<mark>your_token</mark>"
```

Which returns this:

CONST token = "<mark>your_token</mark>"

So we either need the resolution of #626 Pass additional context to highlight option from fence renderer or need to extend fenced code block handler

Prior Art (Possible Syntaxes)

Python - Fenced Code Blocks

~~~~{.python hl_lines="1 3"}
# This line is emphasized
# This line isn't
# This line is emphasized
~~~~

or

```python hl_lines="1 3"
# This line is emphasized
# This line isn't
# This line is emphasized
```

Eleventy - Syntax Highlighting Plugin

{% highlight js 1,3-5 %}
function myFunction() {
  // …
  return true;
}
{% endhighlight %}

Pandoc - Fenced Code Attributes

~~~~ {#mycode .haskell .numberLines startFrom="100"}
qsort []     = []
qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
              qsort (filter (>= x) xs)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

JIRA Advanced Formatting

{code:title=Bar.java|borderStyle=solid}
// Some comments here
public String getFoo()
{
    return foo;
}
{code}

[KyleMit]

How to allow markup in pre-escaped code block in node.js

Out-of-the-box, highlight.js needs to be run in browser in order to preserve HTML markup within a code block

Here are a couple reference issues submitted to highlightjs:

• #1603 HTML tags inside code?
• #2064 Feature Request: hljs-callout
• #1592 A link inside the highlighted code block
• #2126 Hide tags such as span and code?

All of which rely on using hljs.highlightBlock(node) which:

Applies highlighting to a DOM node containing code.

Here's an example of highlighting pre-escaped code using the browser API (live demo):

<pre><code class="language-html" id="block">
    &lt;a href="<mark>url</mark>"&gt; Link &lt;/a&gt;
</code></pre>
<script>
hljs.highlightBlock(document.getElementById('block'));
</script>

Option A - Wrapper

The implementation of highlightBlock does three core things:

1. Parse text from block of html
2. Call the method hljs.highlight
3. Combine original HTML with Highlight Markup

If we can stub 1 & 3 in node, we can call highlight ourselves

Parsing HTML Text

Here are some strategies for extracting the text from an html block (live demo)

• Strip HTML from Text JavaScript
• How can I extract the textContent from an HTML string without creating a HtmlElement?
• Extract the text out of HTML string using JavaScript
• Get the pure text without HTML element by javascript?

However, most suggestions rely on having access to the browser by using node.textContent or node.innerText

There are a couple regex options, but they feel brittle

Merging both html streams also feels non-trivial, so I stopped here

Option B - Add Window to Node

We can install window as an npm package and then use like this:

const hljs = require("highlight.js")

let lang = "html"
let htmlRaw = `&lt;a href="<mark>url</mark>"&gt; Link &lt;/a&gt;`

// create window
const Window = require('window');
const window = new Window();

// make document available globally w/o let
document = window.document

// create text as node
let pre = window.document.createElement('pre');
pre.innerHTML = `<code class="language-${lang}">${htmlRaw}</code>`
let node = pre.childNodes[0]

// highlight node
hljs.highlightBlock(node)

console.log(node.innerHTML);

The biggest tradeoff here is that you need to make document available globally because highlightBlock needs to be able to call document.createElement('div')

I added a minimal, complete verifiable example using node.js in KyleMit/highlightjs-markup