Open root

Syntax Highlighting

Deciding how to add syntax highlighting within code blocks on your website is no small feat. There are various different tools premised upon different architectures. The documentation below attempts to provide a guide to some currently popular approaches.

Goals

The criteria which influenced the syntax highlighting system & theme on this website are included below for context:

Tools

The following tools were considered for the syntax highlighting of this website:

highlight.js

In the end, highlight.js was the simplest to integrate into the website. The usage documentation clearly describes how to get started. The demo made it easy to explore the various themes as well. It checked all the boxes.

Prism

Compared to highlight.js, Prism proved slightly more difficult to integrate into this website due to its different naming scheme for fenced code blocks. For example, rather than "scala", Prism expects "code.language-scala". While such a modification is achievable, it was an unnecessary hurdle at the gate.

In reality, Prism looks slightly more modern and standards-compliant than highlight.js. In the future, it may be worth revisiting it for this website.

Linguist

According to this StackOverflow answer, Linguist (which was originally created & used by GitHub) is not really meant for syntax highlighting:

Linguist only detects the language of files; it doesn't perform the highlighting itself.

Also, according to GitHub's own documentation, Linguist delegates syntax highlighting to third-party grammars:

We use Linguist to perform language detection and to select third-party grammars for syntax highlighting.

Pygments

Pygments has been used by some major websites (i.e. Wikipedia, GitHub, etc.), lending it serious credibility. However, it seems GitHub has moved away from it for performance reasons based on some online discussions. It seems to be an older solution overall. Additionally, compared to highlight.js results, Pygments produced less differentiated results; some elements which were differentiated by highlight.js were conjoined by Pygments. Obviously, the sample size of this testing was small, so account for that. Finally, it was significantly more difficult to integrate. Nonetheless, if you do want to explore the various themes, you can do so at this website. If you want to experiment with it further, you can try out the demo.

The research process for this website also unveiled some interesting projects in the Pygments ecosystem. They are listed below:

Rouge

Rouge is the least researched among the group. Its proximity to Ruby did not align with this website's goals. However, if you want to explore Rouge's available themes, you can do so here.

code-prettify

Google's involvement lent this project some credibility at first, but it quickly became clear that it is not actively maintained. Additionally, this discussion about why Meta Stack Overflow switched from Prettify to highlight.js provides details about the differences between the two systems.

Themes

Literally dozens of themes were considered for use on this website, but these few stood up best to the criteria which led the search.

Base16

The Base16 project drastically simplifies discovery and integration of many popular themes within a diverse set of clients (i.e. JetBrains IDEs, Xcode, etc.). This preview tool makes it easy to experiment with all the available themes. When you need to decide on a pleasant theme for your project, start here.

Dracula

The Dracula theme stands out due to its remarkable website which documents how to integrate it into over 100 tools. If only all themes had such great documentation. While it was very tempting, the bright neon colors proved too distracting for this website.

Nord

The Nord theme is elegant and minimalist. It even has a stunning JetBrains IDE integration. Despite its charm, actual usage proved Nord offers too little differentiation between elements. It is also worth mentioning that it iss not actively maintained.

One Dark

Of all the themes investigated for this website, Atom's One Dark theme came out on top due to its bright color palette, rich integrations, and sibling light theme.

References