Code Markup: a WordPress plugin

Sunday, 29 May 2005

Latest version is 1.3, released on 1 March 2008.

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.5.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

  1. Download the code-markup.php file (see the end of this article for download location)
  2. Copy code-markup.php into your WordPress plugins directory (wp-content/plugins).
  3. Log in to WordPress Admin. Go to the Plugins page and click Activate for Code Markup.
  4. (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. The files are hosted externally — if there’s a problem with them you can download a recent version hosted on this site. Don’t forget to check out all the other plugins available here — there’s bound to be one that you will find useful.

I write these WordPress plugins because I enjoy doing it, but it does take up a lot of my time. If you think this plugin is useful, please consider donating some appropriate amount.

Click here to donate using a credit card or PayPal.

Send Bitcoins to address
1542gqyprvQd7gwvtZZ4x25cPeGWVKg45x

Full WordPress plugin list

  • Code Markup — Quickly paste code samples into your posts -- you can even include HTML markup in the code sample.
  • Evermore — Automatically display a short preview of your posts on the home page and other multiple-post pages, along with a link to the full post.
  • FixBack — Ensure trackbacks and pingbacks are sent with the correct link back to your blog.
  • Less — Less is no more. It has been renamed to Seemore and moved to its own Seemore plugin page.
  • Plaintext — Allow your readers to download source files (e.g. PHP, HTML, ASP) as plain text.
  • Safe Title — Use HTML in post titles in the default WordPress theme (or any other theme).
  • Search Meter — Find out what people are searching for on your blog, so you can write what your visitors want to read.
  • Seemore — Change the (more...) link so it jumps to the full post, not just the part after the link.
  • Top Cat — Specify a main category for your posts, and use template tags to display posts differently according to their main category.

720 comments

You can leave a comment, or trackback from your own site.

  1. It’s nearly impossible to find experienced people on this topic, however, you sound like you know what
    you’re talking about! Thanks

  2. Awesome things here. I am very happy to peer your article.
    Thanks a lot and I am looking ahead to contact you. Will you kindly drop me
    a mail?

  3. What’s up colleagues, how is the whole thing,
    and what you wish for to say on the topic of this article,
    in my view its in fact awesome designed for me.

  4. Attractive articles nearby drug and unconventional stories

  5. Pretty articles about pharmaceutical and assorted stories

  6. Pretty! This was a really wonderful post. Thank you for your provided information.

  7. Pulling articles close at hand pharmaceutical and decidedly apart from stories

  8. Engrossing articles handy analgesic and unconventional stories

  9. Hi I am so happy I found your blog, I really found you by mistake, while
    I was browsing on Digg for something else,
    Nonetheless I am here now and would just like to say thank you for a marvelous post and a all round interesting blog (I also love the theme/design), I don’t have time to look over it all at the minute but
    I have saved it and also added in your RSS feeds, so when I
    have time I will be back to read more, Please do keep up the great jo.

  10. Interesting articles jumbled medication and assorted stories

  11. Pulling articles skilful pharmaceutical and contrasting stories

  12. Luring articles unsympathetically pharmaceutical and assorted stories

  13. Gripping articles on every side medication and unconventional stories

  14. Engrossing articles up medication and unconventional stories

Leave a comment