Static sites

If my web site, e.g. a plain text blog, can be rendered by just a browser and some appropriate files hosted on a server, then it can be hosted by a static web server. This ia a high performance, low-effort way of doing things. It has some annoying keywords to describe it, e.g. JAMstack.

You would like to not have to spend energy on maintaining some fancy blogging engine on the server with databases and PHP scripts etc.

Companion piece to academic blogging workflow, wherein I will mention plain text static-site blogging choices, but I do not worry so much about certain constraints which are important mostly to academics, i.e. e.g. the need to support mathematical equations, graphs, citations…

TODO: AFAICT there is not much to choose between the various site generators I mention below as far as the base functions go (taking some text 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 diagrams and so on.

There are many alternatives here. See the About page to see which ones I am (currently) using for this site.


A.k.a. the static site generator. The core bit. The software that takes your plain text files and turns them into friendly websites with all the nice decorations around the edges and indexes and stuff.

There are lots of tools to do this. There are hundreds — maybe thousands — of static site generators, stemming from the primordial (and no longer active) static site generators such as the venerable bloxsom.

Some interesting ones:

  • 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 I erased it from my brain
  • Hugo (go) is a popular system. Its R companion, blogdown, is probably ascendant for academics.
  • Pelican (python), the previous engine for this blog is pretty easy to adapt if you use python.
  • Gatsby (javascript) is one hipster JS one.
  • Eleventy happens to be javascript but claims to be the least obtrustive 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.”
  • Hakyll is a haskell one with good pandoc integration.
  • Neuron (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, which are mentioned below.
  • 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 One can find many more.

Academic blogs have special needs on top of the basic features provided by these, so I review academic options on their own page.

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.

For my part, I used dokuwiki for a while (no longer recommended), then switched to Pelican, and have now settled upon blogdown (i.e. hugo+RMarkdown).


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 here since 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. The overall workflow is developer-centric.

  • RStudio has sophisticated integration with blogdown blogs.

  • NetlifyCMS is Netlify’s generic CMS client for various static site backends offering a friendly, integrated CMS workflow.

  • (USD3/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.

  • cactus, below, features a GUI app too.

  • Hokus is one just for Hugo sites.

  • 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 minature wersion of the website

Online editors

Websites that edit your website for you.

  • forestry seems popular?

  • gitbook is a markdown website GUI and publishing toolchain.

  • classeur attempts to be friendly for more than nerds.

  • 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.”

  • cactus is a plain website generator, that features a GUI-ish client, cactus for mac

  • Draft is another popular frontend with many features of varying usefulness (“ask an editor” function?)

  • Wagtail plus django-bakery is a fancy python/django CMS that can render static sites.

  • gitit:

    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.


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


Here are some hosts I have auditioned to host my main static site, which is this blog.


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


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. This difficulty is that is the whole reason we moved away from them in the first place.

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.

So far, I have been too busy to actually use one though. Thank you to the occasional people who use the web form to send me comments personally.

Here are a few overviews of options.

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.

One can use a hosted option, as in, hosted by someone else. Web annotation tool can be used as 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 Talkyard is optionally-hosted open-source forum software which integrates blog comments as a side effect. Commento is an optionally-hosted open-source comments software. Both these have heavy requirements 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 is a certain kind of simplicity.

Comments as github issues

A small amount of work can repurpose github 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.

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. Trialling now.

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.


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.

No comments yet. Why not leave one?

GitHub-flavored Markdown & a sane subset of HTML is supported.