# A quick introduction to "gemtext" markup
The most common way to serve textual content over Gemini is not just plain text
like on Gopher, but using a lightweight markup language called "Gemtext" (which
is served with the unofficial MIME type text/gemini). This document is a quick
introduction to that markup language. It has some superficial resemblences to
Markdown, which will make it easy to learn if you know MD, but it's quite
different in other ways.
Once you've read this document, you might like to occasionally refresh your
memory by refering to the:
DIR Gemtext cheatsheet
## Text
Text in Gemtext documents is written using "long lines", i.e. you (or your
editor) shouldn't be inserting newline characters every 80 characters or so.
Instead, leave it up to the receiving Gemini client to wrap your lines to fit
the device's screen size and the user's preference. This way Gemtext content
looks good and is easy to read on desktop monitors, laptop screens, tablets and
smartphones.
Note that while Gemini clients will break up lines of text which are longer than
the user's screen, they will not join up lines which are shorter than the user's
screen, like would happen in Markdown, HTML or LaTeX. This means that, e.g. "dot
point" lists or poems with deliberately short lines will be displayed correctly
without the author having to do any extra work or the client having to be any
smarter in order to recognise and handle that kind of content corectly.
For most "everyday" writing, this approach means you probably just want to use
one line per paragraph.
Note that blank lines are rendered verbatim by clients verbatim, i.e. if you put
two or three blank lines between your paragraphs, the reader will see two or
three blank lines.
## Links
Like Gopher (and unlike Markdown or HTML), Gemtext only lets you put links to
other documents on a line of their own. You can't make a single word in the
middle of a sentence into a link. This takes a little getting used to, but it
means that links are extremely easy to find, and clients can style them
differently (e.g. to make it clear which protocol they use, or to display the
domain name to help users decide whether they want to follow them or not)
without interfering with the readability of your actual textual content.
Link lines look like this:
```
=> https://example.com A cool website
=> gopher://example.com An even cooler gopherhole
=> gemini://example.com A supremely cool Gemini capsule
=> sftp://example.com
```
That is:
* They start with the two characters =>,
* followed by optional whitespace (spaces or tabs, as many or as few as you like),
* followed by a URL (any protocol you like).
* They can end right there if you like, as per the sftp example above!
* Or they can be followed by at least one space or tab,
* And then a human-friendly label, which can be as long as you like
In the above example, all the URLs and labels lined up nicely because the author
was pedantic. But Gemini doesn't care, and this is fine too:
```
=>https://example.com A cool website
=>gopher://example.com An even cooler gopherhole
=> gemini://example.com A supremely cool Gemini capsule
=> sftp://example.com
```
## Headings
Gemtext supports three levels of headings. Headings are limited to a single line
and start with either one, two or three # symbols followed by one mandatory
space character:
```
# Heading
## Sub-heading
### Sub-sub-heading
```
This is the only supported heading syntax. Underlining your headings using - or
= symbols like in Markdown will not do anything.
It is strictly optional for clients to do anything special at all with headings.
Many clients will recognise them and use a larger font or a different colour or
some other kind of styling, but some will not and will just treat them as
ordinary text lines and print them as is. This is fine, because headings are not
supposed to be used to control the appearance of your content. Rather, they
supply important semantic information on the structure of your content. Some
clients will use headings to automatically generate a table of contents for
their user, which can be useful for navigating large documents. Software for
generating Atom or RSS feeds might use headings to automatically detect the
titles for gemlog posts.
## Lists
Gemtext supports unordered lists. Each item in a list is written as a single
long line, which begins with a single * symbol followed by one mandatory space
character:
```
* Mercury
* Gemini
* Apollo
```
This is the only supported list syntax. Using - instead of * like in Markdown
will not do anything. Nested lists are not supported.
It is strictly optional for clients to do anything special at all with list
items, and some clients will treat them just like any other line of text. The
only reason they are defined is so that more advanced clients can replace the
* with a nicer looking bullet symbol and so when list items which are too long
to fit on the device screen get broken across multiple lines, the lines after
the first one can be offset from the margin by the same amount of space as the
bullet symbol. It's just a typographic nicety.
## Blockquotes
Gemtext supports blockquotes. The quoted content is written as a single long
line, which begins with a single > character:
```
> Gemtext supports blockquotes. The quoted content is written as a single long
line, which begins with a single > character
```
It is strictly optional for clients to do anything special at all with
blockquotes, and some clients will treat them just like any other line of text.
As per list items, they are defined strictly to allow for more pleasant
typography in ambitious clients.
## Preformatted text
Gemtext is carefully designed to be very, very easy to parse and render. Gemini
clients process Gemtext one line at a time, rendering each line independently of
any lines before it or after it, just by peeking at the first few characters of
a line to check for something like =>, # , * , etc.
A line which starts with ``` (i.e. with three backticks) tells the client to
toggle between its ordinary parsing mode, and "preformatted mode". In
preformatted mode, clients don't check whether or not a line is a link or a
heading or anything else. They are simply printed as-is. Also, while clients may
use variable width fonts for ordinary all other text, in preformatted mode
clients must use a fixed width font. Thus, a pair of ``` lines acts much like
<pre> and </pre> tags in HTML.
Preformatted text can be used to include ASCII art, source code, or similar
content in a Gemtext document without clients mistakenly interpreting lines as
headings, list items, etc. It can also be used to write documents like this one,
which explain Gemtext syntax with examples - you're able to see the syntax
examples above without your client interpreting them like it normally would
because they are rendered in preformatted mode.
Anything which comes after the ``` characters of a line which toggles
preformatted line *on* (i.e. the first, third, fifth, etc. toggling lines in a
document) may be treated as "alt text" for the preformatted content. In general
you should not count on this content being visible to the user but, for example,
search engines may index it and screen readers may read it to users to help the
user decide whether the preformatted content should be read aloud (which e.g.
ASCII art generally should not be, but which source code perhaps should be).
There are currently no established conventions on how alt text should be
formatted.