Table of Contents

About this blog

This blog is written in org-mode, and is exported automatically by org-publish. It's pretty awesome.

I basically just write everything in org-mode, and have a single function to generate the static HMTL for my blog. Feel free to have a look at my configuration.

Code samples

My work is writing code, so when I blog I tend to include a lot of code blocks in what I write. Syntax highlighting of source code is not just a matter of aestetics, it makes reading source code a lot easier.

Some people use javascript to highlight source code, others use Pygments, and others yet simply embed a Gist to display their source code. Org-mode lets me use Emacs to highlight my source code, and anything that Emacs is able to do syntax highlighting on will be syntax highlighted in HTML as well.

One particular advantage of this is that the code samples are not embedded with Javascript; try reading blog posts with embedded gists in Pocket and you know what I mean.

The #+begin_src+ and #+end_src+ keywords

To add a source block, simply create a block like this

#+begin_src ruby -n
puts "Hello world"

This block takes quite a lot of parameters, here are some of the ones I use all the time:

  • The first parameter, which tells org-mode which language you're writing
  • -n Add line numbers next to your code
  • +n Add line numbers, but start the numbering on the next line from the previous code block. Useful when you're explaining code in chunks at a time
  • :exports determines how to determine what to output, see The :exports parameter below
  • :results determines what parts of a code block to export, see The results parameter below

Automatically evaluate the code

But you know what's really cool? My setup not only prettifies my code samples, it will even run them for me and insert the results of the evaluation.

Code blocks in org-mode can be evaluated when exporting to HTML, and the results of evaluation will be inserted into the exported file.

The :exports parameter

Inside a code block you set an :exports parameter to have the code be evaluated, like this:

#+begin_src ruby :exports both

The :exports parameter can be one of:

  • code: only the code will be exported. This is the default, and will not have code blocks evaluated
  • results: only the results of the code will be exported.
  • both: both the code and the results are exported
  • none: neither code nor results are exported

The results parameter to a code block

You can choose to have the result of code evaluation be the (implicit return) value :results value

1: "Hello world"
Hello world

Or you can have the results be what is printed to standard out from the block, using :results output

1: puts "Hello"
2: puts "Once more"
Once more

You need to tell org-mode which languages to support and trust

You can use customize to tell org-mode which languages it should evaluate. The default is only to evaluate emacs-lisp.

If you set up org-mode to evaluate code blocks, they will be evaluated when you publish your blog automatically. Use customize or set org-confirm-babel-evaluate to a nil value to not have to confirm the evaluation of every code block on your system. Do think twice about the implications of this, however, and don't evaluate code you're uncertain about.

Automatically export all code blocks into a file

This is not something I'm doing yet, but org-mode lets you export all code blocks from a document into a separate file. This process is called tangling. There's more in the manual.