No longer compatible with MkDocs static-site generator

[kxcontrib]

The MkDocs static-site generator has a code-highlighting plugin based on Pygments. We use Prism instead, because it supports the q (kdb+database) language.

code.kx.com

Trying to upgrade Prism, I cannot find a current JS that works. With my 2017 JS everything works. Switch in a current JS or link to the CDN and highlighting disappears. No warning or error in the browser console. Problem is reproducible from the minimal MkDocs instance created by mkdocs new command with inclusion of folders docs/scripts and docs/stylesheets. (Attached.) Configuration file:

#  MkDocs sandbox for testing features
extra_css:
  # - stylesheets/prism.css
  - 'https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.1/themes/prism-solarizedlight.min.css'
extra_javascript:
  - 'https://code.jquery.com/jquery-3.4.1.min.js'
  - scripts/prism0.js
  # - scripts/prism.js
  # - 'https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.1/prism.min.js'
site_name: Sandbox

Above, prism.js is the minimal file downloaded currently from prismjs.com, and prism0.js is the corresponding file from August 2017.

We value the code highlighting Prism gives us and want to stay current.

Attached is a ZIP of the entire MkDocs instance.

archive.zip

[RunDevelopment]

That's because scripts/prism0.js is a bundle created by our download page which includes a few languages and plugins.
Both scripts/prism.js and https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.1/prism.min.js are the standard Prism bundle which only includes HTML, JS, and CSS (and some other minor stuff) but not Q (kdb+ database). You didn't get any error message because Prism highlights code in an unknown language with the empty grammar, so you don't get any highlighting. (This is useful because plugins are still active, so you can have e.g. code block of plain text with line numbers)

To get the latest version of your prism0.js bundle, follow the link in the comment to our download page. There you can download the latest version of Prism with our bundle configurations.

If you want to use a CDN, then check out the basic usage section about CDNs.

[kxcontrib]

Thanks for the prompt response, but that is not the problem I need to report!

The prism.js bundle here deliberately includes only basic highlighting in order to replicate the problem with minimal features. So the opening code fences in docs/index.md are labelled txt and css respectively. The issue here is that prism.js isn’t modifying the DOM, so no highlighting happens at all.

It does puzzle me that this happens with no warning or error message in the console.

I do appreciate that Prism doesn’t claim to support HTML generated by MkDocs (attached). But it used to (try switching in prism0.js from 2017), we value that, and wish it would do so again.

html.zip

[mAAdhaTTah]

The issue here is that prism.js isn’t modifying the DOM, so no highlighting happens at all.

It wouldn't doing any highlighting off the DOM if the language isn't included in the bundle. How did you get the updated bundle?

[kxcontrib]

Apologies that I’m struggling to make this clear. The test site, designed to replicate the issue minimally, is generated from Markdown code fences labelled txt and css. The Download button at prismjs.com leads to

https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript

from which the downloaded prism.js file should find and modify the CSS code block. (Actually, also the TXT block, using the default grammar. My experience with the 2017 JS is that only unlabelled code fences in the Markdown produce code blocks that Prism ignores.) The easiest way to observe this is, factoring out the Prism theme, is to inspect for the Code button that the JS inserts into the DOM as the last child of the code element.

Thanks for your patience.

[RunDevelopment]

So the opening code fences in docs/index.md are labeled txt and css respectively.

That's the problem. The generated code blocks will get the class txt and css respectively but Prism requires language-txt or language-css to detect the language.
To fix that, prism0.js contains a small JQuery function (the first few lines of code) which transforms e.g. css -> language-css. This function isn't from us. It's likely from your predecessor.

[ghost]

That’s not the problem. The code fences (a Markdown, not HTML, feature) are labelled correctly. From them, the MkDocs site generator then produces HTML code elements with language-txt and language-css classes, visible in the HTML attached to my last message. If this were not so, the 2017 prism0.js could not be working. Stephen Taylor | Librarian | *Kx* | +44 7713 400852 | [email protected]

…

On Mon, 21 Oct 2019 at 10:32, Michael Schmidt ***@***.***> wrote: So the opening code fences in docs/index.md are labeled txt and css respectively. That's the problem. The generated code blocks will get the class txt and css respectively but Prism requires language-txt or language-css to detect the language. To fix that, prism0.js contains a small JQuery function (the first few lines of code) which transforms e.g. css -> language-css. This function *isn't* from us. It's likely from your predecessor. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#2099?email_source=notifications&email_token=AE62DADCI5ZFCD22KDKB6R3QPVZJ5A5CNFSM4JCVMBEKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBZV7OQ#issuecomment-544432058>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AE62DADQ2NNQ6QGGLZWMYVTQPVZJ5ANCNFSM4JCVMBEA> .

[RunDevelopment]

From them, the MkDocs site generator then produces HTML
code elements with language-txt and language-css classes, visible in the
HTML attached to my last message.

They are not labeled language-css. This is a part of index.html in your attached html.zip:

<p>And some CSS:</p>
<pre><code class="css">*, .none {
    border-color: red;
    margin: 0;
    padding: 0;
}
</code></pre>

If this were not so, the 2017 prism0.js could not be working.

As I said, prism0.js contains a little function which transforms the classes. This function:

/*	Code syntax highlighting in code.kx.com
-------------------------------------------
	Pygment highlighting disabled – switched off Markdown extensions codehilite and superfences
	This leaves eg <pre><code class="java">… in MkDocs output. 
	Now need to switch to <pre><code class="java language-java">… as per http://prismjs.com/index.html#basic-usage
*/	
$("pre code").each(function(){
	var c = $(this).attr('class');
	if( c ) {
		$(this).addClass('language-'+c);
	}
});
/* End of Kx hack -------------------------- */

So executing this function before Prism should make everything work again.

[ghost]

My apologies: it should have occurred to me to look for a local hack. Thought I’d learned by now:

It’s not what you don’t know that gits you. It’s what you know for certain that jest ain’t so.
— Mark Twain

[RunDevelopment]

No problem. I assume that means the problem is resolved?

[ghost]

It does. Thanks for your help. Stephen Taylor | Librarian | *Kx* | +44 7713 400852 | [email protected]

…

On Mon, 21 Oct 2019 at 14:58, Michael Schmidt ***@***.***> wrote: No problem. I assume that means the problem is resolved? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#2099?email_source=notifications&email_token=AE62DAEWYIHBD74WRLI6K53QPWYQHA5CNFSM4JCVMBEKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEB2NIHQ#issuecomment-544527390>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AE62DABHOOTRLZPOXDRGY3LQPWYQHANCNFSM4JCVMBEA> .