Gemini-Compatible Markdown

Project Gemini is an application-layer Internet protocol for accessing remote documents — deliberately positioned between Gopher and the web. Its native document format, gemtext (text/gemini), is a line-oriented markup language: nearly a subset of CommonMark, but with hard constraints that matter when one source document must render acceptably as both HTML/Markdown and Gemini. The gemtext specification is maintained at geminiprotocol.net.

The core discipline: one paragraph = one line. Gemini clients treat line breaks literally and wrap text themselves, so hard-wrapped Markdown source produces ragged one-line paragraphs on Gemini. ¹

Formatting subset

Gemtext is line-oriented — all formatting applies to the entire line/block, and there is no inline formatting. Inline Markdown conventions can still be used to the extent the raw text stays readable. ²

• Headings — Only #–### (H1–H3). Gemini explicitly permits multiple H1s per document (headings are pure outlining), but dual-rendered documents should keep one H1 since semantic HTML expects it. Some clients treat the first H1 (if nothing precedes it) as the page header, and a directly following H2 as a sub-header.
• Emphasis / inline code — Not supported. Single *stars* for emphasis and `backticks` for code are well-established conventions that read fine as literal text. Prefer UPPER CASE over **bold**. Markdown-style backslash escapes (\*) render literally in Gemini, so dual-target text must strip them (converters like md2gmn/gmnhg handle this).
• Lists — Unordered only, leader must be *, no indentation/nesting.
• Quotes — > quote lines can’t nest; interior formatting is preserved verbatim, so effectively no lists or code blocks inside quotes.
• Preformatted blocks — ``` fences are supported; the “language” slot is alt text in Gemini. Many Markdown processors (e.g. Jekyll) choke on arbitrary alt text there, so stick to conventional language tags.
• Tables — Not supported; md2gmn converts them into preformatted blocks.

Links and images

Gemtext has no inline links or images. Everything is a link line:

=>[<whitespace>]<URL>[<whitespace><USER-FRIENDLY LINK NAME>]

Converters handle inline Markdown links sensibly only when links appear alone on a line or as unordered-list items, with no other non-link characters. So present links as * [Name](url) lists for clean conversion: ³

This is a sentence.
 
- [necopinus.xyz](https://necopinus.xyz)
- [Cardboard Iguana Security](https://cardboard-iguana.com)
 
An image follows.
 
![This is some image alt-text](../image.webp)

becomes:

This is a sentence.
 
=> https://necopinus.xyz necopinus.xyz
=> https://cardboard-iguana.com Cardboard Iguana Security
 
An image follows.
 
=> ../image.webp This is some image alt-text

Consequence: image alt text should be written as if it were the link text for the image — because in Gemini, that’s exactly what it becomes.

Beyond the page: capsules, subscriptions, e-books

• Subscription convention — Gemini has no RSS/Atom equivalent; instead a companion convention lets clients “subscribe” to a regularly-updated page (like a gemlog index) by parsing its link lines for dated entries (=> /2022/01/30-post.gmi 2022-01-30 Post title). A simple manually-maintained index page works without special markup. ⁴
• The protocol itself — request/response over TLS (TOFU server certificates), a gemini:// URI scheme, and two-digit status codes in six classes: 1x input, 2x success, 3x redirect, 4x temporary failure, 5x permanent failure, 6x client certificate required. Client certificates double as a deliberately ephemeral authentication mechanism — contrast with wallet-based identity in web3-identity. ⁵
• GEMPUB — a ZIP-based e-book container (application/gpub+zip) for gemtext content, also used as a capsule archival format.

Sources

• Gemini hypertext format (gemtext) specification v0.24.1
• Wikipedia — Gemini (protocol)
• 2004 — CommonMark Spec 0.31.2
• 1965 — Gemini subscription companion specification
• Project Gemini specification overview

See also

• uniform-resource-locators — gemtext link lines carry URLs
• day-one-to-obsidian-conversion — another format-conversion workflow with line-oriented quirks

Footnotes

1. Gemini hypertext format (gemtext) specification v0.24.1 ↩

2. Gemini hypertext format (gemtext) specification v0.24.1 ↩

3. Gemini hypertext format (gemtext) specification v0.24.1 ↩

4. 1965 — Gemini subscription companion specification ↩

5. Project Gemini specification overview ↩