How I Publish HTML from Org-mode

Org-mode is for keeping notes, maintaining TODO lists, doing project planning, and authoring with a fast and effective plain-text system. It is also an excellent markup language from which HTML can be generated. Comparing to other markup such as markdown, org-mode has some advantages that

1. It can export source code with syntax highlight.
2. It can embed LaTeX equation snippets and export them to images.
3. It generates div around text under each header, so it is easy to adjust the left offset of paragraphs in different level.

Org-mode supports exporting to HTML, but it is not convenient to export many HTML files, e.g., for a site. Publishing can help, but it does not meet my requirements. I have many changes should be applied on the generated HTML. For example, in my notes, I added a breadcrumb and sidebar. In this blog, I need to replace the HTML id in post to make them unique. It can be done by adding org-export-html-final-hook, and I do have added one to clean up unnecessary <br>. But it is painful for me to write complex filter in emacs-lisp, I prefer a easy-to-use script language. I also want to automate the publishing using a tool like Makefile. So I turn to Rake.

The Ruby code can be found in my github repository rubylib. I use it to publish blog and notes.

The publishing has two stages. First org files are exported to HTML files in a temporary directory. Then various filters can be added to change the HTML file and result are saved in destination directory.

I export org to HTML by starting a new instance of Emacs, because I don't want the export block my editing work. The export instance starts with only necessary configurations, such as setting up theme and tab width.

Filters are connect like pipes. I can add dynamic content, fancy widgets or just change HTML to make them look better. For example, in BlogFilter, I make all ID unique so two posts in the same page does not have conflict ID. I add class to exported LaTeX images, so I can apply CSS rules to it. I also add a link at the end pointing to the source org file or the post.

The blog publishing is not automatic. I'm working on Ruby script to automate it using WordPress XML-RPC.

source of this post.

Related posts:

1. Pretty Emacs Diff Mode