I figured the time had come to host some of my modest content online for sharing, fun, persistence, easy access and all the other usual suspects. Going into this adventure there were only a few requirements that I wanted my website to meet:

• Content should be written in my favorite text editor with Org mode.
• No need for any back-end or front-end logic: serving a static website without any fancy HTML/CSS/JS shenanigans will be more than fine.
• The website should be standalone so that it can be viewed offline as well.
• Convenient hosting: hustling with administrating a web-server for such a small project would not make any sense to me.

Let me explain. I have been using Emacs and Org mode for several years now. Its markup language really fits my needs and I have integrated my Org files with the agenda and other nifty features Emacs and Org have to offer. The ability to hack their behavior in elisp is also a great plus to me as it immensely increases the flexibility of this setup.

When it comes to this website, I want to be able to turn whatever I am currently working on into publishable content without having to spend extra time on re-formatting my writing from the ground up. It was thus pretty obvious that I would give a try to the built-in org-publish package for Emacs as it is exactly what I am looking for: automated and configurable exporting of Org projects to HTML files, as plain as possible. There exist quite a few other projects which turn a collection of Org files into a website, such as Hugo or org-static-blog. But I figured I would like to retain maximal control over the exporting process and keep external dependencies as low as possible so I stuck to org-publish.

Using git versioning gives me the opportunity to track and manage changes over time. Since we are dealing with a static website with exclusively public data, github.io will handle the hosting for me. Whenever I want to work on a new item, I can pull the remote github repository, create a local branch and start editing. When the content is ready for publishing, the branch is merged into main, pushed to the remote github repository and voilà!

I ended up with something like the following directory structure for this project. The github repository containing all the up-to-date source files can be found here.

- ~/org/blog/
  - static/
    - css/
    - fonts/
    - img/
  - src/
    - index.org
    - about.org
    - posts/
      - hello.org
      - super-dupa-post.org
  - templates/
    - header.html
    - footer.html
    - post.org
    - readthedocs.org
  - Makefile
  - publish-website.el
  - README.org

src/ contains the Org files that will be published to HTML. These files are declaring as few exporting options as possible so that they can easily be used in other contexts or projects. Global exporting options will be defined in publish-website.el and page-specific options provided via templates/ or, in rare cases, directly in the files themselves. The static/ directory hosts assets such as stylesheets, fonts, images, etc. that will be exported "as is".

The logic behind publishing is implemented in publish-website.el which is called by a Makefile for convenience. It defines all the directories, files and exporting options that will be fed into org-publish. I could have written my publish-website.el in literate programming style and use it as source for this blog post, but that would have been a little bit too meta, even for me :)

Finally, README.org is just a symbolic link to src/about.org. Why? Because we can!

This publishing setup is quite rudimentary. I wrote this note mostly for self reference in case I have to implement a similar project in the future. However, I still hope it can help hesitating people to give a try to org-publish and see if it fits their needs. Maybe existing users could also get a tip or two out of this. The full code is available on my github.

I would encourage anyone fiddling with this to have the official documentation right at hand:

• Org
• Org-publish
• Worg

Here are websites that inspired me for this adventure. I highly recommend that you check them out as well as their publishing workflow:

• Building a Emacs Org-Mode Blog by Thomas Ingram showcases a simple yet effective setup.
• Blogging using org-mode (and nothing else) by Dennis Ogbe is a really neat explanations and setup with Org-file pre-processing before publishing.
• A literate programming example by ryuslash.

Edit [2026-01-27 Tue]: Updated directory structure and rephrased some sections.