Static websites

Websites that are just files on a server, which is all I need

December 29, 2014 — January 19, 2024

computers are awful together
diy
doing internet
faster pussycat
plain text
UI
workflow

Suspiciously similar content

Figure 1

This website is a static site, by which I mean, it is a folder of files on my hard drive.

Figure 2: Screencap of me editing this site

When I want to publish new content, I run these files through a static site generator, which bundles them up, generates an index and a content page, formats everything as HTML files a web browser can understand, then copies those files to a server somewhere. After that, I am free from any further responsibility for its upkeep. The server that hosts this content can be extremely simple, which means I do not need to spend much effort on security or configuration, or hosting fees etc.

This is a high-performance, low-friction way of doing things, at least for me. I do not need to worry about manually copying my notes from my hard drive to the website. My notes are my website.

The main pain point of static sites IMO is that although there are many systems for making them, each pitched at a particular level of nerdiness, there are few targeted at non-nerds, and those tend to be messy in their own way.

Also, yak shaving risk: Static sites are usually highly customisable, and so cry out for automation and macros and setting up just how I like it, which is probably not how other people like it. Any static site generator which is too nerdy seems incomprehensibly idiosyncratic. Any static site generator which is not nerdy enough seems tediously menial. The upshot is that these things are great for personal use but can be tricky for collaboration.

The academic blogging workflow is a sequel to this one, targeted to researchers wherein I recommend plain text static-site blogging. Here I do not worry so much about certain features which are important mostly to academics, e.g. mathematical equations, graphs, citations…

Bloggers might have less academic priorities. If you want less mathematical markup and more monetization, try the blogosphere.

This documentation is oriented to my priorities, but you can find a lot of stuff googling JAMstack, which is the hype name for this static setup.

1 Software

The static site generator. The core bit. The software that takes my plain content files and turns them into friendly websites with all the nice decorations around the edges and colour schemes and indexes and stuff.

As mentioned, there are hundreds — maybe thousands — of static site generators. The lineage is ancient, including such the original World Wide Web and its progenitors, travelling via the primordial (and no longer active) static site generators such as the venerable bloxsom into the current day. See the About page to see which one(s) I am (currently) using for this site.

🚧TODO🚧 clarify: AFAICT there is not much to choose between the various site generators I mention below as far as the base functionality goes (taking some files and making them look acceptable on the internet). There are some advanced features which would be distinguishing, if I had treated them more thoroughly:

  1. Good graphical preview in an editor.
  2. Intuitive handling of images and other media.
  3. Ease of collaboration on content via a CMS of some kind.

Some interesting ones:

  • Hugo (go) is a popular system. Its R companion, blogdown, is probably ascendant for academics.
  • Docusaurus is a facebook-supported javascript one. It seems oriented to content-based sites (e.g. text blogs like this) and has a lot of momentum. It looks pretty nice per default and is not verbose. Maybe it would be the next thing for me.
  • MkDocs is python and looks pretty good for documentation.
  • quarto is basically a reinvention of blogdown, but somewhat cleaner and sometimes easier.
  • Pelican (python), the previous engine for this blog, is easy to hack if you use python.

After this, the options start to get way more abstract and featureful than I need or want.

  • Next.js by Vercel has momentum and is beloved of people building rich interactions and sites that feel like they transcend being a “static” site. If I wasn’t trying to be an academic this would be an interesting thing to try out simply because the tooling is good.
  • Lume is cool because although it is javascript, it eschews the bloaty npm ecosystem for the less messy Deno system.
  • Gatsby (javascript) is another hipster JS one, probably slightly past Next on the hype curve. Notoriously flexible and featureful, but also notoriously complex. Acquired by Netlify, which also means lots of momentum.
  • Eleventy happens to be javascript but claims to be the least obtrusive static site generator. Introducing Eleventy, a new Static Site Generator mentions “While Eleventy uses JavaScript in node.js to transform templates into content, importantly (by default) it does not recommend nor force your HTML to include any Eleventy-specific client-side JavaScript. This is a core facet of the project’s intent and goals. We are not a JavaScript framework. We want our content decoupled as much as possible from Eleventy altogether, and because Eleventy uses templating engines that are Eleventy-independent, it gets us much closer to that goal.”
  • Jekyll (ruby) is the default for github, although I personally could never make it work for me because of something about forking and plugins and other stuff that was so boring that I erased it from my brain.
  • Hakyll is a haskell variant of jekyll one with good pandoc integration.
  • Neuron (also haskell) is noteworthy because it puts Zettelkasten online, which is nice if that is your thing.
  • There are some extra ones, below, that integrate specialised editor apps, a.k.a. CMSs.
  • Not quite a static site, but org2blog publishes org mode notes to a website, even a “non static” one. As seen in Nick Higham’s Blog Workflow

Some, like jekyll or hugo are opinionated and provide a featureful setup per default. Others, like lettersmith take a DIY route where they provide the libraries to build something minimal, but the actual thing is up to you.

For my part, I used dokuwiki for a while (no longer recommended), then switched to Pelican (fine), then blogdown (i.e. hugo+RMarkdown) which has better support for academic blogging. Then I switched to quarto.

Figure 3

2 GUI editors for static sites

My editor is VS code, which is a code editor, and which I basically live in so it is comfortable for me. People who are not full-time nerds might like a friendlier interface.

See static site editors for a list of editors that are specifically designed for static sites.

4 Themes

Try JAMstackthemes for a smörgåsbord of themes for various software.

5 Hosting

Here are some hosts I have auditioned to host my main static site (i.e. this blog).

Useful:

Instant site publishing from a folder of files: Netlify drop.

Want to host your own? Get some of the conveniences with an automated deploy workflow via Coolify, which supports way too much, but in particular, static sites.

6 Commenting

See static site comments.

7 Searching

See the list of tools maintained by Hugo. For my config, algolia/algoliasearch-netlify is convenient and cheap, so I use that.

See also Add Client-side Searching via Fuse.js to Static Sites - Yihui Xie | 谢益辉

8 Migration to

9 Incoming