Many of my blog posts show codes examples. In the past, I’ve used a WordPress plugin to create syntax highlighting to make the code examples easier to read. The problem with the WordPress syntax highlighting plugins is that they load a lot of css and java scripts and wreck your site’s speed scores. As an alternative, I started using Github Gists to show code examples. But I didn’t like the default Gist syntax highlighting. I needed Github Gists custom syntax highlighting. It took me a while to figure out so I’ll save you some time if you want to do it.
What is a Gist?
A Gist is a block of code that is stored on github servers. Once you create a Gist, you can insert that Gist into a web page using an embed script. It’s a simple, lightweight solution to include syntax highlighted blocks of code on your web pages. Another advantage of using Gists is that if you need to change the code in the Gist, you update the Gist and it automatically updates wherever you use that Gist.
Create a Github Account
If you don’t already have one, create a free Github account. This will allow you to create your own Gists.
- Go to https://github.com/
- Click Sign Up.
- Enter a username, email, and password and select the free account.
- You will receive a verification email. Click the verification link.
- Once your account is verified, log into http://github.com.
Create and Embed a Gist
In order to test the custom syntax highlighting I provide below, you’ll need a post or page with a Gist embedded in it.
- Go to https://gist.github.com/ and login.
- Click New Gist.
- Optional: Enter a Gist description
- Enter a file name including the extension. For example, my_new_gist.php. This is VERY important. The file name and extension determine how the Gist is highlighted.
Also, if your file is a .php file, make sure you include the opening php tag: <?php
See the example below.
- Enter your code and then click Create public gist.
- Click the embed Gist link and then click Copy to clipboard icon.
- In a WordPress post or page, click the Text tab on the editor, and paste the Gist where you want it to appear.
- Click Update to save the change.
- Load the page and you should see the Gist on the page. The image below shows the standard syntax highlighting for Gists. We will change that formatting in the next section.
Create a Github Gists Custom Syntax Highlighting
At this point, you should have a page with an embedded gist with the standard Gist syntax highlighting.
The .css code below will change that to a dark background with syntax highlighting that make the code easier to read.
- Copy the css code below and paste it into your WordPress theme’s style.css file.
- Save and upload the style.css file.
- Reload the page with Gist embedded in it. It should now display the new syntax highlighting.
- You can modify any of the syntax highlighting colors in the css.
SASS Version of the Same Syntax Highlighting Theme
The following is a SCSS version of the same syntax highlighting theme.
Additional Gists Syntax Highlighting Themes
There are several other free Gist syntax highlighting themes in case you don’t like the colors of the one I used.