Improved syntax highlighting with org2blog and custom CSS

As mentioned in an earlier post, I changed my blogging workflow to org2blog for writing and editing posts in Emacs and only push them up to my WordPress blog when the posts are almost done. I still do the final editing in WordPress so I can tweak the SEO settings and all that, but the majority of the work happens in org-mode now.

One area that really needed improving was the appearance of the source code that I put in posts. Before I started using org-mode for blogging I edited the code in Emacs, ran it through htmlize and pasted it into my blog post.. That way the Emacs theme I’m using also determined what the generated HTML looked like and it allowed me to control the code’s appearance to a certain extent. Once I moved to org-mode, I just got a generic htmlize output.

In order to improve the appearance output, I switched from the inline styled export to CSS-based export. That way, I can tweak the CSS for the basic syntax highlighting, pick appropriate background colours and all that fun stuff.

First, prepare WordPress for additional custom CSS

The web is full of warnings that you shouldn’t edit your installed WordPress theme so you don’t lose all your customisations the next time the theme is updated. The usual recommendation is to create a child theme instead. This does exactly what I needed to, but felt awfully heavyweight for the comparatively simple task at hand. All I wanted was jam some additional CSS onto a page and be done with it.

I’m using Jetpack on my self-hosted WordPress install for certain additional features that you’d normally only get when hosting a blog on Jetpack has a neat feature called “Custom CSS” that allows you to add additional CSS to your existing theme’s stylesheets. In other words, it allows you to provide exactly the kind of customisation I need to tweak the source code highlighting. If you haven’t activated the Custom CSS feature yet, go to your Jetpack settings and activate it.

Adding org-mode’s code export CSS

This is a relatively simple operation. First, you need to tell org-mode to export the source code formatting information using css and not the more usual inline style. This is easily done by adding the following setting to your .emacs and re-evaluate that particular piece of code:

(setq org-export-htmlize-output-type 'css)

Once that’s done, the easiest way to get the parts of the CSS that are relevant to source code formatting is to create an org file, stick a #+BEGIN_SRC/#+END_SRC block in there and export that to HTML. You can then pull the relevant parts of CSS out of the resulting HTML buffer and put it into the custom CSS settings provided by Jetpack.

In my case, the relevant CSS looks like this:

pre {
  border: 1px solid #ccc;
  box-shadow: 3px 3px 3px #eee;
  padding: 8pt;
  font-family: monospace;
  overflow: auto;
  margin: 1.2em;
  -moz-border-radius: 5px;
  border-radius: 5px;
pre.src {
  position: relative;
  overflow: visible;
  padding-top: 1.2em;
  background-color: DarkSlateGrey;
  color: WhiteSmoke;    
pre.src:before {
  display: none;
  position: absolute;
  background-color: white;
  top: -10px;
  right: 10px;
  padding: 3px;
  border: 1px solid black;
pre.src:hover:before { display: inline;}
pre.src-sh:before    { content: 'sh'; }
pre.src-bash:before  { content: 'sh'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-R:before     { content: 'R'; }
pre.src-perl:before  { content: 'Perl'; }
pre.src-java:before  { content: 'Java'; }
pre.src-sql:before   { content: 'SQL'; }
pre.src-clojure:before { content: 'Clojure'; }

Copy your customized CSS into Jetpack’s “Custom CSS” edit control, save your changes and you’re done. The next time you publish a post from org-mode using org2blog, it’ll automatically apply the above CSS to all your code blocks that were marked as such.

Improving my blogging workflow using Emacs (of course)

I try not to post too many metablogging posts. Other people do it better and I’m trying to focus on journalling what I learn as a software engineer and manager, not what tools I use for blogging. However after losing another post to WordPress’s built-in editor I decided Something Must Be Done. I think this is only the second post I lost, but it’s a fairly regular occurrence for a journalist friend of mine and I really don’t have that much time to retype blog entries that ended up in Bit Nirvana.

My first attempt was to resurrect the weblogger-mode setup I used to have a while ago but after switching the admin interface on my WordPress install to https, I couldn’t quite get it to work again. Plus it was a bit of a half hearted attempt as I never quite warmed to this mode in the first place. It’s actually quite odd as I tend to use gnus semi-regularly and the interface is very similar, but it never quite clicked for me for writing blog posts.

If I would exclusively blog on Windows, I’d just use Windows Live Writer, but as I switch between Windows, OS X, Linux and FreeBSD depending on which machine I’m on, Windows only software just isn’t going to cut it.

As everybody raves about org-mode (which I admittedly have never used) I decided to give org2blog a chance. It’s probably not the smartest idea to try to learn too many new tools at the same time but at least Emacs doesn’t occasionally eat my scribblings. Plus, I’ve started using Jekyll for another one of my experimental blogs, so using org mode and having they ability to publish to a Jekyll blog is also very useful.

So far I’ve got the basics up and running and the main blog configured. I’m using visual-line-mode to do automatic line wrapping and now will have to set up flyspell on the machines that haven’t got it installed yet so I can have basic spell checking.

So far, the basic workflow I’m planning is:

  • Sketch the post(s) and write the drafts in Emacs in the comforts of my local machine
  • Publish them as drafts to my standalone WordPress install
  • Do the final editing and spill chucking in WordPress
  • Ignore or heed the recommendations from the WordPress SEO plugin. That’ll be mostly ignore, then
  • Schedule the final publishing on the WordPress admin console

Hopefully that should work better than the “log into WordPress and start typing” approach I’ve used so far.