My mental health has recovered to the point that I can work on moving the static part of my website onto its own domain name and server. That is good, because WordPress’ web interface has become even more intolerable. Automattic has other frustrating policies, like storing images on their domain not mine (so if I move the site links on other sites to the images break), and editing a customer’s site to stop them from using someone’s legal and most famous name. If you want to see how a computer scientist thinks about this problem, read on!
 a scientist with a diploma that says CSC and a resume with “junior software developer” under work experience, at least
I last coded a website about 20 years ago, and last coded an application of more than 100 lines about ten years ago. HTML 5 seems to have introduced many new features which come from a ‘big corporation’ and ‘mobile-centric’ perspective. The static part of my site has different features:
- tens of pages, with ones of pages added per year
- pages rarely change but must be available at the same URL indefinitely
- visitors can write little or nothing to the site
- most visitors have a full-sized screen and a keyboard
- needs to be accessible offline as well as online
- hosts images where I can share them on other sites (including adjusting their size)
It also has to obey the same principles of software engineering as any website designed to share information:
- if a site for words and pictures is blank without enabling scripts, its not worth enabling scripts to see them
- write once read many times. If something is true across multiple parts of a site, it should be written in exactly one place and changes there should propagate across the site (added 2022-12-10)
- cool URIs don’t change
- a given fact should be written in one and only one place (so the things which are the same for every page of a given type should be written in one place, not written for every individual page
- open standards over proprietary, widely used technologies over rare ones
- if you had to be clever to write it, you won’t be clever enough to debug or update it
- it has to create as few barriers to adding new pages and files as possible
I am not particularly interested in layout and typography and other ways of making a site pretty (even aside from how ugly many of the Apple-style, script-heavy sites are on a full-sized screen). And a lot of the features of HTML 5 seem centred around Content Management Systems and tiny touchscreens. Right now, I am not sure of the best way to handle layout for variable screen sizes.
It seems like the horrors of trying to support older versions of browsers, especially Internet Explorer, are not an issue any more unless you are writing a site to be viewed internally at a bank.
Whereas a lot of advice for web coding takes its model from online stores and giant sites and mobile apps, the model for my static site is sites from the early reenactment movement like I. Marc Carlson’s website. These meet my requirements and principles. I do not understand why people talk about ‘stacks’ for most people’s websites. The purpose of my static site is to be simpler than maintaining a dozen accounts on ‘free’ services which spy on me and change their interface or vanish at random.
At first static site generators like Hugo seemed like a good solution, but as I learned more I decided I was wrong. Hugo seems to want users to spend a long time learning about things like Go and Github, and because it is so complicated it is hard to diagnose problems. It seems like it might be a good tool for professional web designers who can amortize the work of learning how to use it.
I don’t understand the use case for John Gruber’s markdown. It is less powerful than BBCode as a ‘html substitute,’ so it can’t do most of the things that HTML 4 could do. The tags it lets you create are ones which are quick to type in HTML. The extensions of Markdown which allow tables are much uglier than a HTML table out of the 1990s, or the BBCode equivalent! It makes footnotes easy to write I guess …
The way of making a static website which makes sense to me is having a script which wraps the code which is the same on every page around the contents, and uploading the processed files to the server. I am looking into the possibility that pandoc plus shell scripts are the right tools for this. Pandoc has a template feature, but my first attempts to use Pandoc on my Ubuntu box are going oddly- the header with metadata marked up as YAML is being deleted when I generate the final HTML file. I think that one reason why I have a difference of perspective from the folks at The Programming Historian is that they have backgrounds in English so probably don’t worry much about parallel-text editions, six languages and three scripts in 500 words, direct links to bibliography entries, and other things philologists have to worry about. Roman Geber has a handy sketch of how he creates static sites with pandoc and shell scripts https://www.romangeber.com/static_websites_with_pandoc/
Before 2016, Maciej Ceglowski had some very wise thoughts on the subject in his talks (uploaded on a simple static site, because of course it is). His perspective since then on sites like Tech Solidarity has diverged from mine.
I am still looking for explainers of the new concepts in HTML 5, and how to use them to make a simple site with a header bar, a sidebar, and a content area without pulling in a lot of third-party resources and third-party tracking. If I can keep the paragraphs from spreading out to the full width of a large screen, but keep the site readable on a small screen, I will be happy.
Edit 2021-04-02: The Hacker News folks got excited about Jeff Huang’s “This Page is Designed to Last” (2019) https://jeffhuang.com/designed_to_last/
(Scheduled 1 April 2021)