gmi2md

gmi2md is a command-line utility and PHP library for converting gemtext to Markdown.

Requirements

• PHP 8.0 or later to run gmi2md
• diff(1) and just to test it
• pretty-php and just to format the code

Usage

CLI

./gmi2md.php < tests/input.gmi

PHP

The following code is also in example.php.

<?php

include 'gmi2md.php';

$converter = new GemtextToMarkdownConverter();
echo $converter->convert(file_get_contents('tests/input.gmi'));

Design

gmi2md translates gemtext to a subset of Markdown that is compatible with major Markdown variants: CommonMark, GFM, Pandoc, and John Gruber's original Markdown. It preserves vertical whitespace.

In gemtext, if one line follows another, the lines are separate paragraphs; in Markdown, the lines are merged into a single paragraph. gmi2md separates gemtext paragraphs with a blank line to make them paragraphs in Markdown.

I have made a stylistic decision to merge links into one Markdown paragraph in the output when they directly follow each other in the gemtext input. What this mean is that we do not insert blank lines between links to make them different paragraphs. Rather, each line with a link after a paragraph or after the first link of the group when there is no preceding paragraph is prefixed with <br> in the Markdown output.

The gemtext in the first of the following code blocks is translated to the Markdown in the second:

Lorem ipsum.
=> https://example.com/1
=> gemini://example.com/2

Lorem ipsum.
<br><https://example.com/>
<br>[gemini://example.com/2](gemini://example.com/2)

Gemtext where the links are separated with newlines is translated differently:

Lorem ipsum.

=> https://example.com/1

=> gemini://example.com/2

Lorem ipsum.

<https://example.com/>

[gemini://example.com/2](gemini://example.com/2)

To change this behavior, instantiate the converter with a separator prefix other than the default <br>. For example:

// No link grouping. Insert blank lines.
$converter = new GemtextToMarkdownConverter("\n");

Development

gmi2md was written by Claude 3.5 Sonnet for the initial commit, fixed and improved in various ways by a human, and refactored by Claude. It was a first for me. I have written about its development.

License

Copyright law is not yet clear about generated code. This code is a combination of machine and human contributions. One may expect that the code will be considered an original and copyrightable work. I am therefore releasing it under the MIT License. See LICENSE. I am not a lawyer. Use code that is partially generated by AI at your own risk.