My Emacs package Orgox to publish my notes

Currently you’re reading a note from a repository of notes I maintain on GitHub, swinkels/notes. Each note is an Org file and because GitHub has some support for org-mode, the notes are rendered “ok-ish” when you view them in your browser. To also have a more “professional” presence in the blogosphere, earlier this year I published my notes at my blog.journeythatcounts.nl using the static website generator Hugo. This note introduces the Emacs package I developed to convert the notes to the Markdown files that Hugo expects, named Orgox.

Why Orgox?

Hugo expects its content to be formatted using Markdown. Although Org can export Org files to Hugo Markdown files via its exporter ox-hugo, such an export needs additional work to be successful. For example, Hugo reads page properties such as the page title or the date of publishing from “front matter” at the top the Markdown file¹. ox-hugo can create that preamble if the Org file also specifies that information as Org properties. My Org files do not have these properties.

I didn’t want to change my Org notes to make them suitable for ox-hugo and Hugo. However, these changes would have made my notes on GitHub even less attractive. Furthermore, I really like that my notes are independent of any publishing framework or tool. Finally, I also didn’t want to convert each note manually because it seemed such an easy job to automate ;). And so Orgox was born.

From note to page in a website

Orgox is only one of the tools to convert a note to a page of a Hugo site:

1. Orgox converts a single note to an Org file that ox-hugo understands.
2. ox-hugo converts the Org file to a Markdown file that Hugo understands.
3. Hugo converts the Markdown files to a static website ready for publishing.

Let me give a high-level overview of what Orgox does²:

• The Org file that Orgox creates has the front matter that ox-hugo requires. For example, this front matter configures the relative address of the note in the website and its “slug”. Orgox retrieves this information from the filename of the original note file and its content.
• Some notes link to additional files, such as an image that needs to be embedded, or a file with (example) code. Orgox makes these additional files available as static files of the website.
• Although, ox-hugo supports relative links to other notes, it does not support relative links to files and directories that do not need to be published. Orgox replaces these relative links by links that are supported.

You can find the Hugo website at GitHub repository swinkels/notes-as-hugo-blog:

• directory content-org/ contains the converted notes that Orgox has created;
• directory content/ contains the Markdown files that ox-hugo has created from the converted notes;
• directory public/ contains the generated static website that Hugo has created.

This repository configures a GitHub workflow to automatically deploy the Hugo site after each commit. So if I commit a new page, it “automatically” updates blog.journeythatcounts.nl.

Next steps

Writing and publishing a note, or blog post, involves multiple manual steps across the repos swinkels/notes and swinkels/notes-as-hugo-blog: you have to create the note file with its date-based name and path, explicitly call the right Orgox function to convert the note, start the Hugo server to see the output and more. These are all steps that can be automated, possibly in combination with an Emacs hydra for easy access as described in this note.

Orgox is really useful to me and it might also be useful for others, especially when I can remove its dependency on the structure of my notes. I’ve never published an Emacs package to MELPA before but this might be the package to do so.