For an upcoming blog series on learning React, I wanted to have a way to share the code I was writing, including syntax highlighting.
Note: I’m using the “Text” editing view for posts on a self-hosted WordPress instance.
The Naive Solution:
WordPress has built-in
<code> tags, but they’re a pain to use with an HTML snippet since reserved characters need to be escaped manually. Meaning: every
> needs to be entered in the post editor as
> instead. You must make this change to prevent what’s written inside the
<code> tags from being evaluated! It’s quite cumbersome to make these changes manually when editing the post text by hand, and updating existing code is near-impossible without using a separate encoder-decoder. Not a very useful implementation of
<code> tags, IMO.
Another Built-in WordPress Option
WordPress also has “shortcodes” that add functionality through plugins. These shortcodes are similar to html tags but use square brackets () instead of angle brackets (<>). The shortcode suggested for code is the
[x_code] tag, which makes something like
<div id="component">Hello!</div> look like
It’s not as compact as the built-in (inline)
<code> tags, but it’s better for multiple lines of code that need to be separated from the rest of the text. Better yet,
[x_code] tags allow reserved characters to be left alone (and not converted to
&lt;). But there’s still no syntax highlighting.
With the two above code tags already built in, I can include short bits of inline and multiline code. Unfortunately these options both let me down in the end, since for inline code I must escape all special characters, and for both there’s no syntax highlighting. I really want something that lets me copy code from source files and then paste it into the post without escaping “special” characters or monkey-ing with it much at all.
A Sidenote about Self-Hosting:
The following solutions mentioned on How to Insert Code Into WordPress @ StackOverflow did not work out of the box:
This is because our WP site is self-hosted and not run by wordpress.com.
SyntaxHighlighter Evolved Plugin for WordPress
[code] tags with this plugin, then get syntax highlighting by specifying the language with a
language="html" attribute or by using an alias like
[html] instead of
[code]. With this plugin, there is no need for manual encoding of reserved characters – and it includes nice features like line numbering and highlighting. For example:
<div id="component"> Hello! </div>
The above was made using
[html highlight="2"] and
I’ve found this plugin to work well with code snippets that have been separated into one language per snippet. Multiple languages should be supported in one snippet with the
Finding a Solution for ReactJS
The overall operation and look of a React app comes from (at least) HTML, JS, and CSS – each of which usually live in separate files. The above options can be great for showing a single code snippet in one language, but there’s no built-in WordPress way to link snippets of different languages together with a “live preview” or “results” showing how they work together.
For each of these services, once the code snippet has been added on the site, it can then be embedded into a WordPress blog post by pasting in one or two HTML tags. Here are examples of each service’s embed result:
JSfiddle embed code:
<script async src="//jsfiddle.net/cobyhausrath/8ao742vL/3/embed/html,css,js,result/"></script>
JS Bin on jsbin.com
(it’s okay if you don’t see anything above)
JSbin embed code:
<a class="jsbin-embed" href="http://jsbin.com/hawipof/embed?html,css,js,output&height=150px">JS Bin on jsbin.com</a><script src="https://static.jsbin.com/js/embed.min.js?3.41.10"></script>
CodePen embed code:
<p data-height="173" data-theme-id="light" data-slug-hash="rmmgMe" data-default-tab="html,result" data-user="cobyhausrath" data-embed-version="2" data-pen-title="rmmgMe" class="codepen">See the Pen <a href="https://codepen.io/cobyhausrath/pen/rmmgMe/">rmmgMe</a> by Coby Hausrath (<a href="http://codepen.io/cobyhausrath">@cobyhausrath</a>) on <a href="http://codepen.io">CodePen</a>.</p> <script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>
Comparing the Options
JSfiddle, JSbin, and CodePen each highlight syntax and combine HTML, CSS, and JS with the resulting output. Unfortunately JSbin requires a Pro account to embed a snippet on an HTTPS site – and since this site is an HTTPS site, loading the snippet via HTTP is blocked by the browser. For the two examples that *do* load above, they are fairly compact and it’s easy to see that all three inputs (JS, CSS, and HTML) help make up the result.
Taking JSbin out of the running, that leaves JSfiddle and CodePen. Of the two, I like that CodePen has the results always displayed at the right of the code. I also like that CodePen lets you “embed” scripts within the configuration of the JS code – so there’s no need to add
<script> tags at the top of the HTML. This works great to keep examples short and to the point when scripts like React and React-DOM may be used in every snippet.
Even though JSfiddle is completely free (well, ad-supported), I’m leaning towards selecting CodePen as the embedded-source-code-and-example tool for future blog posts because its free version has more features than does JSfiddle. We might go with a paid plan, but I don’t see any immediate reason to do so: the good news is if we did upgrade, there wouldn’t be any loss of functionality down the road if we let the pro-level subscription lapse. Whereas if we paid JSbin to enable HTTPS embeds, dropping that subscription later on would force us to redo those snips with another provider only for the sake of keeping the snips we’ve already embedded working.
Most of all, I don’t want anyone to ever have to use the Wayback Machine to see the full content of the blog.
What have you used for code snippets on WordPress?