Software Curmudgeon

Mumblings and Grumblings About Software

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.


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

#+HTML_HEAD_EXTRA: <link href="/let-the-design-decision-stand" rel="canonical">
#+INCLUDE: "../posts/let-the-design-decision-stand.org"

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.




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>