Org2web
Blogging with Org-mode
Because I work so much in org-mode, I wanted to also write my blog in org-mode. Org-mode is not just an amazing tool for organizing your things, it is also the best markup language in the world.
Headers are marked with a series of *
's at the beginning of the line (the more you add, the deeper it is in the hierarchy).
Text can be marked *bold*
(bold) and /italics/
(italics).
In-line code blocks are indicated with = signs (this is code
).
The linking format is simple, and you don't actually have to memorize it because C-c C-l
opens a minibuffer which allows you to easily insert a link.
Exporting
Not only that, org-mode exports to just about everything (especially if you install pandoc). So if I write a blog post that would actually be helpful for my coworkers to read, I can easily export it to a PDF to distribute it to them. In fact, I've found at least 2 or 3 posts which purport to export from org-mode to Google Docs, though I haven't had a chance to test any of them yet.
I am using Github Pages to publish my blog because it's a simple, straightforward way to publish a static webpage. It is even possible to add comments, though I have not yet done so (in large part because I don't feel like moderating comments). I considered Wordpress, and I may yet switch to Wordpress if I cannot solve the issues described below, but I like the idea of keeping the whole website in git.
Now, there is a fairly simple-minded and straightforward way to publish a static webpage from org-mode to Github pages.
Create two directories, a src
directory which will hold org-mode documents and an export
directory which will hold the html.
Then, you simply write your blog in the src directory and use the org-export menu to export to the export directory.
The export directory is your git repo, so now you simply add, commit, and push to origin.
But that doesn't do things like nav bars, CSS, tags, etc.
I could write that stuff by hand, but that's a lot of extra work.
The Search
So I searched for options. I began with the obvious: Jekyll is a static site generator, which would meet my needs. But it is written in Ruby, and Ruby is not a language I am familiar with. Having code written in languages I don't know running on my computer isn't something that generally bothers me, but it seemed a bit backward for a technical blog.
I looked at a pair of Python generators (Pelican and Nikola). I was able to get Nikola installed, but the org-mode export didn't work correctly. I was about to try Pelican, but I discovered org2web first.
Org2web
Org2web looked like exactly what I wanted. In fact, it seemed that it did everything I wanted and more and it was fairly simple to use. So I set it up (which was as simple as calling org2web-add-project in my init.el).
I would normally describe how I set this up and use it here, but I currently cannot recommend this tool for publishing unless you're running Linux. This is because of how it currently handles exports. From my (limited) understanding of emacs lisp, it seems that it actually requires specific terminal emulators in order to run. Here is the code snippet, found beginning on line 50.
(defcustom org2web-terminal-emulater (or (executable-find "x-terminal-emulator") (executable-find "gnome-terminal") (executable-find "konsole") (executable-find "rxvt-unicode") (executable-find "rxvt") (executable-find "xterm")) "Terminal emulater used by org2web update script." :group 'org2web :type 'string)
My Mac does not have any of these things, nor do I want it to. I've asked about the status of an issue on the Github for this package (Here's the issue). If this can't be made to work, the next step will be to transition away from org2web, likely to Wordpress since it has a supported org-mode export package.