Academic blogging workflow

1 Why?

It helps keep me rigorous and coherent, knowing that the public can see what I am doing and which half-cocked opinions I am holding. It encourages people to contact me about my ideas.

Further, having a bunch of plain text files is the most simple, convenient, and reliable way of taking notes. I’d do it this way even if it weren’t going to be online.

This is being mainstreamed, to the point that blogging is part of writers’ advice books such as Nick Higham’s, Handbook of writing for the mathematical science.

2 How

Great. Enough principles, let’s do stuff. Practicalities follow.

There are lots of tools to render academic blogs. There are hundreds of static site generators for plain text blogging. Particular ones of note for academics are…

3 Blogdown, hugodown

See Blogdown et al.

4 distill

If I understand rightly, this framework was extracted from the journal Distill?

• distillpub/post–example: Example Distill article repository—clone, rename, start writing!
• distillpub/template: This is the repository for the distill web framework
• How to Create a Distill Article

5 Living papers

See living papers.

6 fastpages

fastpages, (source) is a jupyter-based solution. So it blogs, not quite plain-text files, but jupyter files.

fastpages is a platform which allows you to create and host a blog for free, with no ads and many useful features, such as:

• Create posts containing code, outputs of code (which can be interactive), formatted text, etc directly from Jupyter Notebooks; for instance see this great example post from Scott Hawley. Notebook posts support features such as:

• Interactive visualizations made with Altair remain interactive.

• Hide or show cell input and output.

• Collapsible code cells that are either open or closed by default.

• Define the Title, Summary and other metadata via special markdown cells

• Ability to add links to Colab and GitHub automatically.

• Create posts, including formatting and images, directly from Microsoft Word documents.

• Create and edit Markdown posts entirely online using GitHub’s built-in markdown editor.

• Embed Twitter cards and YouTube videos.

• Categorization of blog posts by user-supplied tags for discoverability.

Presumably this works best with Python, which jupyter usually requires.

7 Wowchemy

Wowchemy (formerly Hugo academic) is a collection of Hugo extensions targeted at academics. source is often recommended for scholarly types.

USP: can handle both rmarkdown like blogdown and jupyter. Judging by the bug tracker, it is brittler than vanilla Hugo. However, it solves many niggly theming problems at once and has a strong community. Leslie Myint’s introduction gives us the gist of it.

8 Jekyll

The classic static site generator endorsed by GitHub can pump out academic blogs too. FWIW I found it needed too much tweaking out of the box and got bored because I am not a Ruby hacker who enjoys that kind of thing. I’m even less of a go hacker but I still found hugo less trouble because it is designed cleanly not to require any code to make a site go apart from some HTML templates and a config file, which did not seem to hold for Jekyll for me. 🏗

9 Pelican

Pelican is the Python-based one that I used for this site for a long time; works well for academia especially with my custom pandoc reader. I gave it up because it was boring getting rmarkdown integration and blogdown gave me that for free. On the other hand, its code is clean and it is all written in Python, which can lead to some simple and easy-to-maintain code.

Nafiul Islam gives some clever shortcuts on getting live preview using livereload. Michael Toth’s blog documents a clever rmarkdown solution for Pelican that would also work AFAICT with blogdown.

Open source.

10 Hakyll

Hakyll is a Haskell-backed static site generator which boasts most-favoured-nation status with pandoc. (The less prominent yst might fit that bill also.) A highly evolved example of this in full flight is gwern’s blog.

11 pandoc-scholar

Pandoc Scholar (source) extends pandoc with useful academic features. 🏗

In this article we demonstrate the feasibility of writing scientific manuscripts in plain markdown (MD) text files, which can be easily converted into common publication formats, such as PDF, HTML or EPUB, using pandoc. The simple syntax of markdown assures the long-term readability of raw files and the development of software and workflows. We show the implementation of typical elements of scientific manuscripts – formulas, tables, code blocks and citations – and present tools for editing, collaborative writing and version control. We give an example on how to prepare a manuscript with distinct output formats, a DOCX file for submission to a journal, and a LaTeX/PDF version for deposition as a PeerJ preprint.

12 Pollen

Matthew Butterick’s Pollen is a dark horse.

I created Pollen so I could make my web-based books Practical Typography, Typography for Lawyers, and Beautiful Racket. Sure, go take a look. Are they better than the last digital books you encountered? Yes they are. Would you like your next digital book to work like that? If so, keep reading.

At the core of Pollen is an argument:

1. Digital books should be the best books we’ve ever had. So far, they’re not even close.
2. Because digital books are software, an author shouldn’t think of a book as merely data. The book is a program.
3. The way we make digital books better than their predecessors is by exploiting this programmability.

That’s what Pollen is for.

Yes, it supports mathematical markup amongst all the other elaborate typographical features.

13 Punct

• Joel Dueck Dot Com: A lightweight Pollen replacement

I’m working on a Racket #lang called Punct that serves the same purpose as Pollen — a programming environment for published artifacts. Punct combines Markdown and free-form Racket code, producing a format-independent AST.

Why would I do this? I have enjoyed using Pollen very much. But after seven years of improving my Racket skills, my “Pollen projects” have been making less and less actual use of Pollen’s facilities and features. I’ve started to wish for a DSL that has only the pieces I need: something with fewer moving parts and a different approach to markup and rendering.

Punct is supposed to be a good fit for when you want very lightweight markup and for the language to handle paragraph detection and footnotes for you, but you still want the ability to use functions as markup for things Markdown doesn’t provide.

• otherjoel/punct: ⏺✍️ Write in Lisp + Markdown, publish to multiple formats

14 Madoko

Daan Leijen’s Madoko is an even darker horse than Pollen. It includes some nifty publish-to-the-web features, native citation support, and fancy maths rendering. However, it seems quirky, solo, and undermaintained.

I am starting to feel shades of Donald Knuth: The Patron Saint of Yak Shaves.

15 Jupyter

jupyter can render and export markdown as a flagship part of its policy of doing everything easily but nothing well. One would probably use it as a piece of a full site generator.

16 Hexo

Hexo (javascript) (will render equations on the server)

17 b-ber

b-ber (javascript) is an ebook system which happens to generate suave websites as a side effect. 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.

18 Franklin

franklin.jl is a static site generator in julia, for julia purists I suppose. I probably will not use it as I am already committed to multiple languages and purism is dead to me.