Recap of the previous episodes

As you might know if you are reading this page, I started to recode my old web site in combo of Org mode and Jekyll, and I've been so pleased about this choice that I abandoned my old website last January.

Adapting to version 8

But all of this was done before the release of the version 8 of org mode, a release that is disruptive according to the maintainer Bastien Guerry. The main potential issue for me was the replacement of the old export engine by a brand new one (see this page for a summary of all potential issues). It turned out that while I had to do some modifications, everything went quite fine, as documented below.

Quoting HTML tags

I embed on a regular basis very small HTML snippets in the org files of my website. The 7.x solution used a simple escaping trick where you wrote, to quote the documentation, @<b>bold text@</b> to get some bold text (i.e., to include the <b></b> tags). As I'm writing this, the official documentation does still contain this example. However, it does not work anymore.

You have now to use the new export snippets facility (documented in this page). This is much more flexible and quite convenient, actually. The above example with the bold text has now to be written as follows @@html:<b>bold text</b>@@. As you may have guessed, html stands here for the backend, hence the generalization of the HTML snippets to any backend.

Do not use macros to simplify links!

In a typical display "I don't read the documentation, do you?" attitude, I was not aware of the existence of the link abbreviation feature of org mode. And as linking to e.g., a lot of pdf lecture notes, is quite annoying, I was using macros to simplify my task. I would write something like

and then build links like this: [[{{{notes}}}/something.pdf][something]].

This does not work anymore as the above code gets exported to <i>something</i>. The fix is obvious, just use the standard link abbreviation feature.

More fun which macros

I like also to use macros in order to take advantage of Twitter Bootstrap components (as opposed to having a lot of raw HTML constructs in my org files). To simplify my setting, I used the simple trick of defining macros directly in Elisp rather than in each org files or in a setup file.

In version 7.x, this could be done easily via the org-publish-project-alist variable used by the publishing engine. Assume for instance you want to define the following macro:

This could be done easily in Elisp as macros are (were) properties of the publishing part. More precisely, the property named macro-foo should have for value the definition of the foo macro. So if your are configuring the publication of project bar, your org-publish-project-alist will contain something like this:

(setq org-publish-project-alist
	 :base-directory "~/org/"
	 :publishing-directory "~/html/"
	 :macro-foo "$1 is a foo")))

Unfortunately, this does not work anymore and one has to rely on a slightly more complex solution based on a hook called during export, namely org-export-before-processing-hook. Here the idea is to call explicitly the org-macro-replace-all function, which, has indicated by its name, is responsible of expanding macros. Then the above example becomes:

(defun apply-my-macros (backend)
   (list (cons "foo" "$1 is a foo"))))
(add-hook 'org-export-before-processing-hook apply-my-macros)

This is in fact quite similar to the previous solution in terms of the actual macro definition, but you have to apply the macros by yourself.


25 April 2013




twitter bootstrap