Replacing sblg with lowdown and script

Replacing sblg with lowdown and script


I’ve moved my blog off sblg and have replaced it with a script named make.sh and lowdown.

Motivations

I’ve been interested in gemini※ for a long time now. Previous iterations of my site have been accessible over Gopher and Telnet. At one point the site was exclusively non-HTTP(s). Gemini, I think, is a capable replacement for these protocols. After finding out the creator of sblg, the tool I was previously using to build my blog, had created another tool for text transformation and supported the text/gemini spec, I decided to move.

※ gemini://gemini.circumlunar.space/docs/specification.gmi

XHTML -> text/markdown

XHTML doesn’t at all look like text/markdown, and even less like text/gemini. But we can ease some of the pain by doing three things.

  1. Don’t have a lot of articles.
  2. Use pandoc to convert the XHTML to text/markdown.
  3. Use lowdown to convert the resulting text/markdown to text/gemini.

There’s a missing step in between 2 and 3, where the markdown is manually cleaned up. This xhtml conversion only has to be done once, and new articles are written in the clean markdown. Cleaning the markdown isn’t always necessary, and you may find the output of step 2 acceptable.

A standard for markdown is ephemeral and fleeting, but thankfully whatever standard lowdown supports is metadata-capable, as documented in lowdown’s manpage. In this instance, I just added the metdata by hand, rather than figuring out how to properly carry it over in the pandoc converstion process. Metdata that can be parsed by lowdown is as such:

title: Replacing sblg with lowdown and script
author: PM
css: style.css
date: 2020-12-19

text/markdown -> text/html and text/gemini

lowdown handles conversion to UTF-8 HTML5 well enough, and supports a css metadata key to include a stylesheet. Individual markdown files (articles) are converted and served as-is. The index page is a bit different. As articles are added to the site, the contents of the index needs to change.

Rather than use a rigorously-tested system, I instead wrote a shell script that enumerates “20*.md”, and creates an index.md markdown file. This markdown file is created from scratch each time, and titles, subtitles, and preface are simple echo arguments. Originally reverse-sorting by date was achieved with “tail -r”, but GNU tail apparently doesn’t do that, so “tac” is now used in its place.

lowdown also handles conversion to UTF-8 text/gemini. The only meaningful difference is that sed is used to remove the markdown metadata, as those keys currently end up in the resulting file. An index.gmi is generated in much the same way as index.html, with the list of articles generated by reversing their filesystem order.

Deployment

The script also handles deployment, but I intend to talk about infrastructure some other post. The summary is that it calls scp to my nginx host and gmnisrv host, and puts the files in the right place.