Posting source code on WordPress.com is quite simple: the platform already provides an extremely easy to use shortcode called  sourcecode, based on a fairly flexible syntax highlighter plugin. By looking at the examples in the documentation page, however, it is evident that the default styling used to render sources is quite old-fashioned and does not fit most modern themes.

While the shortcode offers options to allow users to control many options of the rendering, it does not allow us to configure colors, fonts and size (the default size is so tiny that it is barely readable on high-resolution screens).

When I was writing the previous technical post, I did some investigations to figure out what options are available to post more readable sources if your blog is hosted on WordPress.com and I found out there are basically two alternatives.

Embedding Gists

The easiest option is to rely on Gist – GitHub’s tool for sharing snippets of code – which offers an extremely easy way to embed code in your blog. Just create a new snippet (gist) there and follow the instructions.

Unfortunately, the gist embed shortcode available on WordPress.com is less flexible than what you would get if you installed it as a plugin on your own instance of WordPress, but it will be enough for most cases.

<th>
  Cons
</th>

<td>
  Suitable for posts with a few (long) code snippets
</td>

<td>
  Does not always work perfectly with search engines
</td>

<td>
  Does not work with RSS and posts over email
</td>

Styling source code by customizing your CSS

While Gists work great most of the time, they are a pain to create and maintain if you are working on a post that should include multiple short snippets of code. In that case, the amount of bookkeeping you have to do is significant (you will have to create and link many small chunks of code) and you may want to be able to manage your code right within the post.

In that case, it may be more practical to fix the CSS theme used by the syntax highlight plugin to make it look post-2010. If you set your own custom CSS on WordPress.com, it will be supposed to be included as the last one to allow you to redefine the styles specified by the theme you are using.

Unfortunately, the CSS used by the syntax highlight module was clearly not written with extensibility in mind, but quite the opposite:

• all the style declarations it includes make use of !important,
• the plugin will dynamically include its own CSS as the last item in the head node, meaning that it will have preference on the custom one you define.

This makes sense in the original context – the original syntax highlighter offered several themes you could choose from by including different stylesheets, but that feature is not available on WordPress.com – but will make your life more difficult. You will need to add !important to all the CSS declarations you redefine and you will need to use CSS selectors that are more specific than the ones used by the plugin. You will be able to see the final result at the end of this post.

WordPress’s syntax highlight is not perfect, and some things are still quite annoying (e.g. line numbers get in the way if you try selecting and copying source code). Most issues could be addressed by upgrading the plugin to use version 3 of SyntaxHighlighter instead of the outdated version that is in use now, but it is something you will not be able to control unless the folks at Automattic decide to update it.

<th>
  Cons
</th>

<td>
  Hard to copy sources without including line numbers (unless you disable them)
</td>

<td>
  Search engines index sources with the post content
</td>

<td>
  Getting your CSS applied correctly can be difficult (but you can start from <a href="https://gist.github.com/4464280">here</a>)
</td>

What did I choose?

Here is the stylesheet (embedded as a Gist) I am currently using  on this blog, based on the pygments theme used to style code at  docs.python.org.

You can can see what the final result looks like in this post about  User authentication with webapp2 on Google App Engine and in the image at the beginning of this post.

Update: I since migrated this blog to a new system, and am using a completely different way to render source code.