Announcing md2gem 0.1 – a cross-platform, best-effort converter for Markdown to Gemini Gemtext

I’ve written before about getting back into publishing using the Gemini protocol, despite its limitations. One of my concerns is, and always has been, the lack of expressiveness of the “Gemtext” document format. Gemini isn’t limited to Gemtext, although a Gemini client has to support it, to claim to be in any way compliant with the specification. There’s a certain amount of interest in publishing using Markdown, although it’s fair to say that not all Gemini enthusiasts endorse the idea, and some are vehemently opposed. Still, with an increasing number of clients supporting Markdown, – including my own Caztor browser – it seemed reasonable to me to offer my ramblings in this format as well as Gemtext. I don’t expect to stop blathering in Gemtext – the Markdown is an, um…, bonus.

So the question arises whether to use Gemtext or Markdown as the primary source. That seems a no-brainer to me: although it’s trivially easy to convert Gemtext to Markdown, doing this would offer none of the advantages of Markdown. I favour Markdown because it offers features (like in-line links and formatting) that Gemtext does not.

So I’ve started work on a Markdown-to-Gemtext converter, that tries to make the best job it can of representing a Markdown original in Gemtext format. Converters or this kind already exist but I wanted features that, so far as I know, no other converter has. In particular, I want to be able to turn Markdown tables into Gemtext. This can only be done in Gemini by laying out the table using pre-formatted text blocks with a fixed-pitch font, and drawing the table borders using Unicode box-drawing characters. It’s far from ideal, but it’s better than nothing, and md2gem does it automatically.

I’ve written md2gem in Java for two reasons:

• it will work the same on almost any platform, and
• I can use the excellent commonmark-java parser to interpret the Markdown.

Unfortunately, but unsurprisingly, commonmark-java has built-in converters only for HTML and plain text, so the implementation was significantly more complicated than I thought it would be. Still, it seems to work reasonably well for only a couple of evenings’ hacking.

If you want to try md2gem yourself, you can download the source and binary from GitHub. It’s a command-line tool, so you’ll need a little familiarity with this way of working, and a Java JVM. md2gem isn’t fussy, though, and it should work with any JVM released in the last twenty years.

Usage is simple enough:

java -jar md2gem.jar [source_markdown_file] [target_gemtext_file]

although there are various command-line options to modify the output.

The indexes and feeds in my Gemini capsule will remain in Gemtext format, but each Gemtext page from April onwards will now have a link to the Markdown original. That may be a little different from the Gemtext, or perhaps a lot different, depending on the content. Of course, to read the Markdown you’ll need a Gemini browser with Markdown support or, at least, some other Markdown reader.

I’m open to bug reports and suggestions for improvement, although md2gem is already adequate for my modest purposes.