Migrating to Org Publish

• Export
• HTML
• Org

This post marks the move from generating this website with Weblorg¹ to Org publish with Ox-Slimhtml². I'll write another post about the specifics later, for now I mostly just want to celebrate my accomplishment, it's been a long time coming. I want to start by saying if you're interested in a static site generator that translates Org to HTML, I enthusiastically recommend Weblorg: good Jinja-style templating system, good API, very active. Sometimes I had to dig through the pull requests to find new features, but the maintainer clearly is trying to keep the documentation current. Another plus is that the library is easy to contribute to. I added a couple tiny pieces of code and the maintainer was great to work with. While I think the Weblorg project is awesome, I should note that I really have no experience with any other site generators converting Org straight to HTML. While I loved working with Weblorg and I was excited to make the transition from Ox-Hugo, I knew from the get-go that I would be transitioning again. It was the right call, but I have to confess that I'm sad to no longer have Weblorg's pink unicorn in the "Made with" section of my footer. Ultimately, I had three reasons for moving to Ox-Slimhtml:

First and foremost, I want my org files backing the HTML to have the same functionality. Exporting to HTML should feel like something that comes for free, not something to design and write to. A good example is Org links. In Weblorg, if I want to create a link to another post I would write something like this: [[url_for("posts",slug=my-post-slug)][link description]]. Obviously, Org doesn't know how to interpret this link, so if I want to refer back to the post I'm linking, I have to open it manually. As a disclaimer, this is a feature on Weblorg's backlog, it might get implemented soon. Fundamentally, this felt like baggage to me. This is mostly a philosophical grievance: I openly admit that it is not difficult or time-consuming to open a file manually. I guess it just felt like I shouldn't have to. For me, philosophical grievances build up and lead to burnout. Granted, Weblorg removed a lot of the baggage I found using Ox-Hugo, but I still felt like I could do more.

Second, I'm really excited to be coming to a (however temporary) stopping point with my static site generator adventure. I'm just excited to get to a point where I'm not thinking about it all the time. Using a new and growing API is exciting and contributing to that growth is fulfilling, but this website has about a four-year long arc that I was eager to finally resolve and so close to finishing. In theory, I suppose I could have done more to contribute and build out the features that I was wanting, but the codebase has been growing for about a year, and I always got lost trying to reason through a possible implementation for a missing feature. A major contributing factor to this is that my Elisp isn't great.

Third, I want my website to be representative of what I wish the internet had more of. Working in tech, I personally see a lot of web applications that are way more complicated than they need to be. I've worked on so many single-page applications that could have been server-rendered content. It's a little frustrating because super-responsive single-page applications are typically more work, but I feel like this choice is made at the price of simplicity and accessibility. The internet is a treasure trove of information; I wouldn't have ever been able to transition to software from engineering without it. I imagine this is true of many other fields as well. With HTML5, we have more semantic elements that help give cues to markup interpreters to convey information to visually-impaired people. I want to see more simple HTML with expressive markup aimed at providing information to as many people as possible. I have a lot of other thoughts on the advantages of simple, expressive HTML, but they're not well-founded, so I won't go into them here. It's outside the scope of this post anyway.

Back to talking about my migration. Moving to Org publish was a bit intimidating for an Elisp newbie. The Org manual has some good documentation on how to make it work³, but I found myself wishing for more context for someone still grappling with syntax. Luckily, there are tons of resources out there of people who have done what I did, but the vast majority of people use the regular HTML backend, not Ox-Slimhtml, so that's where I started as well. I took most of the code for that iteration from a blog setup I found⁴, which got me most of the way to where I wanted to be. I was still frustrated by the lack of control over how post contents are exported and wanted more customization. That resource does have a good implementation for creating an RSS feed that I carried over to my Ox-Slimhtml publishing script, and the author also wrote a blog post about it⁵.

I also found a neat resource on generating category pages⁶. At this point, this is about the last feature that I really want to add. I don't think I'll use their strategy of refiling org-agenda files, but it did give me some ideas on how to implement this with Ox-Slimhtml. After enough time being frustrated with the limitation of the regular HTML backend, I finally moved to Ox-Slimhtml by using David Wilson's configuration⁷ as a starting point. I'd probably recommend using his configuration over mine; one of my primary goals is to keep dependencies to a minimum, which made my code less readable. I think with a little work I can get my code into pretty good shape, though.

Although the code could use some work, I'm extremely happy with the end result. I acknowledge that it's not the best-looking website, but the markup underneath it is exactly how I want it. I'm excited that I figured out a way to wrap images in figure tags with figcaptions instead of silly p tags. I'm being more judicious with my nav by removing branding from it and putting it elsewhere in the header. I've been able to remove a lot of elements and maintain the same layout, reducing the amount of style classes in my stylesheet in the process. As someone who has worked professionally with complex UI frameworks, it's liberating to slash markup and CSS this way. I feel like I'm learning a lot about what I think good design should be, and I'm happy that it's resulting in simpler, more readable, and easier to understand results.

Truth be told, at the time of writing, there is one last pressing task to be completed: the deployment. As much as I want to write more, I'll save it for later and focus on getting everything deployed.