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 (except for an addtional file for the style) 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 with new entry.

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 headers and the URL to the feed. I make small but reasonable exception for the CSS style sheet this.

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.