Migrating my website to Org Mode

For some time, I was satisfied with Pollen. I achieved a pleasant aesthetic, and had the flexibility to introduce components with ease. However, Pollen began to feel less like a markup language and more like an alternative frontend syntax. I wanted to transition to a markup language that enabled me to focus more on content rather than display.

Scribble is one of Racket's core tools, providing a standardized DSL to write documentation for code. Many professors at Northeastern additionally use it for developing their course pages, as one of its advantages is tight integration with Racket: documentation is easily linked and Racket code can be evaluated and embedded directly in outputted documents.

When considering moving away from Pollen, Scribble was my first option. I could begin to introduce blog posts even more tightly integrated with Racket, linking to documentation and running various codeblocks. The main drawback, I realized, was customizing Scribble's output for a website.

The difficulty is that Scribble is primarily a code documentation tool, providing amazing defaults for writing manuals for DSLs, at a cost of offering inflexibility with other targets. There were two options I had within the realm of Scribble:

• Write a custom mixin for Scribble that extended the HTML generator, and rewrite many methods to accommodate both HTML components I had written and the dramatically different structure of the page I had in mind.
• Write a custom mixin for Scribble that targeted plaintext, but produced HTML. While it was more flexible than the first option, it was still quite a daunting task, since I would need to handle all HTML elements that I previously used in the Pollen version of my website.

I initially begun a rewrite of this website pursuing the first option. Leveraging existing mixins gave me a modest headstart, but the amount of methods I would have to override became a larger task. It was at this point where I began reconsidering my options.

I was stuck on transitioning out of Pollen for a while. During this time, I became a significantly heavier user of Org Mode, using Roam to manage my personal documentation about my systems and life, agenda to handle my calendar and TODOs, and org files in my CS lectures to take interactive notes. Gradually, I began enjoying org-mode a lot more, especially with notes that I could take and run during lecture.

Org Mode gives a reasonable tradeoff between flexibility and practicality. Pollen allowed me to introduce custom components with ease at the cost of verbosity: I needed to annotate and explicitly control the typeset of the document. Org Mode gave concision: focusing on content with only annotations on explicit formatting or custom components. I prefer the latter approach.

Org Mode also allowed me to consolidate my website into using a single filetype: .org files. Previously, with Pollen, main pages were written in standard Pollen files (.rkt extension), while blog posts and project pages were written in Pollen markdown (.pmd extension). For this new website iteration, I only use .org files, which simplifies my overall workflow with this website.

Emacs is my primary editor, and Org Mode is an Emacs-first project. While other editors have adopted and introduced extensions for Org Mode, such has VSCode and Vim, their functionality is comparatively lacking. Org Mode is ultimately a first-class citizen for Emacs.

This iteration of my website is fundamentally similar to the previous iteration: the appearance is alike, along with the website's organization. Org Mode provided a simple transition, with fine-grained settings for influencing the blog's output.

HTML output for Org Mode documents produced three distinct sections: the preamble, the content, and the postamble. To maintain similarity to my previous iteration, I removed any postamble output. Then, there would be a direct mapping from my previous iteration's sidebar section to the postamble and a trivial mapping between content sections.

While structurally and semantically the HTML output was equivalent, Org Mode produced subtly different class and id names for styling. Because the output was identical to the previous iteration's output, my remaining time was spent on altering my stylesheets to accommodate the small name changes.

I consolidated more of my life into Org Mode. Now, I use Org Mode for these purposes:

• This website!
• Personal and system documentation (a wiki for my life)
• Interactive CS lecture notes
• Agenda and task management

Using Org Mode has been pretty enjoyable thus far.