Pushing Gemini

Gemini has an intentionally limiting feature set. It can feel as if it's not possible to do certain things. I believe that's merely a consequence of being new. There's been a lot of time to figure out how to solve problems in HTML, and there's many resources and tools for overcoming them already made.

With time, Gemini users will have developed their own ways of working around these challenges. This page is me experimenting new ways of tackling those. I hope by sharing it will help others as well.

What We Have To Work With

Gemtext is simple UTF-8 encoded text with a few additional markup features. Features Gemtext does support are:


The nature of this would seem to favor programming content more than other types of content, due to specifically having support for code blocks, which is non-standard in a lot of writing. Although, it does not support advanced features such as code highlighting, and can also be used for ASCII art.

People are an expressive bunch though, and they will always wish to push the boundaries of what is possible.


Instead of trying to extend the feature set of Gemtext, I believe a better solution is instead to stop thinking of Gemtext as the medium.

Instead, think of Gemtext as merely a glue which binds the actual content together. It's meant to be simple so it is consistent. It's just featureful enough to comfortably provide outlining utilities which can be used to organize content.

In a way, I think this could possibly be more freeing. You're free to use any tools you wish to craft your content. You can use more specialized tools which are better at performing the job you want, and the reader can use their own preferred tools to view it.

Flounder.online unfortunately only supports uploading a very small group of file types. You will need external hosting for this, making this option less appealing. If you are self hosting, this should not be an issue.

Until I can find a hosting site, most of the example files linked below will be broken.


One of the first things people have been doing to personalize their home page is add banners using ASCII art inside codeblocks. Some find this garish, but personally I feel it does not disrupt the flow if used in moderation.

The big advantage of using codeblocks over doing something like linking to an image is that the codeblock loads with the rest of the page. An image would require an additional request, which the user must initiate manually.

Rich Text

As someone with a writing background, I'm a bit disappointed in Gemini lacking most basic typography features. The way it's designed seems to favor text based content, but it is not actually that well supported by Gemtext.

I believe this is an intentional design feature. It would be ๐˜ฏ๐˜ช๐˜ค๐˜ฆ if we could simply apply some basic formatting to Gemtext. In particular, I would like to have ๐—ฏ๐—ผ๐—น๐—ฑ and ๐˜ช๐˜ต๐˜ข๐˜ญ๐˜ช๐˜ค๐˜ด (and ๐™—๐™ค๐™ฉ๐™ ๐™ฉ๐™ค๐™œ๐™š๐™ฉ๐™๐™š๐™ง). However, doing this would require in-line formatting, which would break Gemini's rule about having one element per line.

In the paragraph above I'm forcing bold and italics using UTF-8's set of preformatted text.



This is not a good solution because it is fragile. We have to choose in advance if the text is ๐’”๐’†๐’“๐’Š๐’‡, ๐™จ๐™–๐™ฃ๐™จ ๐™จ๐™š๐™ง๐™ž๐™›, ๐“ฌ๐“พ๐“ป๐“ผ๐“ฒ๐“ฟ๐“ฎ/๐“ผ๐“ฌ๐“ป๐“ฒ๐“น๐“ฝ, ๐•ค๐•ฅ๐•–๐•Ÿ๐•”๐•š๐• (๐••๐• ๐•ฆ๐•“๐•๐•– ๐•ค๐•ฅ๐•ฃ๐•ฆ๐•”๐•œ), or ๐–Œ๐–”๐–™๐–๐–Ž๐–ˆ (๐”ฃ๐”ฏ๐”ž๐” ๐”จ๐”ฑ๐”ฒ๐”ฏ), which could be mismatched with what the user's client has set. The font that the reader is using could be missing these characters, since they are not as standard (though I'd argue a good Gemini client should include full support of Gemini features, such as all of UTF-8).

This is why it's a better solution to provide formatting markers which the client can then render as appropriate. If we specify italics, it will use that font's version of italics. If it doesn't have it, it can gracefully fall back to having no special formatting.

If we want guaranteed consistent and advanced formatting, we should use another file format. If for example we wish to publish the chapter of an ongoing novel, we could format it as a PDF or epub file, and link to it as we would any other post. The user's client will download it and they can read it using their computer's native reader. You could even serve standard HTML this way.

Formats you could use:

Examples, using Grimm's Fairy Tales - Rapunzel:

Grimm's Fairy Tales - Rapunzel (pdf)

Grimm's Fairy Tales - Rapunzel (epub)

Grimm's Fairy Tales - Rapunzel (odt)

Grimm's Fairy Tales - Rapunzel (html)

Grimm's Fairy Tales - Rapunzel (txt)

Text was sourced from Project Gutenberg.


The downside is that changing between the browser and the reader could be considered a disruptive experience. It will be up to Gemini browsers how they handle this. Some already display images inline for example. They could add similar features for other formats. However, the more that are added, the more the client will be bloated.

I personally think it is a better experience using a purpose built reading tool than it is using an embedded one. I think I would prefer my client download a temp file and then open it in my reader directly.

Preformatted Gemtext

As shown above, using UTF-8 to it's fullest potential is one way of extending the reach of what Gemtext can do, though with its shortcomings.

It would be tempting to invent a Gemtext+ format, a superset of Gemtext, which would allow us to add our own hinting which then transpiles to standard UTF-8 encoded Gemtext. This would make it easier to write content in this style. It's not extending the features of Gemtext because UTF-8 is already supported.

๐—จ๐—ฃ๐——๐—”๐—ง๐—˜ (๐Ÿฎ๐Ÿฌ๐Ÿฎ๐Ÿฎ-๐Ÿฌ๐Ÿฑ-๐Ÿฏ๐Ÿญ):

There exist Markdown to Gemtext converters. Using Markdown as the superset of Gemtext is likely a smarter way to go, since the Markdown content will be easier to mirror to an HTML source. Though I still think a purpose built language could better suited to handle Gemini's choices.

๐—บ๐—ฑ๐Ÿฎ๐—ด๐—ฒ๐—บ๐—ถ๐—ป๐—ถ seems to currently be the most popular option. It supports converting tables into ASCII code blocks, and will convert links in a couple ways. I think the default way of faking inline links looks awkward to read, and much prefer the enumerated list at the end of a paragraph.

md2gemini repository

๐—ด๐—ฒ๐—บ๐—ฑ๐—ผ๐˜„๐—ป is another converter, but is in a fairly early state.

gemdown repository

I do not see any converters that take advantage of bold/italics, so these will still need to be added manually to your text.


Tables have been an often requested feature to be added.

This can be done by using UTF-8 box drawing characters inside a codeblock.




          โ•‘ Flavors                    โ•‘
          โ• โ•โ•โ•โ•โ•โ•โ•โ•ฆโ•โ•โ•โ•โ•โ•โ•โ•ฆโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•ฃ
          โ•‘ Apple โ•‘ Grape โ•‘ Strawberry โ•‘
โ•‘ P โ•‘ USD โ•‘ $2.99 โ•‘ $2.39 โ•‘ $3.29      โ•‘
โ•‘ r โ•‘     โ•‘       โ•‘       โ•‘            โ•‘
โ•‘ i โ• โ•โ•โ•โ•โ•โ•ฌโ•โ•โ•โ•โ•โ•โ•โ•ฌโ•โ•โ•โ•โ•โ•โ•โ•ฌโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•ฃ
โ•‘ c โ•‘ CAD โ•‘ $3.08 โ•‘ $2.44 โ•‘ $3.56      โ•‘
โ•‘ e โ•‘     โ•‘       โ•‘       โ•‘            โ•‘

A more decorated table:

         โ•Ž Apple โ•Ž Grape โ•Ž Strawberry โ•Ž
 P โ•Ž USD โ”‚ $2.99 โ”‚ $2.39 โ”ƒ $3.29      โ”ƒ
 r โ•Ž     โ”‚       โ”‚       โ”ƒ            โ”ƒ
 i โ”œโ•ดโ•ดโ•ดโ•ดโ•ดโ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ•„โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”ฉ
 c โ•Ž CAD โ”‚ $3.08 โ”‚ $2.44 โ”‚ $3.56      โ”‚
 e โ•Ž     โ”‚       โ”‚       โ”‚            โ”‚

Mathematical Notation

Mathematical notation has been and continues to be a difficult challenge for computers. It sometimes feels as if characters could simply float wherever they please around a formula. Smart people have been working on this though and have come up with some different solutions.

As with rich text, it would be better to use one of those purpose built solutions. Decide if you want the entire article formatted, or only the formulas. If the whole article is included in a single file, then you can use any existing solutions.

UTF-8 does support some basic mathematical symbols, but it is not enough for composing formulas. You can try using these for inline formatting, though I'd highly advise against it because they do not often display well. If you need inline math formatting, use a different format.

If you want to include formulas with Gemtext, I'd suggest choosing a writing style which explains the formula, then include an image of it, along with a source file for the reader to build it themselves.

Since you will most likely be working with plain black and white text, I suggest formatting your images using a limited color space and as aggressive of a lossy compression as you can get before it is noticeable. In the example below, I used the following command for Imagemagick, which gave a file almost half the size of the default.

convert binomial_coefficient.png -quality 50 -set colorspace Gray -separate -average binomial_coefficient.jpg


(text source: Wikipedia)

In mathematics, the binomial coefficients are the positive integers that occur as coefficients in the binomial theorem. Commonly, a binomial coefficient is indexed by a pair of integers n โ‰ฅ k โ‰ฅ 0 and is written with n above k (shown in the left side of the formula). It is the coefficient of the xแต term in the polynomial expansion of the binomial power (1 + x)โฟ, and is given by the formula:

Binomial coefficient (jpg)

Binomial coefficient (LaTeX)


Gemini does not enforce any type of "correctness" when formatting links. This is my own suggestion for providing a nice experience.

When linking to a file of a different format, include its file type in parenthesis at the end of the name. An unlabeled link may skip this type-hinting if it can be inferred from a visible file extension. This gives the reader an idea what to expect when they follow the link.

The label should be either descriptive or the filename. If you reference to it in the body text, the naming should match or at least be closely identifiable.

Always include at least 1 space after the arrow. Some clients may not format correctly otherwise.


=> image.jpg Image (jpg)
=> article.pdf Article (pdf)
=> tux.sh


=> image.jpg Image
=> article.pdf (pdf)
=> tux