Code Highlighter for Website in ↓markdown↓ CMS

This article discusses syntax highlighting source code on web pages. If you know what syntax highlighting is and just need to know how it is done in a ↓markdown↓ CMS based website, then jump to the implementation section. Otherwise read on for some background.

A lot of websites on the Internet show code snippets, settings and other types of data. When displaying code or data on a webpage it needs to stand out from descriptive text and retain the formatting. This is achieved firstly by using the pre (for preformatted) HTML tag, which preserves the white space in a section of text. Without the pre tag browsers will collapse multiple normal whitespace characters (space, tab and line breaks) to a single space. This would destroy the layout of source code, or other text that relies on white space for formatting, e.g. verse or poetry.

Secondly, the HTML specification also defines the code tag for wrapping source code. This commonly uses a monospace font for displaying the text between the start and end code tags.

Thus the display of computer code in HTML uses a combination of pre (to preserve formating) and code (for a monospace font). This combination is now common practice and was used in the original Markdown text formatting rules. The pre and code tags are used to trigger code highlighting in the HTML.

What is Code Highlighting or Syntax Highlighting?

Code highlighting changes the text color of different elements of the source code being displayed. It assigns different colors to items such as computer language keywords, variable values and line terminators. This makes it easier for the code to be read and digested. Code highlighting for a web page allows a visitor to see the code clearly amongst the descriptive text. Here is an example of some code (which shows how code is wrapped in HTML):

<pre><code>
10 print "Hello"
20 goto 10
</code></pre>

The above example highlights different parts of the code for easier comprehension. This code highlighting is also known as syntax highlighting or code colorizing. There are many different tools, scripts and utilities available to do code highlighting. A common method for web pages is to use JavaScript and Cascading Style Sheets (CSS) to spot the pre and code tags and then apply the colorizing styles to the source code. This technique is used for a ↓markdown↓ CMS based website, using an open source code highlighter.

The Syntax Highlighter Implementation in ↓markdown↓ CMS

With ↓markdown↓ CMS all sorts of web sites can be built, including sites that need to display snippets of code, configuration settings, HTML or other types of computer files. Therefore ↓markdown↓ CMS needs to support syntax highlighting. In ↓markdown↓ the source code colorizing is performed by a JavaScript library called highlight.js.

The pre and code tags are detected by highlight.js and the code colorizing styles applied. The highlight.js files are hosted on a Content Delivery Network (CDN). The means just three lines of code in the hearder of a HTML file gets code syntax colorised:

<link rel="stylesheet" href="//cdn.jsdelivr.net/highlight.js/9.2.0/styles/default.min.css">
<script src="//cdn.jsdelivr.net/highlight.js/9.2.0/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

These three lines are added automatically by ↓markdown↓ CMS to a web page if the Syntax ↓markdown↓ tag is add to the metadata section. In the following simple metadata section syntax highlighting has been enabled for the web page by setting Syntax to yes:

/*
Title: Example Web Page Title
Description: About the web page.
Syntax: yes
*/

Here's an example Java function highlighted:

public static boolean isPrime(long N) {
  // Trial divide the positive integer N by the primes from 2
  // Returns true if a prime divisor found, or false if none found
  if (N%2 == 0) return false;//Eliminates evens
  if (N%3 == 0) return false;//Eliminates multiples of three
  // No need to go past the square root of our number (see Sieve of Eratosthenes)
  long Stop = (long) Math.sqrt(N);
  // Okay, lets "wheel factor" alternately adding 2 and 4
  long di=2;
  for(long i=5; i<=Stop; i+=di, di=6-di) {
    if (N%i == 0) return false;
  };
  return true;
}

If the Syntax setting is blank or missing or set to no then no syntax highlighting occurs on the web page.

Using highlight.js Locally

If the website requires a local copy of highlight.js this can be done by placing the files into a subfolder off the md directory. This sub-directory must use all lowercase characters in the name. The md directory is where ↓markdown↓ CMS is installed. Download a custom highlight.js package and unzip the highlight.zip file into the new folder under the md directory. The important files are the highlight.pack.js file and the styles folder containing the CSS.

The local copy can be used by setting the Syntax tag to the name of the created directory. For example if the directory created was called color-it:

/*
Title: Example Web Page Title
Description: About the web page.
Syntax: color-it
*/

Obviously the directories cannot be called yes or no (any capitalisation) as those values are required for other uses.

Changing the Highlighting Colors

There are many colorizing styles supported by highlight.js. To use one of these styles set the ↓markdown↓ CMS SynStyle tag to the name part of the relevant style sheet. For example one of the style sheets is called github.css for GitHub style colorizing. To use this style the SynStyle tag is set to github:

/*
Title: Example Web Page Title
Description: About the web page.
Syntax: yes
SynStyle: github
*/

This works for both CDN and local hosting of highlight.js. To determine the names of the various CSS files:

• Look in the styles directory in a downloaded highlight.zip package.
• Use the style name on the highlight.js demo page, lowercasing the name and using - (hyphen) to replace the spaces.
• View the style files on the GitHub repository.

Note: ↓markdown↓ CMS currently uses the highlight.js autodetect feature for determining the computer language syntax to apply.

See Also

For other articles on using ↓markdown↓ CMS see the post Build a Website from Scratch with ↓markdown↓ CMS.