getimiskon's space

Publishing with Org Mode

Posted in 2023-07-18

During last year, I started publishing my posts and rewrote my website with Org mode. For those who aren't familiar with it, it's a way to write and publish text. Org mode is a basic feature on Emacs, but you can use it on other text editors by installing a plugin.

In the past, I have been experimenting with sblg, which is a simple tool for blogs. It's not bad, but I wasn't satisfied with it, as I still had to write HTML for each post, which I didn't quite like. For some time I was experimenting with Emacs, and since I decided to take the time to learn its basics, I decided to give Org mode a try. It took some time to get used to it, but it become one of my favorite features on Emacs.

There are some things that make Org mode nicer to use. First, it's the simplicity of the syntax. While it's different than Markdown, it's not hard to understand how it works. To make it even better, even complex things are made easy, like tables. Second, you can embed code in the file. On my website, I embed quite a bit of HTML in some places (I'll explain why later in the post), but also lines of code when needed. For example, my configuration for Emacs is actually an Org mode file. Last, but not least, exporting the file to an HTML file, or another type of file, is easy and quick, just by pressing a few keys.

While there are lots of reasons to use Org mode, unfortunately there are some caveats. Some of them are because I designed my website being originally made for HTML written by hand, but had to adapt it in some ways to work with Org mode. If you write something and export it to HTML without changing the default options, there's a default style that gets applied, something that I definitely don't want, since I want my website to have a specific look. For my pages, I use the following options.

#+options: toc:nil num:nil html-postamble:nil html-style:nil html-doctype:xhtml-11 author:nil title:nil

Despite my changes, I still have some issues. For example, Org mode tries to resolve external links, but some links aren't recognized which causes the file not to be exported. To solve that issue I have to write a bit of HTML in the file to make it work. There's an option that allows "broken" links, but in my case it's still problematic, as the links do not appear in the exported file.

Another problem I had to deal with was that some elements in the pages just don't work well. For instance, working with lots of images can be a bit of a pain. While it's trivial to add these in Org mode, they just seem broken on my configuration. So I have to write HTML to match exactly how these things should look and feel.

Something I want to work on is to automate the update of the RSS feed. While I automate a bunch of stuff during the publishing of a post by generating a new file from a template, I still have to figure out how to automate the RSS feed. Currently I have to write the post first and then I manually edit the RSS feed file after I'm done with the post. I'm sure there is a tool that handles that, but I haven't tried it yet. If you know something that does that job, let me know.

Thanks for reading.

Created by getimiskon.
This work is licensed under a Creative Commons Attribution 4.0 International License.