About this web page

This an explanation (or justification?) of how this page is created. The takeaway is that every page is a single HTML file and no templating is involved.

Creating a page

  1. Copy index.html to page-name/index.html
  2. Update title in head
  3. Write HTML contents to body
  4. Update feed.xml. UUIDs can be inserted by calling uuidgen from the editor and inserting the resulting UUID

Why write HTML by hand?!

Reproducibility

HTML is pretty consistently displayed across most modern web-browsers, while multiple templating engines and markdown parsers are not always as consistent in their interpretation of markdown, and the details of how they render markdown may change over time.

Debugging

The feedback when editing the HTML files is immediate without an intermediate compilation step that may break when there is an issue with some template or the templating engine. Since web browsers are quite lenient in what they accept, even minor problems in the HTML will still at least partially display the page while it is beeing edited. Developer tools of modern web browsers provide extensive feedback about errors in the HTML, making it easy to debug the draft. At the same time, errors in the templates and the templating engine may lead to arbitrarily complex bugs.

Future-Proofing

I like to avoid external dependencies if the benefit from using them is not significant or easily acchievable otherwise. Static site generators include markdown parsers and templating engines which have a lot of external dependencies.

Duplicate State

A problem with single-file HTML pages is that there are multiple copies of the same data, such as the page-style and the URL to the feed. This is solved by having very few such data, so it is less likely to change, and updating it can be done with reasonable effort through search-and-replace.

Unreadable HTML

Editing HTML by hand bears the risk that the HTML contains errors or the formatting is inconsistent. Formatters like prettier can be used to check the HTML and reformat it. The diff can be easily inspected to check for inconsistencies between the initial HTML and the formatted HTML.