Code Markup is a WordPress plugin that makes it easy to include program code samples in your posts. You can even include HTML markup in the code sample; Code Markup magically knows which characters should be displayed as code and which should be rendered as HTML. For example, with Code Markup you can write:
<pre>
<code>
for (int i = 0; i < top; ++i) {
vector<int> <span style="color:red">judy</span> = mary();
</code>
</pre>
And have it displayed as
for (int i = 0; i < top; ++i) {
vector<int> judy = mary();
with “judy” in red, just as you would expect. The <span> tag is rendered as normal HTML , but the <int> and i < top are displayed exactly as typed. This is very useful for times when you want to highlight a particular piece of code in your listing.
Code Markup also prevents WordPress from removing backslashes, turning your quotes into curly quotes, rendering decrements (--) into dashes (–), and so on.
Compatibility
Code Markup has been tested successfully with WordPress versions from 1.5 to 2.1, and should also work with newer versions as they are released.
In WordPress 2 and above, you’re better off disabling the visual editor in order to have finer control over your post formatting. To do this, go to the administration interface. Select Users, then Your Profile. The checkbox is at the top of the screen.
If you do decide to use the WordPress 2 visual editor, Code Markup works with the following limitations:
- leading whitespace is trimmed within <pre> elements (this is an editor bug)
- line breaks are mangled within <pre> elements (this is an editor bug)
- after you have saved the post, the code does not display correctly (even in HTML view)
- because the display is wrong, you can’t edit code after it has been saved.
Installation
- Download the code-markup.php file (see the end of this article for download location)
- Copy code-markup.php into your WordPress plugins directory (wp-content/plugins).
- Log in to WordPress Admin. Go to the Plugins page and click Activate for Code Markup.
- (Optional but recommended) Go to the Options page and click Writing. Make sure “WordPress should correct invalidly nested XHTML automatically” is not checked. (Otherwise it may do funny things to your code listings.)
How to use
The plugin works by escaping most special HTML tags and characters so they display exactly as typed, but allowing certain tags to be rendered as normal HTML. The default set of allowed tags is the standard formatting tags like em, strong, span and so on. You can control this explicitly, or implicitly by specifying the language of the code block. For example, in a normal code block, <em> will be rendered as emphasised text, but in an HTML code block, <em> will be displayed as <em>.
Here’s how to format your code for Code Markup.
- Enclose all code inside a
<code> block.
- Include any HTML markup you like in the code, for example to add emphasis to certain sections.
- Separate
<code> blocks should be nested within a <pre> block to preserve whitespace.
If you want to fine-tune how Code Markup treats your code, use the markup and lang attributes on the code tag to specify how Code Markup should handle it.
<code> or <code markup=”default”> allows common HTML tags to be rendered, and displays everything else exactly as written.<code markup=”none”> displays content exactly as written — no markup is rendered.<code markup=”all”> renders content as HTML — all markup is rendered.<code markup=”em strong a”> treats <em>, <strong> and <a> tags as HTML markup — everything else is displayed exactly as written. You can put whatever tags you like in the markup attribute, separated by spaces. As a special case, you can include the comment tag — this means that HTML comments <!-- like this --> will be “rendered” as normal HTML comments (i.e. not displayed).<code lang=”html”> or
<code lang=”xhtml”> displays content exactly as written, the same as <code markup=”none”>.
The markup attribute overrides the lang attribute.
Examples
Example: Test strings using <code><b>aString</b> < "foo"</code>.
Display: Test strings using aString < “foo”.
Example:
<pre>
<code lang="xhtml">
<p> <!-- paragraph -->
<b>What's going on?</b>
</p>
</code>
</pre>
Display:
<p> <!-- paragraph -->
<b>What's going on?</b>
</p>
Example:
<pre>
<code>
<p> <!-- paragraph -->
<b>What's going on?</b>
</p>
</code>
</pre>
Display:
<p>
What’s going on?
</p>
Example:
<pre>
<code>
for (int i=0; i<5; ++i) {
<span style="color:red">cout</span> << "smap!" << endl;
}
</code>
</pre>
Display:
for (int i=0; i<5; ++i) {
cout << "smap!" << endl;
}
Example:
<pre>
<code markup="span">
<a href="<span style="color:green">target-url</span>">Link text</a>
</code>
</pre>
Display:
<a href="target-url">Link text</a>
Bugs
If you want to display the text </code>, <!--more--> or <!--page--> in your code, you have to put them in a <code markup="all"></code> block. If you don’t they will be rendered as HTML, which is not what you want, believe me.
If you find any other problems, please let me know by leaving a comment at the bottom of this page.
Frequently Asked Questions
What is this good for?
The plugin allows you to quickly copy and paste code into your blog, and add HTML markup to it to emphasise certain parts of it. Normally this is not possible without a lot of fiddly manual editing.
What tags are allowed by default?
If the code block has its lang attribute set to html or xhtml, then no markup are allowed: all tags are escaped and will display as typed. Otherwise the following tags are allowed: em strong b i ins del a span as well as <!--comments-->
How do I change the default behaviour?
- To make the code block render as straight HTML, use
<code markup="all">. In this case, make sure that you have typed correct HTML!
- To make the code block display exactly as typed, use
<code markup="none">.
- To specify which HTML tags should be rendered as HTML, include them in the
markup attribute. For example, <code markup="strong em comment">.
Alternatives
There are a few other plugins that do somewhat similar things. Code Markup is simple and useful, but if you feel it’s not quite right for you, you could try looking at these other plugins.
- Preserve Code Formatting has a slightly more robust untexturizer (it correctly handles a triple dash, for example), but doesn’t allow any markup at all in code blocks.
- Code Viewer displays code from an external file, so it’s not so good for tiny code snippets. However, it does allow readers to download the code, and it also adds line numbers. But again, no manual markup allowed.
- Unfancy quote plugin uses the sledgehammer technique to avoid WordPress’s fancification of text: it disables it completely.
There are also a number of syntax highlighting plugins. These make your code look nice, but don’t allow you any manual control of markup. They’re also pretty heavyweight, and some are slightly fiddly to install. But if you want syntax highlighting, try them out.
Please leave a comment if you know of other similar plugins.
Download
You can download code-markup.php or view the source code.
