now | blog | wiki | recipes | bookmarks | contact | about | donate
* * * back home * * *
document formatting structure for the gemini protocol
On the "regular" internet that you access on your normal browser, such as Firefox or Chromium, everything you do is going to be handled by HTTP. If you have been reading about gemini in the Wiki or somewhere else online, you probably know there are several Gemini clients (browsers for Gemini) and a "language" of its own.
On the "regular internet", webpages are written using HTML. HTML is the document formatting structure that tells your web browser how the page should be rendered. Gemini has its own version of this, a document formatting structure called gemtext. Gemtext is very simple and minimal by design, and you can learn it in just a few short minutes and begin building Gemini capsules all your own with your newfound knowledge. Once you've written up some pages in Gemtext, you can test it out in a Gemini browser and upload it to your capsule if you'd like.
Gemtext, stylistically, is akin to a stripped-down type of Markdown.
If you are familiar with Markdown, you will find yourself adept at Gemtext in just a few minutes.
~ Beginning a Gemtext file
To start a Gemtext file, open up your code editor and begin a new file using the gmi file extension.
vim example.gmi
~ Text
Text is written as it would be in Markdown. Paragraphs are done in lines with no breaks.
We can just write text content without anything special in front of it. Just begin typing!
Every line break is a new paragraph.
~ Headings
Gemtext has three header layers. HTML, by comparison has six.
Top level headings (usually used as titles) are prefixed with a single hashtag ("#").
Second level headings (I use them as subheadings) are prefixed with two hashtags ("##").
Third level headings (I use them as separators within page sections) are prefixed with three hashtags ("###").
# Page Title Text
## second-level subheading
### third-level subheading
~ Links
Links are written using an equal sign followed by a right arrow ("=>"), followed by a URL, and finally followed by your desired link text.
Note that in Gemtext, you can't insert links in-line, so you'll have to place them on their own line.
=> gemini://geminiprotocol.net Gemini Protocol homepage
=> gemini://fossphones.com FOSSphones on Gemini
~ Lists
You can make bulleted lists in Gemini, just as you can in HTML.
In Gemtext, we make lists using an asterisk ("*"), followed by the list item text.
* List item 1
* List item 2
* List item 3
~ Blockquotes
Blockquotes in Gemtext are handled the same way we do it in Markdown.
To create a blockquote, simply prefix your desired quote with a right arrow (">").
> "You've met with a terrible fate, haven't you?" - Happy Mask Salesman
~ Code snippets and preformatted text
Code snippets are able to be done in Gemtext as well. How they are rendered can depend on the Gemini client being used. Amfora, for example, will properly render code snippets and provide supported syntax highlighting.
Code snippets are created using three backticks ("```") followed by the file extension you wish to use.
For example, displaying a Bash snippet would look like this:
```sh
#!/usr/bin/env bash
title="Gemini example script"
echo "$title"; sleep 1
exit
```
You can also use the backticks in order to create standard preformatted text that will show up simply as a monospace font, something that comes in handy for doing things like making ASCII art. Think of it as the Gemtext sibling of the HTML pre tag.
If you want to see some example Gemtext code for how I structure my Gemini capsules, please feel free to take a look at the following links - you'll find the source repos for the Gemini port of this website and the Gemini port of FOSSphones! I am also providing some helpful Gemini resources in the "relevant links" section below.
As you can see, Gemini is very simple and easy to write. Minimal by design and with a focus on getting your ideas across using text only, you might see how creative you can get under these constraints!
Here are a few helpful links so you can dive even deeper into the Gemini protocol if you want to learn more.