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. 1
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. 2
- 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: 3
This is a sentence.
- [necopinus.xyz](https://necopinus.xyz)
- [Cardboard Iguana Security](https://cardboard-iguana.com)
An image follows.
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-textConsequence: 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. 4 - 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. 5 - 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)
- CommonMark Spec 0.31.2
- 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