-- Leo's gemini proxy
-- Connecting to git.thebackupbox.net:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini
repo: gemini-site action: commit revision: path_from: revision_from: f49a9edfe67c485079d8d992276790d84e711d25: path_to: revision_to:
commit f49a9edfe67c485079d8d992276790d84e711d25
Author: Solderpunk <solderpunk@sdf.org>
Date: Thu Jul 2 15:58:25 2020 +0000
Add introductory Gemtext material.
diff --git a/docs/cheatsheet.gmi b/docs/cheatsheet.gmi
new file mode 100644
index 0000000000000000000000000000000000000000..1faea20f4d0084994823ec716343c033b313e734
--- /dev/null
+++ b/docs/cheatsheet.gmi
@@ -0,0 +1,34 @@
+# Gemtext cheatsheet
+
+Here's the basics of how text works in Gemtext:
+
+* Long lines get wrapped by the client to fit the screen
+* Short lines *don't* get joined together
+* Write paragraphs as single long lines
+* Blank lines are rendered verbatim
+
+You get three levels of heading:
+
+```
+# Heading
+
+## Sub-heading
+
+### Sub-subheading
+```
+
+You get one kind of list and you can't nest them:
+
+```
+* Mercury
+* Gemini
+* Apollo
+```
+
+Here's a quote from Maciej Cegłowski:
+
+```
+> I contend that text-based websites should not exceed in size the major works of Russian literature.
+```
+
+Lines which start with ``` will cause clients to toggle in and out of ordinary rendering mode and preformatted mode. In preformatted mode, Gemtext syntax is ignored so links etc. will not be rendered, and text will appear in a monospace font.
diff --git a/docs/gemtext.gmi b/docs/gemtext.gmi
new file mode 100644
index 0000000000000000000000000000000000000000..d13681aedd3437ce0d92dede30d9e12b1a25f8a8
--- /dev/null
+++ b/docs/gemtext.gmi
@@ -0,0 +1,98 @@
+# 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:
+
+=> cheetsheet.gmi 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.
diff --git a/docs/index.gmi b/docs/index.gmi
new file mode 100644
index 0000000000000000000000000000000000000000..cbf115d7e0fa8a567929fc42cfee4051155bf460
--- /dev/null
+++ b/docs/index.gmi
@@ -0,0 +1,12 @@
+# Gemini protocol documentation
+
+## Core documents
+
+=> faq.gmi Project Gemini FAQ
+=> specification.gmi Protocol specification
+=> best-practices.gmi Best practices for Gemini implementers
+
+## Resources for beginners
+
+=> gemtext.gmi A quick introduction to "gemtext" markup
+=> cheatsheet.gmi Gemtext cheatsheet
-----END OF PAGE-----
-- Response ended
-- Page fetched on Sun Jun 2 14:43:26 2024