Coders' Guidebook

How to display example code on your website

In this tutorial, you will learn how to display code on your blog/website that readers can copy and paste with ease. We will also cover how to customise the appearance of the code and utilise add-ons such as line numbering and line highlighting.

display-example-code-on-your-website-using-highlight.png display-example-code-on-your-website-using-prism.png

Display code using highlight.js

Using highlight.js on your webpage

Highlight.js is a JavaScript package that allows you to add example code to your webpages. Highlight.js is a relatively simple code highlighter and does not allow you to add line numbers or highlight lines of code (see Prism if you need this functionality); however, it is one of the best at understanding how different code languages should be displayed. Highlight.js also comes with themes that allow you to customise the appearance of the code you're displaying. Ready-made themes include Android Studio, Github and Google code, so your code can emulate many popular platforms.

To incorporate highlight.js into your webpage, visit their website and copy their readymade jsdelivr CSS and JavaScript links into the head element of your HTML file:

<head>
	<!-- other content of the head element goes here -->
	<link rel="stylesheet" href="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.16.2/build/styles/default.min.css">
	<script src="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.16.2/build/highlight.min.js"></script>
</head>

Notice how the link to the stylesheet ends 'default.min.css'. You can change the theme of your example code by replacing the word 'default' with any of the other styles shown in this demo. If the theme name includes spaces then make sure you replace them with a hyphen. For example, if you wanted to use the Atelier Estuary Dark theme then your entry into the head element would like this:

<head>
	<!-- other content of the head element goes here -->
	<link rel="stylesheet" href="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.16.2/build/styles/atelier-estuary-dark.min.css">
	<script src="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.16.2/build/highlight.min.js"></script>
</head>

Once you have added the links to the CSS stylesheet and JavaScript files, there is just one more line of code you need to write into the head element of your HTML page. Add this script to activate highlight.js and set it to work on your example code:

<script>hljs.initHighlightingOnLoad();</script>

Altogether, the head element should look like this:

<head>
	<!-- other content of the head element goes here -->
	<link rel="stylesheet" href="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.16.2/build/styles/default.min.css">
	<script src="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@9.16.2/build/highlight.min.js"></script>
	<script>hljs.initHighlightingOnLoad();</script>
</head>

Adding example code to your webpage

Now your webpage is equipped to use highlight.js, you can write the example code that will displayed to your readers. Simply write the example code at your chosen location within the body element of your HTML page and enclose it inside opening <pre><code> and closing </pre></code> tags. In case you're curious, the 'pre' tag refers to preformatted text and the 'code' tag indicates a section of code.

An advantage of using highlight.js is that it can tailor its highlighting approach to the programming language you wish to display. To tell highlight.js which programming language you are using, add the language name as a class inside the opening <code> tag. For example, you could display HTML code on your webpage like this:

<pre><code class="html">
<!DOCTYPE html>
<html lang="en-GB">
<head>
	<title>Home</title>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" type="text/css" href="main.css">
</head>
<body>
	<h1>My nature and wildlife blog</h1>
	<img src="tree.jpg" alt="Tree" class="photo"/>
</body>
</html>
</code></pre>

A full list of supported languages and corresponding classes can be found here.

warning.png'Escape' your example code to ensure it is read as text. You may notice when you load your webpage that your example code is invisible. This is likely because the web browser is reading your example code as HTML code instead of text. To resolve this, you must convert some of the symbols in your example code (e.g. <, >, & and ") to 'entities'. An entity is a short sequence of letters and symbols that represents an item of punctuation. For example, &quot; is the entity for the " symbol. While you could go through your example code and convert each punctuation symbol to an entity one-by-one, a much quicker way is to copy and paste your example code into an 'HTML escape' tool. Once you have escaped your example code, you can copy it back into your HTML file between the opening and closing 'pre' and 'code' tags and it should now display correctly.

Display code using prism.js and its plugins

prism-code-highlighting.png

Using prism.js on your webpage

An alternative syntax highlighter to highlight.js is prism.js. While prism.js may not be quite as adept at understanding the nuances between different coding languages, it does come with more plugins and themes to help you customise the look of your code. To use prism.js, you should first visit their website and download a javascript file and a CSS file. The prism.js download page will give you many options to customise the javascript and CSS files. The amount of choice can be overwhelming but there are only a couple options you need to change so it's not as complex as it may seem.

You can leave the compression level on 'Minified version' and core on 'Core' but you may like to change the theme. You can test how the different themes modify the appearance of the example code at the bottom of the page. Once you have selected your favourite theme, move on to the Languages section. The default selection (Markup + HTML + XML + SVG + MathML, CSS, C-like and JavaScript) should be sufficient. Lastly, we come to the plugins. We will discuss some of the most popular plugins shortly but for now, it's fine if you want to leave the section blank.

Now you have selected your preferences, you can download the JS and CSS files using the buttons at the bottom of the page. Store the downloads in the folder where your website files are kept and use the filenames 'prism.js' and 'prism.css', respectively.

To use prism.js on a webpage, you will need to import the CSS and JavaScript files into the head element of the HTML document. If the prism.css stylesheet is in the same folder as the HTML file then the import declaration will look like this: <link rel="stylesheet" type="text/css" href="prism.css">. On the other hand, if the stylesheet is in a parent folder relative to the HTML file then remember to include '../' before 'prism.css' in the href attribute. Next type the following line to utilise the prism.js file: <script src="prism.js"></script>. Similar to the stylesheet declaration, you may need to edit the src attribute to reflect the location of the prism.js file relative to the HTML file. Altogether, the head element of the HTML file should look like this:

<head>
	<!-- other content of the head element goes here -->
	<link rel="stylesheet" type="text/css" href="prism.css">
	<script src="prism.js"></script>
</head>

With the head element now set up, you are ready to add some example code to your webpage.

Adding example code to your webpage

The process for displaying example code using prism.js is very similar to highlight.js. Simply type your example code between the opening tags <pre><code class="language-css"> and closing tags </pre></code>. The 'language-css' class declaration ensures your example code will be processed by the prism.js JavaScript file. And remember, if your example code is not displaying properly then you may need to 'escape' some of the characters first to ensure it is read as text rather than code.

<pre><code class="language-css">
<!DOCTYPE html>
<html lang="en-GB">
<head>
	<title>Home</title>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" type="text/css" href="main.css">
</head>
<body>
	<h1>My nature and wildlife blog</h1>
	<img src="tree.jpg" alt="Tree" class="photo"/>
</body>
</html>
</code></pre>

And that's it! Providing you have imported your 'prism.css' and 'prism.js' files into the HTML file correctly then you should be able to successfully display example code on your website. The remainder of this tutorial will explore some of the plugins you can select when downloading your prism.js JavaScript and CSS files.

Line Numbers plugin

The Line Numbers plugin allows you to display line numbers with your example code. Line numbers are not included if a reader copy and pastes the code.

prism-line-numbers-plugin.png

To implement the Line Numbers plugin, first make sure it is selected when you download the source files. Line numbers can then be applied to your example code by adding the 'line-numbers' class to the opening 'pre' tag like this:

<pre class="line-numbers"><code class="language-css">
<!DOCTYPE html>
<html lang="en-GB">
<head>
	<title>Home</title>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" type="text/css" href="main.css">
</head>
<body>
	<h1>My nature and wildlife blog</h1>
	<img src="tree.jpg" alt="Tree" class="photo"/>
</body>
</html>
</code></pre>

Line Highlight plugin

The Line Highlight plugin is a good way of drawing attention to specific lines of your example code.

prism-highlight-plugin.png

To implement the Line Highlight plugin, first make sure it is selected when you download the source files. You can then highlight certain lines of code by adding the data-line attribute to the opening 'pre' tag. To highlight a single line of code, then set the data-line attribute to that line number only e.g. data-line="4". A range of lines can be highlighted as follows: data-line="2-6" and a combination of single lines and ranges can be highlighted like this: data-line="2, 5-10, 14".

<pre data-line="5, 11-12"><code class="language-css">
<!DOCTYPE html>
<html lang="en-GB">
<head>
	<title>Home</title>
	<meta charset="utf-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<link rel="stylesheet" type="text/css" href="main.css">
</head>
<body>
	<h1>My nature and wildlife blog</h1>
	<img src="tree.jpg" alt="Tree" class="photo"/>
</body>
</html>
</code></pre>

<<< Previous

Next >>>