Gemtext Compatibility Reference Guide
This reference guide documents the compatibility of Markdown features with gemtext as an output format of this Hugo theme. It should be assumed that any Markdown features not documented below are unsupported.
The reference guide format is as follows:
## <Feature Name>
<Markdown input> => <gemtext output>
Support level: <full, partial, or unsupported>
[Other relevant information]
[Examples]
Nesting
nested element => unchanged
Support level: unsupported
Nesting support is not factored into other features' support levels.
Escape Characters
literal backslash + character => unchanged
Support level: unsupported
Escape character support is not factored into other features' support levels.
Paragraphs
paragraph => text line
Support level: full
E.g:
Markdown input:
I will become a text line in the gemtext output.
Gemtext output:
I will become a text line in the gemtext output.
Blockquotes
blockquote => quote line
Support level: full
E.g:
Markdown input:
> I will become quote lines
> in the gemtext output.
Gemtext output:
> I will become quote lines
> in the gemtext output.
Headings
heading => (flattened) heading
Support level: partial
Number signs, equal signs, and dashes can delimit headings. Markdown heading levels greater than level 3 are flattened to level 3 in the gemtext output. The use of heading levels greater than level 3 is strongly discouraged.
E.g:
Markdown input:
===
I will become a level 1 heading in the gemtext output
---------
I will become a level 2 heading in the gemtext output
### I will become a level 3 heading in the gemtext output
#### I will become a level 3 heading in the gemtext output
##### I will become a level 3 heading in the gemtext output
###### I will become a level 3 heading in the gemtext output
Gemtext output:
# I will become a level 1 heading in the gemtext output
## I will become a level 2 heading in the gemtext output
### I will become a level 3 heading in the gemtext output
### I will become a level 3 heading in the gemtext output
### I will become a level 3 heading in the gemtext output
### I will become a level 3 heading in the gemtext output
Emphasis (Italic)
emphasis (italic) => text with italic delimiters removed
Support level: partial
Asterisks delimiting italicized text are removed from the gemtext output. Using italics with other supported Markdown features can cause unexpected behavior.
E.g:
Markdown input:
I will become *italicized* in the HTML output.
*##* I will become a level 2 heading in the gemtext output but not in the HTML output
Gemtext output:
I will become italicized in the HTML output.
## I will become a level 2 heading in the gemtext output but not in the HTML output
Emphasis (Bold)
emphasis (bold) => text with bold delimiters removed
Support level: partial
Asterisks delimiting bolded text are removed from the gemtext output. Using bolding with other supported Markdown features can cause unexpected behavior.
E.g:
Markdown input:
I will become **bolded** in the HTML output.
**##** I will become a level 2 heading in the gemtext output but not in the HTML output
Gemtext output:
I will become bolded in the HTML output.
## I will become a level 2 heading in the gemtext output but not in the HTML output
Emphasis (Bold and Italic)
emphasis (bold and italic) => text with bold and italic delimiters removed
Support level: partial
Asterisks delimiting bolded and italicized text are removed from the gemtext output. Using bolding and italics with other supported Markdown features can cause unexpected behavior.
E.g:
Markdown input:
I will become ***bolded and italicized*** in the HTML output.
***##*** I will become a level 2 heading in the gemtext output but not in the HTML output
Gemtext output:
I will become bolded and italicized in the HTML output.
## I will become a level 2 heading in the gemtext output but not in the HTML output
Unordered Lists
unordered list item => unordered list item
Support level: full
Dashes (-), asterisks (*), and plus signs (+) can delimit unordered list items.
E.g:
Markdown input:
* I will become unordered list #1 item #1 in the gemtext output
* I will become unordered list #1 item #2 in the gemtext output
- I will become unordered list #2 item #1 in the gemtext output
- I will become unordered list #2 item #2 in the gemtext output
+ I will become unordered list #3 item #1 in the gemtext output
+ I will become unordered list #3 item #2 in the gemtext output
Gemtext output:
* I will become unordered list #1 item #1 in the gemtext output
* I will become unordered list #1 item #2 in the gemtext output
* I will become unordered list #2 item #1 in the gemtext output
* I will become unordered list #2 item #2 in the gemtext output
* I will become unordered list #3 item #1 in the gemtext output
* I will become unordered list #3 item #2 in the gemtext output
Ordered Lists
ordered list item => unordered list line
Support level: partial
Numbers can delimit unordered list lines.
E.g:
Markdown input:
1. I will become an unordered list line in the gemtext output
2. I will also become an unordered list line in the gemtext output
Gemtext output:
* I will become an unordered list line in the gemtext output
* I will also become an unordered list line in the gemtext output
Preformatted Text
preformatted text => preformatting toggle lines + preformatted text lines
Support level: partial
Only 3 consecutive backticks can delimit preformatted text. Text following the leading "```" on the same line is permitted.
E.g:
Markdown input:
```markdown
[this link](https://example.com) will not be rendered in the HTML nor in the gemtext output.
```
Gemtext output:
```markdown
[this link](https://example.com) will not be rendered in the HTML nor in the gemtext output.
```
Links
link => superscripted reference numbers + link lines
Support level: partial
Hypertext references must be URL-encoded. Angle bracketed URLs, Markdown reference-style links, and linking to heading IDs are unsupported.
If the "makerefs" variable in the frontmatter is set to true (the default), text enclosed in brackets (e.g. [Arch Linux]) immediately followed by a URL in parenthesis (e.g. (https://archlinux.org)) and an optional link title ("Arch Linux") becomes a reference-style link with a corresponding link line appended to the bottom of the page in the gemtext output. If there is a link title in the Markdown, it becomes the link name in the gemtext.
E.g:
Markdown input:
[Debian](https://www.debian.org) is a good OS, but I prefer [arch](https://archlinux.org "Arch Linux").
Gemtext output:
Debian¹ is a good OS, but I prefer arch².
## References
=> https://www.debian.org 🔗 [1]: Debian
=> https://archlinux.org 🔗 [2]: Arch Linux
If the "makerefs" variable in the frontmatter is set to false, reference-style links are not created and only links that occupy the entire line become link lines in the gemtext output.
E.g:
Markdown input:
---
<mandatory frontmatter>
makerefs: false
---
[Puppy Linux](https://puppylinux-woof-ce.github.io "a lightweight linux distro")
Gemtext output:
=> https://puppylinux-woof-ce.github.io Puppy Linux
Inline Images
inline image => link line
Support level: partial
Links with a preceding exclamation mark are treated the same as normal links in the gemtext output.
E.g:
Markdown input:
---
<mandatory frontmatter>
makerefs: false
---
Check out my dog:
Gemtext output:
Check out my dog:
=> pics/dogs/spot.jpeg Spot
Whitespace
whitespace => literal whitespace
Support level: partial
Whitespace in the Markdown input is copied verbatim into the gemtext output. For maximum compatibility, it is advised to use 2 literal newlines after each element except before headings. Headings require 3 preceding literal newlines except at the start of the document.
E.g:
Markdown input:
I will become a text line
## I will become a level 2 heading
* I will become unordered list item #1
* I will become unordered list item #2
> I will become
> quote lines
Gemtext output:
I will become a text line
## I will become a level 2 heading
* I will become unordered list item #1
* I will become unordered list item #2
> I will become
> quote lines