Ikiwiki Org Plugin

This is a plugin for the ikiwiki wiki compiler that interprets org-mode files.

The plugin is in a beta state – it should be monitored to ensure that it is not hanging – but is nearly feature-complete and can be used instead of the existing org-mode plugin. An example of it in action is my blog.

Compatibility

This version is known to work with git org-mode at commit 62950827eccedbb7deb11684c2ad6995213cf67d.

Motivation

Why a rewrite of the plugin?

Speed

The current org-mode plugin is very slow. It starts a new emacs process for every file that is interpreted. The emacs startup time dominates the time for interpreting the file for all but the largest files.

Flexibility

The current org-mode plugin doesn’t interpret common org-mode directives like #+TITLE or #+AUTHOR. These are not hard to parse out of the files with Perl, but the better solution is to allow org-mode itself to parse the files, and get the information from org-mode’s internal structures.

Installation

There are two main files: perl/new_org.pm and lisp/ikiwiki-org-plugin.el. The first needs to go in the ~/.ikiwiki/IkiWiki/Plugin directory and the second needs to go somewhere in the emacs load-path. However, it is not recommended that you require the ikiwiki-org-plugin file from your usually-running emacs – a new emacs instance is started by the plugin which will require it for you.

The plugin must be enabled in your wiki.setup or blog.setup file. This is done by adding new_org to the add_plugins list.

Security Warning

This plugin uses IPC::open2 to communicate with emacs. Every effort has been made to ensure that the arguments to this function can not cause damage, but it is possible that I have missed something. Given this, the plugin should not be used in situations where malicious input is possible.

Ideas for how to avoid this problem would be highly appreciated.

Debugging

If you experience problems with this plugin, the commands mentioned below can help you to debug them.

You may start with asking ikiwiki to render a single page and print the result to standard output:

ikiwiki --setup <file.setup> --render <file.org>

You may want to debug the lisp code interactively while running the above command. In order to do that, run

emacsclient -s org-ikiwiki-compiler <some_file>

This connects you to the emacs process that performs the actual processing. There you can watch messages in the Messages buffer or interactively debug lisp function (press C-u C-M-x).

If the above commands are not enough, you can even invoke individual hooks from the command line. The command below runs htmlize() hook on file.org and prints the result.

perl -e 'use new_org; print(IkiWiki::Plugin::new_org::htmlize((content => do { local $/; <>})));' file.org

License

Copyright (C) 2011-2012, Chris Gray.

Distributed under the GPL, version 2 or (at your discretion) higher.