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.
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.
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.
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.
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
'(("org-files"
: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)
(org-macro-replace-all
(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.