On Gopher map formats by Christopher Williams 2026-06-30 When I started this Gopher site over a year ago (has it really been that long?) I had aspirations to use AsciiDoc to generate all of my site’s static content, for both plain text files and gophermaps. But why AsciiDoc and not the more popular Markdown? Simply put, AsciiDoc is much more powerful than Markdown and doesn’t require embedded HTML for missing features: sidebars, admonitions, block titles, nested blocks, file includes, attributes, description lists, custom CSS classes, etc. It syntax is also much more consistent. Early on I wrote an Asciidoctor text converter which converts an AsciiDoc document to plain text, with wrapped text, styled headings, and so on. I use AsciiDoc for my phlog posts (including this one) and for many other text files, so in that regard I succeeded. I also use it for gophermaps (in the geomyidae format—I like it better than the more common gophermap format for a few reasons). ------------------------------------------------------------ Using Gemtext ------------------------------------------------------------ However, as I’ve spent time in Gemini and working on my site more, I found that many of AsciiDoc’s features aren’t really needed for a basic smolnet site like mine. For example, nested blocks, cross references, bibliographies, etc., aren’t very useful. I found that Gemtext is sufficient for most purposes. I recently added Gemtext support to my site to automatically convert .gmi files to Gopher menus. I even converted my home page to a slightly extended version of Gemtext; previously I used geomyidae’s gophermap format, but I find Gemtext’s link lines easier to read and write. I have to make a couple minor concessions or compromises when using Gemtext on a Gopher site. The first is in telling the Gemtext-to-Gopher converter the type of a relative link in a `=>` line. In Gemini this is a non-issue, as it (like HTTP) specifies a resource’s content type in its response header rather than in its locator. With Gopher, I have to rely on convention: a link ending in a slash is a directory (type 1), .txt is a text file (type 0), .bin is a binary file (type 9), etc. This means that any resource on my site that is referenced by a relative link in a Gemtext file must follow convention, which really isn’t a big deal. ---------------------------------------------------- A note from 2026-07-01 Gopher servers often rely on convention too, especially when generating directory listings. Most Gopher servers map file extensions to item types, just as my Gemtext-to-Gopher converter does. ---------------------------------------------------- That still leaves the issue of relative links to “search” items. A Gopher client relies on the item type (type 7) to know that a link takes user input, but there’s no way to explicitly specify this in a Gemtext link line (short of using a Gopher URL). I used Spartan’s solution, which uses a modified version of Gemtext: use `=:` rather than `=>` for query links. With my converter, a link on a `=:` line is converted to a type 7 item. The second concession is compromising on block styles. Gemtext supports only two block types: quote blocks and code blocks. But I find sidebar and admonition blocks to be quite useful sometimes. And verse blocks, which are similar to quote blocks but preserve indentation and line breaks, are nice for poetry and such. For the most part these various block types can be represented in Gemtext with a little help from Unicode—a pointing finger for a sidebar or an exclamation point/bomb/whatever for an admonition, for example. But when writing Gemtext directly, all of that must be done manually, which can be tedious and error prone and is a reason I like using AsciiDoc. It would nice, then, to support more block types in the markup itself and have them automatically rendered to text in whatever style I want. The format would be a sort of middle ground between Gemtext and a more common lightweight markup language. (There’s been countless discussions and proposals about extending Gemtext; this is my own personal bikeshedding.) ------------------------------------------------------------ Extending Gemtext ------------------------------------------------------------ First of all, I want to maintain Gemtext’s simplicity as a line-based format. I want an extended format to remain easy to parse, so no inline formatting for you. Inline formatting doesn’t exactly work in Gopher either, so it’s rather pointless. Gemtext uses “fenced” code/literal blocks, which means text inside a block is surrounded by lines of three backticks (```); the opening line optionally has descriptive text following the backticks. New block types will follow this syntax for simplicity and consistency. What block types do I want? * Sidebar * Admonition * Thematic break (technically this is a standalone line type, not a block delimiter) That’s it for now (I can add more later). # Extended Gemtext syntax Here’s what I have so far: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Paragraph text before a sidebar. *** This is a sidebar block. *** A thematic break: ''' Paragraph text after the thematic break. ---NOTE This is an admonition block. The opening delimiter is followed by the admonition type. --- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - As in AsciiDoc, the admonition type can be one of NOTE, TIP, IMPORTANT, CAUTION, or WARNING (though this isn’t set in stone or anything). # Rendering extended Gemtext The above markup might be rendered to something like this (using styles from my Asciidoctor text converter): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Paragraph text before a sidebar. ------------------------------------------------ This is a sidebar block. ------------------------------------------------ A thematic break: * * * Paragraph text after the thematic break. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- NOTE : This is an admonition block. : : The opening delimiter is followed by the : admonition type. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ That’s pretty much it. What do you think?