2020-11-11: Replacing Macdown in OpenBSD                                     xkp
================================================================================

On Macs I use Macdown for notes and small documents. On Windows I use
MarkdownPad 2. There isn't really an equivalent on OpenBSD, so I thought I'd
make one. Markdown is far from perfect but it's what I use and it works for me. 
Thankfully OpenBSD has an excellent native vi implementation and neovim package.

The things I need to do with Markdown are:

* Occasionally generate HTML
* Occasionally generate PDFs

Normally I use Pandoc in the absence of MacDown but there's no OpenBSD package
and underneath it's a little bit of dependency hell. I've used Roman
Zolotarev's[1] excellent SSG before, and while looking into extending it with
Gopher and Gemini support had a bit of an epiphany.

For those that don't know, SSG is an extremely lightweight site generator tool,
like Hugo that uses Markdown. Unlike Hugo it's designed for base OpenBSD with
the only dependency being the lowdown package. With pandoc, I tend to prefer
using HTML5 as an intermediary step over latex as it preserves the look of links
more effectively.That route uses wkhtmltopdf which is also available as an
OpenBSD package.

Installing lowdown and wkhtmltopdf on OpenBSD is as simple as:

	$ doas pkg_add lowdown wkhtmltopdf

We need a Markdown file to test. Macdown is open source, but needs a bunch of
MacOS stuff to build it. As I'm only interested in the assets I downloaded the
latest release[2] and ripped them from there.

For non-Mac users, help.md can be found beneath the zip under
MacDown.app/Contents/Resources/help.md

Lets start by turning that into HTML with lowdown. The simplest way to run this
is:

	$ lowdown -s -o help.html help.md 

The results mostly work but look... ugly.

We can specify a CSS file in the top of our markdown using metadata, e.g.:

	css: Styles/Github2.css

This would apply the Styles/Github2.css file, and it does look better but
ideally we don't want to have to modify documents to specify CSS. We'll come
back to this later.

Now we have a HTML file with stylesheet, lets make a PDF using wkhtmltopdf. We
can pass our output directly to Zathura and as long as the CSS is reachable,
wkhtmltopdf will generate a PDF of the page.

	$ lowdown -s help.md | wkhtmltopdf -s A4 - help.pdf

For some reason when piped, wkhtmltopdf ignores the stylesheet. If on the other
hand I write lowdown to a file, then run wkhtmltopdf separately the stylesheet
is picked up.

	$ lowdown -s help.md -o help.html
	$ wkhtmltopdf -s A4 help.html help.pdf

I haven't really had time to look into why.

Putting this all together, I've created a script that:

1. Takes a markdown file
2. Runs it through lowdown to generate a HTML version of the file
3. Generates a PDF version with wkhtmltopdf

It's called SDG, as it borrows a lot from Roman's SSG. I'm not quite ready to
release it yet but when it's ready I'll put it up either here, on sourcehut or
both as I'm no longer using Github. The main advantage is that SDG lets you
specify a stylesheet instead of having to add it to the metadata. 

If the PDF version is open in Zathura it'll automatically refresh on change. You
can also preview in a terminal using this:

	$ lowdown -Tterm help.md | less -R

This just runs lowdown to generate raw terminal output which is passed to less
in raw mode.

[1] - https://www.romanzolotarev.com/ssg.html
[2] - http://macdown.uranusjr.com/download/latest/