This website is a static site, by which I mean, it is a folder of files on my hard drive .
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 there are many systems for making them, each pitched at a particular level of nerdiness, but there are few methods targeted at non-nerds. Also, yak shaving risk: Such sites are 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 sit 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 blogophere.
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.
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: 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:
- Good graphical preview in an editor.
- Intuitive handling of images and other media.
- 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.
- quarto is basically a reinvention of blogdown, but cleaner and easier.
- Next.js by Vercel has momentum and is beloved of people building rich interactions and sites that transcend the feeling of 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.
- Gatsby (javascript) is another hipster JS one, probably slightly past Next on the hype curve
- 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.”
- Pelican (python), the previous engine for this blog, is easy to hack if you use python.
- 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 it is up to you.
For my part, I used dokuwiki for a while (no longer recommended), then switched to Pelican (fine), and have now settled upon blogdown (i.e. hugo+RMarkdown) which has better support for academic blogging.
Editors
Local editors
If your static site system comes with some kind of app that will edit that site it is called a CMS, for content management system. There is a continuum between that and an editor with integrated static site generator capabilities. Also there is no sharp distinction truly between online and offline editors, for all that I have tried to make one below for the sake of simplicity. Sometimes the local CMS can run on the internet, sometimes that would be unwise or inconvenient.
If you use markdown, which is the de facto standard markup for plain text blogging it might be a good start to simply preview that in the old code editor. If you are using some other weirder specialised markup, good on you but I will not cover that complexity. Presumably if you know enough to do that, you know the consequences.
For a combination blogging tool and encrypted markdown edition note storage you might want to use something like standard notes, which costs some money when you use the bells and whistles, although might be worth it if your notes include confidential ones.
Preview tools, that show you plain text as rendered web-style HTML, make it all nicer.
Lektor is a static site generator with an integrated local CMS that looks Wordpress-like. Seems to be made of python.
publii is a desktop-based CMS with integrated site generator for Windows, Mac and Linux. Seems to be based on Electron/node.js.
Text editors Atom and vs code have built-in markdown preview, which is rough but often helps.
RStudio has sophisticated integration with blogdown blogs.
blot.im (USD4/month)
A blogging platform with no interface
Why a blogging platform with no interface? So you can blog with your favorite tools. Blot turns a folder into a blog. Drag-and-drop files inside to publish. Images, text files, Word Documents, Markdown and more become blog posts automatically.
Support mathematical markup.
Hokus is one just for Hugo sites. (Untouched for two years).
As mentioned above, Caddy has a built-in automatic hugo editor.
marked is cheap macOS markdown editor/previewer…
restview is a previewer for an alternative markup called ReST
mou is cheap and looks nice.
and (free! open source! mou-like design): Macdown
livereload turns any browser into a preview tool.
Experts can run a localhost dev server which will host a local copy of the website
Online editors
Websites that edit your website for you.
forestry seems popular. It has a rather good interface and I quite like it, but there are red flags
- sunset product receiving no updates, and also
- it wants intrusive repository permissions (it seems to demand read and write access to all my private github repos?)
NetlifyCMS is Netlify’s generic CMS client for various static site backends offering a friendly, integrated CMS workflow. Code seems to have been untouched for two years.
Tina, by the creators of forestry.io, specialises for NextJS in particular but adds extra features by being tightly-coupled instead of generic. User experience at this stage is ungainly; there is a lot of logins to various different static site providers and the default config didn’t actually set up a working site for me, and now I cannot work out how to even delete it. But the demos look impressive. Maybe it will get better?
gitbook is a markdown website GUI and publishing toolchain.
“Prose provides a beautifully simple content authoring environment for CMS-free websites. It’s a web-based interface for managing content on GitHub. Use it to create, edit, and delete files, and save your changes directly to GitHub. Host your website on GitHub Pages for free, or set up your own GitHub webhook server.”
It is indeed lovely and minimalist. The subset of markdown that it supports is also minimalist, so this blog looks funky if I edit it in prose. If you do not need mathematics and citations this is not terrible option.
Draft is a collaborative frontend for document editing although not AFAICT publishing.
Commercial option Cosmic can do lots of stuff, but for multiple users is expensive (USD99/month)
Wagtail plus django-bakery together render static sites from a dynamic database. One could fashion an UI out of these parts, but it would be a lot of work
Gitit is a wiki backed by a git, darcs, or mercurial filestore. Pages and uploaded files can be modified either directly via the VCS’s command-line tools or through the wiki’s web interface. Pandoc is used for markup processing, so pages may be written in (extended) markdown, reStructuredText, LaTeX, HTML, or literate Haskell, and exported in ten different formats, including LaTeX, ConTeXt, DocBook, RTF, OpenOffice ODT, and MediaWiki markup.
cactus is a plain website generator, that features a GUI-ish client, cactus for macclasseur attempts to be friendly for more than nerds.
Link checking
See link rot.
Themes
Try JAMstackthemes for a smörgåsbord of themes for various software.
Hosting
Here are some hosts I have auditioned to host my main static site (i.e. this blog).
github incidentally hosts sites as part of their
github pagesthing.netlify is a hosting/CDN/etc provider with good github integration, with especially fancy affordances for javascript static site builders like gatsby or nextjs.
They support a local dev server which makes stuff convenient.
Vercel supports many static apps and has integrated tools for traffic tracking. See Simon Willison’s case study. They presumably support nextjs well because they invented it.
Various other generic hosts such as Hostinger or Vindo. Have not tried.
Useful:
Instant site publishing from a folder of files: Netlify drop.
Commenting
Hosting comments is a weak point for static sites, since by definition there is no content server to wait around for random drive-by interactions from the internet. But it is feasible by leveraging various other hosted services, in a slightly laborious, quirky, two-tiers-of-content kind of way.
I used the hosted Disqus system but it was bloated and suspect, so I seek alternatives.
- Start with Cloudcannon’s Commenting for Jamstack overview
- Ben Fedidat’s reviews.
- Hugo’s suggestions
- Peter Baumgartner’s reviews
Bake comments into the site code
Welcomments is a new entrant that for a monthly fee will de-spam and stash comments in github for you. I currently use this service for this site and I love it. They handle all the hosting.
staticman is an (optionally) hosted (open source) app that integrates comments into your source. It looks mostly smooth; the lack of authentication might be tedious if there was a lot of traffic on your blog.
There is a Go option called remark42.
Netlify advocates for their own DIY solution: gotell: Netlify Comments is an API and build tool for handling large amounts of comments for JAMstack products, but it seems to be discontinued?
Hypothes.is
Web annotation tool hypothes.is can be used as a weird kind of web comment system.
Annotate the web, with anyone, anywhere. We’re a nonprofit on a mission to bring an open conversation over the whole web. Use Hypothesis right now to hold discussions, read socially, organize your research, and take personal notes.
It is targeted at academics who are the people whose comments I generally want, plus is run by a non-profit. It has fancy options.
Seems to be open source, and in principle one could extract ones own data from it.
Self-hosted comment server
One could host a server running its own comment system.
The two most hip seem to be Commento is an optionally-hosted open-source comments software. Both these have heavy dependencies if you are self-hosting.
Schnack is a simple node.js one supporting various
3rd party authentication.
Another simple alternative is isso (python) it
has no third party authentication support so I am nervous about having to do my
own account management, but it has a certain kind of seductive simplicity.
Talkyard is optionally-hosted open-source forum software which integrates blog comments as a side effect.
Comments as github issues
A small amount of work can repurpose github issues as a comment system, although it is clunky, and requires your users to be prepared to open github issues if they want to comment, which is nerdier than one would like.
This can be made smoother with utterances which automates some of the legwork in github comments at the cost of needing a helper app to run.
Comments as github discussions
A comments system powered by GitHub Discussions. Let visitors leave comments and reactions on your website via GitHub! Heavily inspired by utterances.
- Open source. 🌏
- No tracking, no ads, always free. 📡 🚫
- No database needed. All data is stored in GitHub Discussions.
- Supports custom themes! 🌗
- Supports multiple languages. 🌐
- Extensively configurable. 🔧
- Automatically fetches new comments and edits from GitHub. 🔃
- Can be self-hosted! 🤳
Searching
See the list of tools maintained by Hugo. For my config, algolia/algoliasearch-netlify is convenient and cheap, so I use that. TODO: work out how to link to searches.
Comment server less suspect than disqus
Hyvor Talk is a disqus alternative. The following two are self-hosted but also offer a paid non-self-hosted version: