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

I've written before about [getting back into Gemini], 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.

getting back into Gemini

Caztor

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.

download the source and binary from GitHub

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.

my Gemini capsule

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

Published 2026-04-27, updated 2026-04-27

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

Categories