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 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 web pages. 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@11.3.1/build/styles/default.min.css">
<script src="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.3.1/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 Base 16 / Atelier Estuary theme then replace default.min.css with base16/atelier-estuary.min.css. After making this change, 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@11.3.1/build/styles/base16/atelier-estuary.min.css">
<script src="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.3.1/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@11.3.1/build/styles/default.min.css">
<script src="//cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.3.1/build/highlight.min.js"></script>
<script>hljs.initHighlightingOnLoad();</script>
</head>Adding example code to your webpage
Once your web page is equipped to use highlight.js, you can add the example code that you wish to show 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 text 'language-' followed by 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="language-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.
'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, " 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
Using prism.js on your webpage
An alternative syntax highlighter to highlight.js is prism.js. Prism.js has fewer available themes than highlight.js; however, it does offer lots of useful plugins to help make your example code interactive. 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 of 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, CSS, C-like and JavaScript) should be sufficient; however, feel free to tick more languages from the list if you see others that you wish to display. 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.
Once 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 <pre><code class="language-YOUR-LANGUAGE-HERE"> and closing </pre></code> tags. Replace the YOUR-LANGUAGE-HERE part of the class assigned to the opening code tag with the name of the language you wish to display. For a full list of languages supported by Prism then click here. Note you should also have selected the code language you are displaying in your preferences when downloading the Prism JavaScript and CSS files. 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-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>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 copies and pastes the code.
To implement the Line Numbers plugin, ensure 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-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>Line Highlight plugin
The Line Highlight plugin is a good way of drawing attention to specific lines of your example code.
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-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>Copy to Clipboard Button plugin
Prism.js offers a Copy to Clipboard button plugin that adds a button to your example code and allows users to copy the displayed code with a single click.
If you selected the Copy to Clipboard button plugin when downloading the prism.js file, then it will automatically apply to all code that you display. There is nothing more you need to do. However, you can customise the button. For example, the button has three states:
- data-prismjs-copy - The default resting state.
- data-prismjs-copy-error - The button has been clicked but failed to copy the text to the user's clipboard.
- data-prismjs-copy-success - The button has been clicked and successfully copied the text to the clipboard.
You can alter the message that the button displays in each state by referencing the relevant property in the opening code tag. For example, we could create a copy button that displays the text "Copy me" in its resting state and "I've been copied!" in its success state by writing the following code:
<pre><code class="language-html"
data-prismjs-copy="Сopy me"
data-prismjs-copy-success="I've been copied!" >
<!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>You can also style the copy button. To do this, simply modify the copy-to-clipboard-button class in your main.css stylesheet. For example, you could change the user's cursor to a pointer symbol rather than an arrow when the button is hovered over by writing the following CSS code:
.copy-to-clipboard-button:hover {
cursor: pointer;
}