💾 Archived View for gemi.dev › gemlog › 2023-01-18-md2gemini.gmi captured on 2024-06-16 at 12:29:44. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

md2gemini and Images

2023-01-18 | #markdown #gemtext | @Acidus

I have a few early Apple history projects where I have ported source content to Markdown, and then I convert that into gemtext:

Apple History and the Creation of the Macintosh

History of the Apple II

Why convert the source to Markdown instead of all the way to gemtext? For these projects, yes I'm taking amazing content that is slowly rotting in the web available to gemini, but I'm also trying to preserve that content in a more portable form. So I need a good canonical "content-at-rest" format for the source material I'm converting. Markdown is this "content-at-rest" format for a several reasons:

Markdown has more nuance for handling different text semantics and hyperlinks, so it does a better job capturing the source content.
It's fairly easy to convert into other formats
There are standard conventions for adding metadata (e.g. front matter)
Markdown has a wide range of tooling and libraries. I'm doing the source material conversion with a mix of automated tooling and manual work. Having a large number of Markdown utilities and libraries I can use helps.
Unlike other formats (like XML) its close enough to what I need that I can work in it by itself.

But once I have the content into Markdown, I still need to convert that into gemtext. To do that I use @makeworld's awesome md2gemini Markdown-to-Gemtext converter.

md2gemini on GitHub

One of the things that makes md2gemini great is its support for different linking modes. Links can be rendered inline or at the end of the paragraph, they can have numbering inside the paragraph or not, etc. However one issue I have is that md2gemini treats images and links the same. I think this is odd.

Image links in Markdown are fundamentally different than hyperlinks. Image links link to content that should be rendered *with* the Markdown document, while a hyperlink is to navigate the reader to another piece of content. A Markdown document without its images loses meaning, whereas a Markdown document without its hyperlinks just loses the ability to navigate to other places. Additionally, image links in Markdown documents are often used as block level elements, instead of inline in a paragraph, which makes their conversion to a gemtext link line straightforward.

Many of my Markdown documents use hyperlinks such as to link back to their original sources. However, when rendering to Gemtext, I don't want these links. But md2gemini treats image lines and hyperlinks the same, so there is no way to say "off" for hyperlinks, but "on" for rendering image links.

While ideally, md2gemini should try image links and hyperlinks completely separately, and allow different render options for both, I had this problem now and needed to solve it. I'm not python developer at all, but looking the source code was simply enough to follow. So I forked md2gemini and implemented an "--links images-only" option, which will not render hyperlinks, but will render images:

md2gemini fork with "images-only" option

I sent a PR back to @makeworld, so hopefully they will use it. I also filed a feature request ticket on GitHub with more details:

My PR implementing an "images-only" option

Feature Request: Allow image links to be treated differently than hyperlinks for --links option

I think this might actually the first time in my life where I've taken an open source code project and added a feature to it! I hope @makeworld accepts the PR, but regardless, I can't see myself using a version of md2gemini without this feature. Thanks to open source, I won't have to!