👴 jdcard

Reading Gemtext

There are several good guides to help people write in the gemtext format. Here is a brief guide to reading gemtext documents.

The programs that display nicely-formatted gemtext documents work by reading only the first two or three characters at the beginning of each line of text. In this document I will insert a blank space at the beginning of lines that demonstrate gemtext markup as a way to show you what the markup looks like (in case you happen to read this file in a gemtext browser).

Gemtext is written as one long line of text for each paragraph. Programs that are designed to display gemtext automatically force any text that is too long to fit in your window onto the next line. If you're reading gemtext in a text editor you can achieve the same effect in many editors by enabling their "word wrap" or "soft wrap" features.


Headings are used in a document to show where different sections of the document begin.

Heading Types

Many word processor programs provide an option to insert different types of headings into documents you write. Gemtext provides three types of headings. These are similar to what you might see in HTML code as <h1>, <h2>, and <h3> level headings.

#   Level 1 Heading -- many documents have only one Level 1 heading, at the 
                       very top of the document, that serves as a title.
##  Level 2 Heading -- these are often used to indicate the various major 
                       sections of the document.
### Level 3 Heading -- indicates a subsection of a larger portion the document.

Reading Headings

When you encounter a line that begins with one or more "#" characters you know that this line introduces a new section of the document. More "#" characters indicate lesser levels of importance, or greater levels of detail, within the document.


Another feature seen in word processing software is the creation of bulleted lists. Gemtext supports one type of list. It is what HTML designates as <ul>, or an unordered list. Lines that begin with the "*" character are list items.

List Examples

* An asterisk at the beginning of a line denotes a list item.
* Gemtext client sofware will generally replace the asterisk with a dot or 
  other marker, wrap list items that have long text, and may adjust margins 
  to make list items like this one more readable.
* List items are not automatically numbered.
* 1. This is one way you might see a "numbered list" presented.
* 2. These numbers are inserted by the author manually.
* 4. They are not generated automatically -- that's why you see a break in 
     the number sequence here, as a demonstration.
* 5. Nevertheless you may see gemtext authors use list items in this way.


A line that begins with "=>" indicates a reference to another document. The text that immediately follows the "=>" marker is the "address" of the document being referenced. After the (often long and hard to read) "address" is often a blank space followed by a plain text description of the document being referenced. If you're reading a gemtext document without the aid of gemtext software, you may have to copy the "address" information into a browser or file manager to manually retrieve the referenced document.

Link Examples

=> GemText.gmi A brief guide for Gemtext authors.

This link points to another document (Gemtext.gmi) in the same location as the current document.

=> blog/hello-tildeverse.gmi One of my early blog posts

This link points to a document in the "blog" subdirectory relative to where this current file is located.

=> https://wagingnonviolence.org/ The Waging Nonviolence website

This link points to a web resource totally separate from the current document.

=> ../img/JDCARDlicense.jpg

Links may point to non-document resources. Also note that a link does not have to have any description following the resource address. This is another link relative to the current document: go up one directory and look in the "img" folder to find the "JDCARDlicense.jpg" file.


A ">" character at the beginning of a line indicates that text in that line is a quoted passage from another source.

Quoted Text Examples

> "The cure for boredom is curiousity. There is no cure for curiousity." -- Ellen Parr

Here is a longer quotation (two paragraphs), followed immediately by a link to the source document.

> "Burning fossil fuels warms the planet, which harms others. It's that simple. 
> Although the processes involved are distributed globally, accrue over decades, 
> and are statistical in nature -- and therefore difficult for our brains to 
> connect directly back to our individual actions -- the harm is nonetheless real.
> "Burning fossil fuels should be unacceptable socially, the way physical assault 
> is unacceptable. The harm it does is less immediate, but just as real. We need 
> to start speaking this truth -- burning fossil fuels harms others -- so that 
> society can begin realizing it." -- Peter Kalmus
=> https://peterkalmus.net/books/read-by-chapter-being-the-change/ [Peter Kalmus in "Being The Change"]

Preformatted Text

When a line begins with the "```" sequence it indicates that what follows -- until you come to another line starting with "```" -- is text that should be read using a mono-spaced font so that all the characters line up properly with one another. The "```" sequence is often followed by a brief explanation of what the preformatted section represents. The three most common uses for this are in presenting tables of data, computer source code, or ASCII art.


 ``` Table: Number of incidents per month
│     Month      │ Count │
│ September 2020 │ 8     │
│ October 2020   │ 4     │
│ November 2020  │ 1     │
│ December 2020  │ 2     │
│ January 2021   │ 1     │
│ February 2021  │ 2     │
│ March 2021     │ 0     │
│ April 2021     │ 1     │
│ May 2021       │ 4     │
│ June 2021      │ 4     │
│ July 2021      │ 5     │
│ August 2021    │ 1     │
│ September 2021 │ 7     │
│ October 2021   │ 2     │
│ November 2021  │ 2     │

Programming Code

 ``` Code: My first BASIC program: HELLO.BAS
10 REM HELLO.BAS - print a message to the output device
20 PRINT "Hello world."
30 END


 ``` ASCII art: cat and bunny
  |\_/|        ****************************    (\_/)
 / @ @ \       *  "Purrrfectly pleasant"  *   (='.'=)
( > º < )      *       Poppy Prinz        *   (")_(")
 `>>x<<´       *   (pprinzexample.com)    *
 /  O  \       ****************************



Although it is less than ideal, it is quite possible to read gemtext documents without a browser or other specialized software.

©2022 🅭🅯🄏🄎 Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)

🌐 jdcard.tilde.team

Search this site at marginalia.nu