In the past I found that static site build systems, such as Hugo, added complexity and rigidity which wasted more time than they saved, and ultimately made me more annoyed than anything else. This is my answer, and my thinking.

Transcription, Compilation, and Deployment

Pages are transcribed in the markup language org. I could talk about all the features of org I like, however that is another whole post and inextricably tied to why I like emacs in general. It is the language of my notes, and thus natural. These org documents are compiled via a posix shell script using pandoc. The script generates the footer and passes it to pandoc. Once org files have been compiled to html, hrefs are patched via sed. Deployment is achieved by rsync-ing the target directory to my server.

Thoughts

The quality of an abstraction can be measured by its compositionality. An abstraction exhibiting compositionality can be applied to a superset of the problems it was designed to solve. To compose is to program.

The command-line is a classic example of compositionality, having survived since CTSS was developed at MIT in '61. An abstraction so ubiquitous its now passed into the realm of paradigm¹.

Pandoc is a good abstraction over document formats. I believe there is a high probability that future problems with this site will be susceptible to a composition which includes Pandoc. For example, more code-oriented writing, Pandoc supports codeblock syntax highlighting as shown:

unsigned NetbufferChecksum(void) {
  unsigned c;
  int i, l;

  c = 0x1234567;

  // FIXME -endianess?
#ifdef NORMALUNIX
  return 0; // byte order problems
#endif

  l = (NetbufferSize() - (int)&(((doomdata_t *)0)->retransmitfrom)) / 4;
  for (i = 0; i < l; i++)
    c += ((unsigned *)&netbuffer->retransmitfrom)[i] * (i + 1);

  return c & NCMD_CHECKSUM;
}

// -- John Carmack, Doom '93

Often when compositionality is eschewed it is for short term programmer ease², instead of composing simple programs we configure complex systems. Configuration based systems are forced to anticipate every problem the user will have. The delineation between composition and configuration isn't always obvious, I define it by whether the tool is prescriptivist or descriptivist about your problems.

My emacs configuration is more composition than configuration, a set of programs written by myself and others composed together to solve a set of problems I have while using the computer. Contrast this with the way static site generators are often configured, where if you one day need to write latex in an article and have it rendered, if the system doesn't already support that things will be difficult. You may even give up on writing that maths post all together, in favor of letting the system describe what your problem is.

Future Directions

With usage I expect the patterns I actually write in will make abstractions past the per-document compilation paradigm obvious. Whether this looks like appending "posts" to be displayed in reverse chronological ordering, or a more graph oriented wiki system, is currently unclear.

A similar system consistent with my tastes here is hakyll, which I will likely try at some point. However currently this serves my priority of having something exist at all, and ultimately these concerns are primarily only relevant to me, currently the only engineer tasked with maintaining this website.