Developer docs

A complete guide to code samples in Ghost

In this guide we’ll show how to add code samples to your Ghost site, and how to customise them with code syntax highlighting.

When writing technical content, most commonly engineering and development articles, example code needs to be shown to the reader. “Code blocks” are a way of presenting code in the same way it would look in a code editor, with indenting and a monospaced font.

<article class="post-item">
    <h2 class="post-title"><a href="/welcome/">Welcome to Ghost</a></h2>
    <p>Welcome, it's great to have you here...</p>
    <a class="read-more" href="/welcome/">Read more</a>
</article>

Syntax highlighting extends code blocks by adding colour and other styling to further emulate the presentation of a code editor.

<article class="post-item">
    <h2 class="post-title"><a href="/welcome/">Welcome to Ghost</a></h2>
    <p>Welcome, it's great to have you here...</p>
    <a class="read-more" href="/welcome/">Read more</a>
</article>

Example of code syntax highlighting in a code editor

Create a code block

Before we highlight our code we need some example code to highlight. To add a block of code to a post or page type three backticks () and hit enter. To set the language for the code block write it after the backticks. If I was writing JavaScript I would type "javascript" and hit enter. You can also use the language field in the top right corner of the code block:

Example of creating a code block in Ghost

The language field value will be set on the surrounding element of the code block so the syntax highlighter knows the language of the example code.

Add syntax highlighting

For highlighting your code we recommend using Prism.js, which is a lightweight JavaScript library especially for syntax highlighting. To add Prism.js to your Ghost site navigate to the Code Injection view in Ghost admin and use the cdnjs.com directory to copy the main prism.js script tag and style link tag.

Dropdown on cdnjs.com showing how to copy the CSS link tag

Dropdown on cdnjs.com showing how to copy the script tag

You can either copy the tags directly from cdnjs.com or copy the code below. As of writing this tutorial Prism.js is at version 1.19.0, please check you’re using the latest version.

<!-- link tag -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/themes/prism.min.css" />

<!-- script tag -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/prism.min.js"></script>

Paste the style link tag into the Site Header section, and the script tag into the Site Footer section:

Code Injection view in Ghost editor, with the CSS and script tags added to Site Header and Site Footer respectively

Adding the CSS tag to the header, and the script tag to the footer.

Click save and navigate to a post or page with a code block. You’ll see the code block is now using highlighted colours. 🎉

Example code block with syntax highlighting within a Ghost site

Customising Prism.js themes

Controlling the presentation of your code doesn’t stop there though. Just like the rest of your Ghost theme, code blocks are fully customisable with standard CSS and JavaScript.

The Prism.js library comes with an extensive list of alternate styles and plugins to further customise how your code samples look. In the following example the syntax highlighting has been changed to the Tomorrow Night theme.

Example code block with syntax highlighting with a dark theme added

To achieve the style shown above replace the standard CSS link tag with the following theme link tag:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/themes/prism-tomorrow.min.css" />

We can apply our own CSS and JavaScript too. The following design uses the Prism.js line numbers option with the assistance of some JavaScript and CSS to reduce the font size and background colour:

Example code block with syntax highlighting with a dark theme and minor styles added

To produce the design shown in the last screenshot add the following to the Site Header section:

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/themes/prism-tomorrow.min.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/plugins/line-numbers/prism-line-numbers.min.css" />
<style>
    pre[class*=language-] {
        margin: 1.75em 0;
        font-size: 1.4rem;
        background: #111;
    }
</style>

Add the following to the Site Footer section:

<script>
    window.addEventListener('DOMContentLoaded', (event) => {
        document.querySelectorAll('pre[class*=language-]').forEach(function (node) {
            node.classList.add('line-numbers');
        });
        Prism.highlightAll();
    });
</script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/prism.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/plugins/line-numbers/prism-line-numbers.min.js"></script>

Note that the inline JavaScript shown above is needed in order for Prism.js to know which code blocks require line numbers.

Add a copy to clipboard button

Adding a ‘copy to clipboard’ button can save your readers time when copying your code examples. This can also be added using Prism.js plugins.

Add the following to your Site Header and Site Footer code injection sections:

<!-- site header -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/themes/prism-tomorrow.min.css" />
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/plugins/toolbar/prism-toolbar.min.css" />
<!-- site footer -->
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/prism.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/plugins/toolbar/prism-toolbar.min.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.19.0/plugins/copy-to-clipboard/prism-copy-to-clipboard.min.js"></script>
Copy to clipboard button shown in the top right

Copy to clipboard button shown in the top right

Click save, navigate to an example code block and hover over the block itself. You’ll now see a “Copy” button in the top right of each code block on your site:

Further reading

We’ve discovered how to create code blocks in Ghost and add custom syntax highlighting to improve the reader experience of your technical content!

To take things a step further with Prism.js, check out an abundance of plugins, themes and optional languages for Prism.js in the official documentation. There’s even the option to create your own JavaScript bundle to keep your site dependencies small and maintain fast loading times. Your code samples don’t have to be just text though, check out how to add interactive code blocks in our integration guide for CodePen.