Plain-text blogging

You would like to write a blog or whatever, which is a bunch of notebooks on your hard disk which gets rendered to a normal web page on a server somewhere. You would like to not have to spend energy on maintaining some bit of fancy software.

Companion piece to academic writing workflow, wherein I will mention plain text blogging choices, but I do not worry so much about certain fiddly detaisl which are important mostly to academics, i.e. lifestyle choices available free from the additional fiddly constraints of academia, e.g. 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 accetable on the internet).

There are some advanced features which would be more distinguishing, and which I have not handled especially well.

  1. Good graphical preview in an editor.
  2. Intuitive handling of images and graphics and such.

Rendering engine

A.k.a. the static site generator. The core bit. The software that takes your plain text files and turns them into friendly websites.

There are lots of tools to do this. There are hundreds or maybe thousands of static site generators.

The top few in my community seem to be

  • Jekyll (ruby) which is the default for github, although I personally could never make it work for me.
  • Hugo (go) is a popular system.
  • b-ber (javascript) is an ebook system which happens to make very suave websites while it is at it. It has a “prosumer” feel, and a designerly motivation where they want to target e-readers as well. >b-ber is both a method and an application for producing publications in a variety of formats—EPUB 3, Mobi/KF8, static website, PDF, and XML file, which can be imported into InDesign for print layouts—from a single source that consists of plain-text files and other assets. b-ber also functions as a browser-based EPUB reader, which explains the name.
  • Pelican (python)
  • Gatsby (javascript)
  • Metalsmith (javascript) is a clean-lookin’ plugin-based one.
  • There are some extra ones, below, that integrate into specialised editor apps, a.k.a. CMSs, which are mentioned below.

One can find many more.

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.

I use Pelican.

As to why I chose Pelican over Jekyll: I am more fluent in Python than Ruby, and those were the two prominent options at the time.

Due to the unpredictable tides of hype, Hugo might be the most popular move now.

Gatsby, which I have been recommended frequently also, also fancy with so many features I cannot track them, although it is oriented towards my academic needs.

Hugo tips

Caddy has a builtin automatic hugo editor.

There is an academic derivative of hugo called Blogdown which might be of interest to the general population, since it includes msuch luxires as such as preview rendering using the rstudio editor. See the blogdown-book for more on that.

Some themes have been tested against blogdown.

Site hosting choice

Ultimately the content still has to be visible online, so I need to get a web-host.

  • github incidentally hosts sites as part of their github pages thing.
  • netlify is a hosting/CDN/etc provider with good github integration that one might use instead, with especially fancy gatsby integration

Editors

Local editors

If your static site system comes with some kind of app that will edit that site it is called a CMS - content management system. There is a blurry relationship between that and an editor with integrated static site generator capabilities. Also there there is no sharp distinction between online (internetty) and offline (on my laptop) editors. Sometimes the local CMS can run on the internet. There are many options that veer to various combinations of these things.

If you use markdown, which is the de facto standard markup for plain text blogging it might be a good strt to simply preview that in the old text 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.

Markdown preview extended turns atom or vs code into good markdown editors, including mathematical equations.

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.
  • blot.im (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…
  • … inspired by Notational Velocity – specifically the reboot nvALT which has its own noteworthy features (high tech search)
  • 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?)
  • 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.

Comment systems

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 use the hosted Disqus system but it is bloated and suspect, so I seek alternatives.

Here are a few overviews of options.

Hypothes.is

One can use a hosted option, as in, hosted by someone else. Web annotation tool hypothes.is 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. However it only supports the Chrome browser.

Self-hosted comment server

One could host a server running its own comment system. Schnack is a simple node.js nice 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 on the other hand that might be easier.

Bake comments into the version control

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. Similarly, staticman is an (optionally) hosted (open source) app that integrates comments into your source. There is also a hot Go option called remark42.