Multiple ways to syntax highlight code blocks.. confusing


I have been using the fence highlighting method just fine using Pygments. Let’s call this fencehl method for further reference below.

 <!-- some code -->

But I see [here][1] that we also have a *shortcodes* version too. Let's call this **shortcodehl** method for further reference below.

{{< highlight html >}}

{{< /highlight >}}

What are the main differences between the two approaches?

I believe `fencehl` works **only** if you use *Pygments* (if you have `pygmentsCodeFences = true` in your `config.toml`).  Is that right?

Does the `shortcodehl` approach work whether you use *Pygments* or client-side JS for highlighting?

If I use `fencehl`, and *Pygments* is not available, the resultant HTML looks like a mess (it's not rendered even as a black and white `<pre>` block!). Is that a bug?

If I use `shortcodehl`, and if *Pygments* is not available, what happens? 

If I have highlighting JS in the `static/` dir, and *Pygments* is available, can I set a priority like below?

1. Use *Pygments* if available
2. Else use highlighting JS if present
3. Else make the code blocks plain black and white `<pre>` blocks.

I apologize for these many questions. But as there are multiple options available and as many aspects of those are confusing, I want to make sure I pick the right way and use it consistently in all my blog posts.


A1. There’s very little difference, actually. The shortcode predates the Github-style code fencing. The only real difference I can see is that if you enable pygmentsCodeFences, all code fences will be parsed by pygments.

A2. Yes

A3. No, shortcodehl requires pygments. Two ways to do the same thing.

A4. You’ll get a warning message on the command-line, and the raw content inside the shortcode will be inserted into the HTML output. Seems like we should wrap the code in a <pre> block instead of just returning the raw source with no block around it.

A5. See A4.

A6. Not sure. I would pick one or the other. You may be able to use code blocks and have it fall through like that, but I haven’t tested that.

1 Like

That is not true.

You must have pygmentsCodeFences + a code block with a language indicator or pygmentsCodeFences+ pygmentsCodeFencesGuessSyntax … pygmentsCodeFences = true only is in line with how GitHub does it.

1 Like