UPDATE!!!

November 2025: Pretty much everything in this post is invalid as I use a completely different system now.

Intro

Right after spending about 2 weeks in making genorg, my supreme and functioning (most of the time) static site generator¹, here are the hows and whys.

Criteria

My criteria compared to your career just isn't fair

• The markup document type for the a blog article should be Org, or something as powerful(void).
• The org to html function should be complete and work well. Currently (and eternally), this is only done by the emacs org exporter itself.
• Categories
• Moving files around in the 'articles' directory should still produce the same output blog. This means that the category info would need to be in the article file itself.
• A powerful and flexible templating system. This would be used for example to export to the blog page.
• Rss feeds.

Comparasion of other static site generators

Before I decided to make my own thing, I tried to find other static site generator that would meet this criteria. At the end, I was left with 2 valid options.

Hugo/jekyll

The compromise here would be using the shabby hugo org export, or use Hugo. However, this could pretty much be fixed by using ox-hugo. Now I look back at it, this would probably have been the better choice. oh well, I'm happy with I have now. I reccomend this to to all readers who have a similar criteria.

Plus, using Hugo would remind me too much of the film with the same name which I vaguely remember watching, hence forcing me to rewatch and waste 2 hours.

Org publish

I couldn't move files, plus I would have to hand maintain the category pages. No thanks, I got better things to do (gulp).

The solution

Writing about programming instead of just programming kinda sucks, bear with me.

genorg

genorg is a perl script which generates the sites from a input directory and a TOML configuration file. It scours and converts a bunch of org files in the directory, and converts them to html (if needed). Each of these files contain a id for internal use, and a category.

  Input                  Cache                Output
+-----------+       +---------------+       +-----------+
| Org files | ----> | direct org    | ----> | Modified  |
|           | ----> | html export   | ----> | html      |
+-----------+       +---------------+       +-----------+
                       |        |
                    +---------------+       +-----------+
                    | Neccasary info| ----> | navigtion |
                    | eg title, date| ----> | files     |
                    +---------------+       +-----------+

Of course, any good static site generator needs a good templating system. So since genorg used perl, I had a obvious choice ahead: Template::Toolkit. Since it used C code with perl bindings, it was extremly fast. But still very powerful since it has been around for a while.

A example info file generated by genorg to communicate with genserve:

{
  "landing": "templates/index.html.tt",
  "blog_dir": "/blog/",
  "rss_dir": "/rss/:cat",
  "main_rss": "templates/main.xml",
  "blog_file": "templates/blog.html.tt",
  "cpath": [
    {
      "file": "templates/1.html",
      "rss": "templates/1.html.xml",
      "cat": "tech"
    }
  ],
  "files": [
    {
      "cat": "tech",
      "art": "introblog",
      "file": "2025/intro.org.html"
    },
    {
      "cat": "tech",
      "file": "2025/window.org.html",
      "art": "new_window_cmds"
    }
  ],
  "main_rss_url": "/rss"
}

The navigation files are considered stuff like the category pages. To keep the urls the same even when a org file is moved, the site needs to dynamically resolve links into respsecite file paths. example.com/category/article-id needs to find the file and serve it.

Why perl?

Lisp has all the visual appeal of oatmeal with fingernail clippings mixed in.

Larry Wall, as always, puts it very well. The other reasons are because of TIMTOWDI, and typed containers (in combination with a weakly typed language.).

genserve

So now to serve the dynamicly serve the genorg output, all we have to do is parse the json file and redirect files accordingly. Easy enough… right?

Well, it would be if I was satisfied with http requests taking 0.0001 seconds to be proccesed by genorg instead of 0.00001 seconds.

So I initally decided to make the http server part in Go. This did not go well, I didn't like the language, I didn't like the http server the standard library provided. So in about one day, I wrote 300+ lines of zig code to make it work.

Although the process was tedious, the result was worth it, as any visitors get to save approximately 10 × 10⁻5 seconds for every visit.

Code

My beautiful code can be found here. As for the http server code, I won't share that. Simply cause it's crappy code and it's going to be easy to find exploits in it. If you do decide to use genorg, I suggest using a fastcgi script to serve content based of the parsed json.

What now?

I'm very happy with the software used to generate the blog and articles, but I still want to add some HTML and CSS and images in the home page and category pages to make the site more vibrant (I've recived feedback that this site reminds a viewer of a 'bee'). Maybe later, I'll write about the non-technical aspect of blogs and why I wanted to have one.

Footnotes