Highlight your code syntax with PrismJS

To improve the readability of code added to a post, we can use a syntax highlighter that highlights keywords, string values and numbers with different colors, much like a desktop code editor such as Sublime Text.

Handlebars template code with syntax highlighting on a dark background — Syntax highlighting uses different colors to distinguish parts of a code sample.

To implement this feature on a website, we can use Prism.js, a syntax highlighter built with JavaScript and CSS. You can add it manually by including its files on your website and identifying the language used in each code sample.

How to add Prism.js syntax highlighting to any website

To add Prism.js manually, download its JavaScript and CSS files, load them on your website and identify the language used in each code sample:

Go to the Prism.js project homepage and click Download. Select a color theme, the languages you want to highlight and any additional Prism plugins you want to use.
Download the generated prism.js and prism.css files.
Add both downloaded files to your website and reference them in its HTML. In the example below, prism.css is in the css folder and prism.js is in the scripts folder. Adjust the paths to match where you placed the files:
```
<!DOCTYPE html>
<html>
<head>
    <link href="css/prism.css" rel="stylesheet">
</head>
<body>

    <script src="scripts/prism.js"></script>
</body>
</html>
```
To highlight a code block, wrap it in <pre> and <code> tags, then add a language class to <pre> in the format language-xxxx. The language must be included in the Prism.js file you downloaded.
For example, use language-css for CSS or language-php for PHP. You can find the available language identifiers here: https://prismjs.com/#languages-list.
```
<pre class="language-css"><code>::placeholder {
    color: var(--placeholder);
    opacity: 1;
}
</code></pre>
```
If you enter code directly in HTML, escape characters such as < and & as < and &. This allows the browser to display them as code instead of interpreting them as HTML.

Info: You can see Prism.js highlighting in the code examples on this page, which uses the ProDocs theme and was created with Publii.

How to modify an existing Prism.js installation

If your website already uses Prism.js, it may have custom CSS styles or load additional Prism plugins separately. Check the existing files before replacing anything, so you can preserve its appearance and features.

Two optional Prism plugins are Line Numbers and Copy to Clipboard. The first numbers the lines in a code block, and the second allows readers to copy the code to the clipboard. You can include these plugins when preparing your download on the Prism.js website.

When using the Line Numbers plugin, add the line-numbers class to the <pre> element alongside the language class:

<pre class="language-css line-numbers"><code>::placeholder {
    color: var(--placeholder);
    opacity: 1;
}
</code></pre>

How to add more languages

After implementing Prism.js, you may decide to add support for more languages. To add languages to a manual installation, follow these steps:

Go to the Prism project homepage (https://prismjs.com/), then open the download page. Select all the languages you want to keep, along with the new ones you want to add, and download the JavaScript file.
If your website loads Prism plugins as separate files, leave those plugins out of the new download. If they are bundled into the existing prism.js file, include them again.
Remember: When you are only adding languages, keep your existing CSS files so the appearance of your code blocks stays the same.
Replace your website’s existing prism.js file with the new download. For the setup described above, the location is scripts/prism.js.
Add the appropriate language class to your code sample, following step 4 above.
Open the page in your browser and check that the new language is highlighted correctly.

Using Prism.js in Publii

In Publii, syntax highlighting is provided by the Syntax Highlighter plugin. It adds Prism.js to your website without requiring you to edit theme files. This applies to ProDocs and other Publii themes.

The plugin loads the required JavaScript and CSS files for you, so you do not need to follow the manual installation steps above. It includes six color themes and options for line numbers, a Copy to Clipboard button, inline color previews, automatic links and hidden characters.

Installing and enabling the plugin

Download the plugin, then open Publii’s three-dot app menu and select Plugins. Click Install plugin and select the downloaded ZIP file.
Open your website and select Plugins in the left sidebar. Enable Syntax Highlighter, then click its name to open its settings.
Choose a color theme and the display options you want to use. Use Load on to select where the plugin should load, then click Save settings.

The Load on setting offers Posts, Pages, Posts and Pages and All pages. The All pages option excludes the 404 and search pages. Choose an option that includes the pages where you want to display code.

You can find more information in the Syntax Highlighter plugin documentation.

Adding code in the WYSIWYG editor

To save time, use the WYSIWYG editor’s Insert/edit code sample button. In the dialog that opens, select the Language, type or paste your code into Code view and click Save. Publii adds the markup for you.

Insert/Edit Code Sample dialog with the Language dropdown open and Plain text selected — Choose the language for your code in the Insert/Edit Code Sample dialog.

Paste the code itself into the dialog; you do not need to add <pre> or <code> tags. To change an existing sample, select it and click Insert/edit code sample again.

Choose Plain text if you want to display a code block without language-specific highlighting.

Adding code in the Block editor

Add a Code block and type or paste your code into it. With the block selected, choose the appropriate Language from its toolbar. The language list is searchable, so you can type a language name to find it.

As with the WYSIWYG editor, Publii creates the required markup for you. Choose Plain text when you do not need syntax highlighting.

Adding code in the Markdown editor

In the Markdown editor, place your code between two lines containing three backticks. Add the language identifier immediately after the opening backticks. For example, a CSS sample looks like this:

```css
::placeholder {
    color: var(--placeholder);
    opacity: 1;
}
```

Use the identifier that matches your code, such as javascript, php or python. The selected language must be supported by the Syntax Highlighter plugin.

Note: Highlighting inside the editor is separate from highlighting on your website. Enable the plugin for the current website and check the result in the website preview.

Once your code samples look correct in the preview, sync your website to publish the changes.