💾 Archived View for mozz.us › markdown › design_document.txt captured on 2020-10-31 at 01:15:00.

View Raw

More Information

⬅️ Previous capture (2020-09-24)

-=-=-=-=-=-=-

             GEMINI MARKDOWN PROPOSAL             

This document uses a experimental markdown format
that was designed to extend the text/gemini
mimetype. The design goals for this format are:

• Simple enough to write and read as plain text
• Simple enough to be easily parsed, with
  unambiguous line-based syntax
• Expressive enough to compose markdown style
  documents
• Easy to understand for those familiar with
  writing in markdown

This format combines several syntax ideas that
have been proposed by other people in the mailing
list and elsewhere. I do not claim creative
ownership over any of this, I am just too lazy to
properly cite where everything came from.

OVERVIEW

> # Title
> ## Heading
> ### Sub-Heading

> =>Link

> * Unordered list

> + Ordered list

> --- Horizontal rule

> Text blocks surrounded by ``` contain pre-
formatted lines.

PARAGRAPHS

Paragraphs are blocks of text that do not start
with any other reserved "tokens". Any whitespace
at the beginning and end of lines within a
paragraph will be normalized to a single <SPACE>.
This allows paragraphs to be easily re-flowed to
fit the client's screen.

Two or more consecutive newlines will start a new
paragraph. If a line contains only whitespace
characters, it will be considered equivalent to a
newline.

Inline styles like *italic* and **bold** are NOT
supported. They would be nice to have, but they
making parsing much more difficult and result in
too many ambiguities and edge cases.

HEADINGS

Three levels of headings are supported.



                 THIS IS A TITLE                  

THIS IS A HEADING

This is a sub-heading

Headings are denoted by the hash character
followed by a single whitespace. A heading is
restricted to a single line, but you can make it
as long as you want if you are willing to spill
over 80 characters. You can only use between 1-3
hash characters for headings, because supporting
arbitrary heading levels is difficult to parse.

LINKS

Links keep the pre-existing gemini format:

[0] /path

[1] An alternate description

[2] Full URLs are also supported

If you are a writing a gemini client for the
terminal, you can get away with parsing only the
link lines in a file and displaying everything
else as plain text. The markdown elements are
designed to gracefully degrade.

HORIZONTAL RULES

Horizontal rules are lines that start with three
"---".

──────────────────────────────────────────────────

These have the same syntax meaning as the <hr> tag
in HTML. The text after the first three characters
is not significant. You could choose to pad the
line out to 80 characters to look better for plain
text displays.

LISTS

Unordered

Unordered (bullet) lists are consecutive lines
that start with the "*" character.

• This is an unordered list
• Single items are not allowed to wrap to multiple
  lines
• Nested lists are not supported because they are
  difficult to parse

Ordered

Ordered lists behave the same, except they use the
"+" character instead of a asterisk. Using a
single character is much easier to parse than
trying to detect consecutive integers like "1.)",
"2.)", etc. The client can render the ordered list
however they feel is appropriate, for example by
using a <ol> in HTML.

1. This is an ordered list
2. Second element
3. Third element

PREFORMATTED TEXT

A preformatted text block starts and ends with a
line containing only the "```" characters. You can
use preformatted blocks for ASCII art, code
snippets, or anything else that requires monospace
font or significant whitespace.

> def greet(name):
>     print("Hello " + name)

>            /\
>           p  q
>       _\| \  / |/_
>         \//  \\/
>          `|  |`
>           |  | ,/_
>       _\, |  |//\
>        /\\|  ;/
>          \;  \
>   jgs      '. \
>       .-.    \ |
>      `   '.__//
>            `"`

> # Other tokens like headings are ignored inside
of pre-formatted blocks.

PARSING

I was able to write a syntax parser for this
format in about 50 lines of python. I have never
written a markdown parser before, and my code is
very naive. I did not need to use recursion or any
other advanced constructs. The only state that I
had to keep was whether or not a preformatted text
block was currently active.

This document leaves some ambiguities as to how
whitespaces are handled. The parser implementation
should be considered the canonical truth for the
proposed markdown specification.