Blogging in Org-mode
Published on Oct 15, 2021 by dix.
Frequent readers of this blog (the dozens of you there are) will likely have
noticed that the format of it has recently changed. This has something that has
been long in coming but I had never been able to figure out how to do it well
until recently. Sometime in the middle of last year, I started to fully commit
to using Emacs as my daily driver. In particular, I wanted to invest some effort
in learning org-mode and even more specifically wanted to start using org-roam
for note taking. I hoped that a more intentional approach to note taking and
research, for lack of a better term, could yield dividends in the frequency and
quality of my posts. I also started moving other parts of my professional life
into org-mode, e.g. preparing presentations and diagrams at work using it.
However, one activity remained outside org-mode, the actual publishing of my
blog. I was drafting posts within my org-roam directory, but haven’t to
transfer them and translate them into markdown to be published on Github pages
with jekyll.
But as of last week, no longer! I had always known it was possible to publish a
blog using only org-mode but I had never find the right guides on how to do
it. Thanks to a couple of YouTube videos and blog pages linked below I was able
to figure out how to do it, and I’ll never have to leave Emacs again.
I wrote this post to document some of the useful resources I found to set this
blog up as well as a trick I figured out to duplicate some of the functionality
of jekyll.
Permalinks
When I published my blog through jekyll, some of my posts were published at
multiple URLs. I hadn’t totally realized this was happening until I checked the
traffic to my blog and saw a bunch of 404s. Turns out one of my posts had been
available at a second permalink which I lost in the migration to org-mode. My
initial solution for this was to create a second copy of the post with a
different filename. This worked, but caused the page to appear twice on the
index and the RSS feed. I also wanted to tag one version of the post with a link
to the canonical version.1 The following org-mode file is all I needed to
implement this. The #+INCLUDE: line instructs org-publish to include the
source of the other org-mode file when publishing this file.2
The above file is named using-precedent-for-software.org which creates a file
for at using-precedent-for-software.html and eliminates my 404s. This file is
located in a different directory from the other posts and is therefore excluded
from my index page and RSS feed.
Resources
Footnotes:
None of this really matters. Having my blog optimally crawled and indexed couldn’t possibly make a difference in any way, but well I did it anyway.
#+INCLUDE: can also be used to include the literal source of another
file rather than publishing its contents. In fact #+INCLUDE: is how I am
including the contents of my redirect file below. To include the source of
another file, the syntax is #+INCLUDE: <file-path> src <file-mode-for-source>