{"id":163047,"date":"2015-11-05T08:00:18","date_gmt":"2015-11-05T15:00:18","guid":{"rendered":"http:\/\/css-tricks.com\/?p=163047"},"modified":"2015-11-06T08:25:19","modified_gmt":"2015-11-06T15:25:19","slug":"posting-code-blocks-wordpress-site","status":"publish","type":"post","link":"https:\/\/css-tricks.com\/posting-code-blocks-wordpress-site\/","title":{"rendered":"Posting Code Blocks on a WordPress Site"},"content":{"rendered":"

Originally published in February 2014, now updated\/corrected\/expanded.<\/em><\/p>\n

So you’ve installed WordPress and want to blog about code. Yay! You’re a hero and I thank on behalf of myself an coders everywhere. Here’s what you’ll need to do and think about to actually get publishing blocks of code.<\/p>\n

<\/p>\n

The HTML for a “code block”<\/h3>\n

There is an element specifically for code: <code><\/code>. I’d say it’s semantically correct to wrap any and all code in it. Browser’s default stylesheets leave it as inline element, and I’d recommend you leave it that way so you can use it within sentences like I did in the last sentence. <\/p>\n

But you’ll want to use a block-level element to wrap a block of code. <pre><\/code> is the perfect element for that, as it naturally retains whitespace. “Pre” as in “Preformatted text”. Multiple spaces will render as multiple spaces instead of collapsing into a single space as normally happens in HTML. That’s perfect for code, because you’ll likely want to use indentation in a block of code and you don’t want to resort to any &nbsp;<\/code> shenanigans.<\/p>\n

So:<\/p>\n

<pre><code>Your \r\n   \r\n   block\r\n  \r\n       of\r\n\r\n   code\r\n \r\n here.<\/\u200bcode><\/\u200bpre><\/code><\/pre>\n
Turn off the “Visual” editor<\/h3>\n
By default, WordPress lets you switch between Visual and Text tabs in the editor. <\/p>\n
<\/figure>\n
For you, the Visual editor has to go. You will never use it. You want full control of the text you are writing and want it to stay just how you write it when you save it. <\/p>\n
Turn it off under Users > Your Profile<\/strong> <\/p>\n
<\/figure>\n
Are you going to blog in Markdown or not?<\/h3>\n
Here on CSS-Tricks I do not, but if I could go back in time to the beginning I probably would. On most subsequent blogs I’ve done, I do use Markdown and prefer it. If you are going to, I’d suggest using Jetpack’s Markdown feature<\/a>.<\/p>\n
To post a block of code in Markdown, one ways is to indent that code four spaces on every single line, like this:<\/p>\n
Yadda yadda yadda. I'm a *paragraph* in Markdown. Here's a [link to Google](http:\/\/google.com). Here's a block of code:\r\n\r\n    <div>\r\n       <p>I'm some code.<\/p>\r\n    <div>\r\n\r\nAnother paragraph here.<\/code><\/pre>\n
Manually doing that is going to get old very fast. So you’ll want to replace your editor buttons with Markdown buttons. It looks like the plugin Markdown Quicktags<\/a> can do that.<\/p>\n
<\/figure>\n
What’s cool about using Markdown is that you don’t have to worry about escaping the code. So those angle brackets are no rendering threat, Markdown will escape them for you. In other words, all those angle brackets (<<\/code>) in the HTML example above will be turned into &lt;<\/code> and thus display on the screen as an angle bracket rather than confuse the browser into thinking an HTML tag is coming up.<\/p>\n
That Markdown example above will be turned into this before it hits the browser:<\/p>\n
<p>Yadda yadda yadda. I'm a <em>paragraph<\/em> in Markdown. Here's a <a href="http:\/\/google.com">link to Google<\/a>. Here's a block of code:<\/p>\r\n\r\n<pre><code>&lt;div&gt;\r\n   &lt;p&gt;I'm some code.&lt;\/p&gt;\r\n&lt;div&gt;<\/code><\/pre>\r\n\r\n<p>Another paragraph here.<\/p><\/pre>\n
If you’re interested in blogging in Markdown, you have some options. Jetpack<\/a>, the Automattic-created and maintained plugin, now offers it<\/a> as part of it’s mega-pack of offerings. At the time being I use WP-Markdown<\/a> here on CSS-Tricks (I know I said I don’t use Markdown, but I do for the Forums and comments, just not blogging). <\/p>\n
Two I haven’t personally tried are Typewriter<\/a> and Markdown on Saved Improved<\/a>. <\/p>\n
There is a fairly major limitation here though. Notice that the four-spacing indentation converts into a <pre><code><\/code> block, but there was no opportunity there to add attributes to those tags. Attributes (like classes and data-* attributes) are a common need. You might want to use a syntax highlighter (we’ll talk about those later) that requires some attributes to do it’s thing. Or you might want to identify the code block somehow by language. <\/p>\n
More convenient than indenting, many “flavors” of Markdown (including the Jetpack version) support code fencing<\/em>, which is putting blocks of code within triple backticks:<\/p>\n
```\r\n<div>\r\n  <p>I'm some code.<\/p>\r\n<div>\r\n```<\/code><\/pre>\n
I’d call this straight up better. It’s easier to jump into a code block while writing without having to worry about the indentation thing. Plus code has it’s own indentation going on so it’s nice to start flush-left with that. <\/p>\n
You can also specify the language right in the Markdown syntax. So our example could be:<\/p>\n
```html\r\n<div>\r\n  <p>I'm some code.<\/p>\r\n<div>\r\n```<\/code><\/pre>\n
Which gives:<\/p>\n
<pre><code class="html">&lt;div&gt;\r\n  &lt;p&gt;I'm some code.&lt;\/p&gt;\r\n&lt;div&gt;\r\n<\/code><\/pre><\/pre>\n
If you DON’T use Markdown, you’ll need to escape the code.<\/h3>\n
Blocks of CSS code rarely need escaping, but HTML for sure does, and JavaScript sometimes has HTML in it (as well as just about all backend languages), so you might as well just assume you need to escape all code. <\/p>\n
You could do it manually by converting all <‘s into &lt;’s, but you’ll go nutty doing that. You could use a tool like Postable<\/a> to copy-and-paste blocks to be escaped, but that’s slow and tedious too. <\/p>\n
I prefer using a plugin called Code Markup<\/a> for this. It just auto-escapes anything it finds within <code><\/code><\/code> tags so you just never have to think about it.<\/p>\n
Because I use that plugin on this site, I can do stuff like:<\/p>\n
<pre data-lang=\"HTML\"><code class=\"language-markup\"><div>\r\n  <p>I'm some code.<\/p>\r\n<div><\/\u200bcode><\/\u200bpre><\/code><\/pre>\n
And it works great. No escaping. Full attribute control.<\/p>\n
Handling Syntax Highlighting<\/h3>\n
Remember that one option for syntax highlighting blocks of code is not<\/em> syntax highlighting. Certainly that would be the fastest and easiest way. But you might want it. Personally I like it. I like the way it looks. Here’s a few options.<\/p>\n
What essentially happens with any syntax highlighter is bits of code end up getting wrapped in <span><\/code>s with class names that you colorize with CSS. Choosing is a matter of features.<\/p>\n
Prism.js<\/h4>\n
Here on CSS-Tricks, I use (and recommend) Prism<\/a> by Lea Verou as it works with those right out of the box. It’s small, fast, and (my favorite) as rational class names for styling. You choose which languages you want it to support as you download it.<\/p>\n
I also use that escaping plugin, meaning I don’t need to escape HTML inside code tags, so again that looks like this:<\/p>\n
<pre><code markup=\"tt\" class=\"language-markup\"><div>\r\n  <p>I'm some code.<\/p>\r\n<div><\/\u200bcode><\/\u200bpre><\/code><\/pre>\n
That class=\"language-markup\"<\/code> on the code tag is what Prism picks up on to syntax highlight. It works automatically on all code it finds with that class name pattern by default, but you can use the API<\/a> instead if you want to do your own thing.<\/p>\n
Prettify<\/h4>\n
An extremely popular one is google-code-prettify<\/a>. To syntax highlight a block, you put class=\"prettyprint\"<\/code> on either the code or pre tag. <\/p>\n
It’s a larger file size than Prism, but one advantage is that it auto-detects language (and supports a ton of languages), so it should work on just about anything without you having to specify it.<\/p>\n
Others<\/h4>\n
Digging around a little, there are plenty more that I can’t vouch for but seem like they’ll do the trick: Rainbow<\/a>, SyntaxHighlighter<\/a>, Chili<\/a> (jQuery), JSHighlighter<\/a>, jQuery.Syntax<\/a> (jQuery), GeSHi<\/a>, Lighter<\/a> (MooTools), highlight.js<\/a>, SHJS<\/a>, and Pygments<\/a> (Python).<\/p>\n
Deciding<\/h4>\n
To decide amongst these, you might think about these things:<\/p>\n