How to make better the syntax highlighting for Markdown code blocks (Discourse)

1

A Markdown or fenced code block in a post on this discussion forum (Discourse), is a few lines of text in preformatted style, optionally with some color highlighting.

When you write a post or comment in Discourse, you are writing normal text but if you include special Markdown instructions, your text will look a bit better.

Here is a screenshot of a fenced code block, and after that you can see how it’s rendered in Discourse.
image

Those three backticks on an empty line signify the start and end (i.e. the fence) of the code block. Discourse has some defaults in the choice of the highlighting and in some cases the default is not the best choice. Nice colors but distracting.

$ incus launch images:debian/12 mycontainer
Launching mycontainer
$

Can something be done about this?

How could we get better highlighting in the fenced code blocks? By specifying a language for the highlighting. You do that by adding a supported language name on the first line with those three backticks. In the example below I used bash as an example. I think there’s no such language as bash, hence there is no actual highlighting at all.

image

This is the result.

$ incus launch images:debian/12 mycontainer
Launching mycontainer
$

Therefore, we should figure out some highlighting rules that make the incus commands look better. Let’s call it a new incus highlighting language for Discourse.

Do we change something in Discourse?

After some long searching in Discourse, the solution is not in Discourse. Discourse is using an external package, a markdown editor called markdown-it. Still, the highlighting does not happen in markdown-it. markdown-it is using Highlight-JS for the highlighting.

Overall, once we figure out how to add highlighting rules in Highlight-JS, then we can enable that new language in Discourse.

Adding support in Highlight-JS

Here is Highlight-JS and the location with the existing languages.

In the most basic case, the highlighting rules in a new incus language for Highlight-JS should recognize the Incus commands, subcommands, profile content, etc and show them with appropriate nice colors.
Then, this new HighlightJS language would become the default language for code blocks in this Discourse instance.

I have come up to here with this. If someone else want’s to continue on this, post below.

2

Your bash code block is not actually bash. It is a console session. I have also thought about this issue a few times since I used to run my own Discourse server.

I think the best I have come up for that is to use HTML and CSS directly.

It might be worth it to look for competing Discourse plugins. Their might be alternatives with better defaults for our use case.

The code highlighters are good for language like Python and JavaScript. They are not so good for generic preformatted text.

Do you know of any shells or shell plugins that can do what you are describing in a terminal? If so we could extract their coloring rules.

3

1000002564
10000025641152×2496 284 KB

There are a few console and repl examples. This might be easier than I first thought.

$ echo $EDITOR
vim
$ git checkout main
Switched to branch 'main'
Your branch is up-to-date with 'origin/main'.
$ git push
Everything up-to-date
$ echo 'All
> done!'
All
done!
4

In the above case, I would prefer to have incus colored in a specific color (perhaps a color from the logo), then launch as a VERB in a distinctive color, then the image in a separate color, etc.

The Highlight.js code for the shell and bash languages. The shell language is just a prompt and the rest is the bash language.

In a way, the Highlight.JS highlighting rules for the command-line would have similarities to the Bash completion rules.

5

That is what I was thinking too.

There are a few other commands that would be great to have. Like git.

I wonder if the shell completion scripts could be used to create the styling.