How I created branded syntax highlighting for my WordPress blog

By Matt Visiwig Sep 1, 2021

Quickly, let me demo the branded CODE blocks I made:

<!-- This is how HTML markup looks -->
<div id="welcome-msg">
   <p>Hello World</p>
</div>

TL:DR; Skip to the solution heading

Finding a WordPress solution

I started doing research on how to add syntax highlighting to my WP blog tutorials, it was a bit more complex than I first realized.

There are many libraries to handle prettifying code on webpages and there are limitations to how you write code into the WordPress editor.

I needed an easy way to:

• input code snippets
• display code with highlighting

Chris Coyier wrote an older post about how you’ll need to disable the visual text editor on WordPress if you’re going to write code on your blog posts often. But after trying that out, I realized I wanted to see everything styled, from headers to images as I wrote and revised my content. I wanted an enjoyable blogging experience.

I nearly ruled out Gutenberg blocks as I have avoided the new editor since its launch. Despite testing Gutenberg out on three separate occasions, I’ve always reached for the classic editor plugin. But this time was different. I was actually going to be blogging and not simply creating page content. Gutenberg began to look more attractive, so I tried it for a fourth time.

Gutenberg had definitely been fleshed out since I last tried it. It was a generally smooth experience. When I first tried the CODE block, the results weren’t optimal and I had some weird results. I thought it was a dead end and that I would have to create a custom solution. At the same time, I didn’t want to waste a lot of time on this non-critical task. I ruled out creating a custom solution.

I tried making Gutenberg CODE blocks work and I ended up finding a few tools that made this work reasonably well.

The solution

The setup is straightforward: 

• Gutenberg default code blocks to input code into blog posts.
• PrismJS + a theme editor to style the code on the webpage.
• Optional: custom CSS

Getting the editor for code input

The great thing about this setup is there is no special WordPress addon needed. As long as you have Gutenberg, the default editor, you are ready to proceed. The classic editor plugin disables Gutenberg, so you will have to disable that plugin before moving on.

Getting PrismJS

To get PrismJS to work, you’ll need to link to both a JS file and CSS file. Head over to the PrismJS website and click download. You’ll be presented with an overwhelming screen of options. Here is what you want:

1. Compression level:
   Keep “Minified Version” unless you KNOW you want the dev version
2. Themes:
   Theme is not important as we’ll be creating our own
3. Languages:
   Check the boxes for the coding languages you will share on your blog
4. Download:
   Click the giant “Download JS” button. We’ll use this file in a few steps.

Create your syntax highlight theme

The thing that sold me on PrismJS was the ability to create my own theme and colorize the code how I wanted. Even better, you can use this syntax highlighting theme builder (http://k88hudson.github.io/syntax-highlighting-theme-generator/www/) to create it visually and quickly. After you play around and select your desired color highlighting, click the “Download CSS” button in the bottom right corner. We’ll use this downloaded file in the next step.

Upload your JS and CSS files

In the last two steps you downloaded a JS file from PrismJS and a CSS file from the theme builder. Now we need to host these files to make use of them. I’m not going to go into detail about how to upload your files, but will note, an easy way is using an FTP client like Filezilla. You’ll likely want to keep these files with your theme. This may mean creating a child-theme, or if you built your own WP theme like me, adding the files to a /js/ and /css/ directory within your theme structure is ideal. Alternatively, the easiest spot to place your files is in the root of your website, but keep in mind this isn’t a good practice.

Link to your JS and CSS files

Now that we are hosting the files, we need to include these files on the front-end of your website. You need to know the path (location to your file) and file names.

<link href="/path/to/your/file/prism-theme.css" type="text/css" rel="stylesheet">
<script src="/path/to/your/file/prism.js" type="text/javascript"></script>

You’re going to want to place this in the <head> or <body> of your webpages. If you’re not working with PHP template files or don’t have the general know-how, a popular way to add these tags is to use an insert header and footer plugin. 

Test out the Syntax Highlighter

If you successfully followed these previous steps, our code blocks should be ready to work.

Let’s test it out!

1. Create a new post in your WP backend
2. Select and add a code block
3. Enter your code into the code block
4. Add the special language class (required)
   You’ll find the “additional CSS class(es)” field in the block settings within the “Advanced tab”. PrismJS only works if it knows what language of your code snippet. In my case, I’d enter language-markup for HTML code and language-css for CSS code. You can find your specific class alias in the PrismJS docs (https://prismjs.com/#supported-languages).
5. Click preview to check out the output

Fingers crossed! That should work.

Troubleshooting

Unfortunately sometimes things go wrong. It took me a few tries. Here are a few things I would check to figure out what is preventing your syntax highlighter from working.

1. Is the code block displaying on your blog post?
   • If not, perhaps publish the post, as the preview may not work 100% of the time.
2. Is the HTML output correct
   • View the source code. I use Chrome’s inspector to make this easier. I right click the element I want to view and select “inspect”, and it brings me directly to the relevant code. You should expect to see your code within a <pre> that wraps a <code>.
   • Both tags should have the class that you specified, such as language-js. If not, this is a sign that there is a typo or that the PrismJS files are not loading.
   • If the class alias is correct, make sure your code reflects the language you specified. For instance, CSS won’t work as expected in language-markup, unless wrapped within <style> tags.
3.  Are the PrismJS files loading?
   • Again, break out the source code and make sure you see the links to your files.
   • Check to ensure the browser is locating the files on your server. You can do this by visiting the URL in the src="" and href="" of those JS and CSS file links. If they don’t lead to code, the path is wrong or the files don’t exist on your server.

Add optional formatting and styling

The theme builder UI made colorizing the syntax a cinch, but if you want to take this to the next level, you can also format the code even more using CSS. I did things like make sure my font-size and padding system for the blog content worked alongside the new code block.

Your WordPress blog how has a branded syntax highlighter

Now that you’re set up, you’re good to go. There’s not much to it, just remember to add the class each time you use the code block, or the PrismJS file won’t target and style your code snippet.

Here is a before and after:

<!-- without style -->
<p>A paragraph</p>

<!-- with custom style -->
<p>A paragraph</p>

Down the road, if you find you need support for other languages, you can hop back to the PrismJS website to download the new languages.

Let me know how it goes! Share your results with me on Twitter @MattVisiwig