Publishing on the web with Jekyll, Emacs and Org-Mode

I have been using Emacs and Org-Mode every day in my professional life for about a decade. So for me, the highest level of convenience for taking notes is to write them down in my Emacs setup in an Org-Mode file. Not only do I prefer the syntax over markdown, I also memoized a lot of shortcuts on the keyboard that maximize text editing efficiency for me.

Over the years I came to the conclusion: Only Emacs should be used to work with .org files.

I know there are plenty of Org-Mode parsers, viewers and publishers out there. But in the end all of these are incomplete attempts to mimic what makes Org-Mode special. They will all fall short of the original at some point.

So for me it became clear that I should stick to the original publishing mechanism of Org-Mode. But: While it is great to export .org files to html, it feels rather complicated to build a whole site around this publishing mechanism.

I resorted to another trusted technology of mine: Jekyll.

Jekyll is a Ruby-based static site generator. I use it since around 2010 when I published my first Github page.

Jekyll is based on long-living, stable Ruby libraries. In over 14 years, the combined effort spent on upgrading the dependencies of the multiple sites I run with it is probably less than one evening.

It does not use npm, which is probably the most important factor to create a stable, low-maintenance tech setup these days. In general, this site does not use a JS-based build tool at all.

I love the simplicity of Jekyll, yet I also got to learn of some nice features of the software over the years (like data files, collections or custom hooks).

The publishing involves both systems: Emacs converts .org content to HTML and Jekyll builds the whole rest of the page around it.

I have configured Org-Mode's publishing system to handle all the specifics of content generation. The configuration specifies that all my .org files are stored in a specific directory (./_org), and whenever I make updates or save a file, Org-Mode exports them into HTML format.

The generated HTML pages, as well as additional HTML pages and static assets such as images, CSS, and (in theory) JavaScript files are handled by the Jekyll build system to generate the the full website.

To further streamline my workflow, I make use of the Transient library in Emacs, which provides a convenient interface for executing various tasks related to the website.

Transient allows me to define a custom command center within Emacs that brings together all the important functions I need to manage the site - from starting the local Jekyll server, to creating new posts, to viewing the site in the browser, or triggering a deployment.

I host the site on Netlify, using the netlify-cli to push new versions of the website.

I manage the deployment directly within Emacs, using Prodigy, an excellent tool for managing services and tasks. Prodigy allows me to run short-lived tasks like `jekyll build` as well as the full deployment process, all from within Emacs.

Emacs, Org-Mode and Jekyll play very well together. They are all technologies that I enjoy for a very long time.

They combine my favorite way to create content with my favorite way to deliver content. To have the best of both worlds is a very nice experience.

This is a very indivdual setup that always had the goal to bring me joy personally. I do not intend to publish in any packaged way, however the setup is fully documented in the public repo of this website.