1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
# Gemtext Compatibility
Gemtext output format support for Hugo is a hack. Since Hugo's theme API does not expose the Markdown parser, the Markdown is rendered into gemtext using regex. The lack of a proper Markdown parser coupled with the limitations of the [Gemini protocol](https://gemini.circumlunar.space/docs/specification.gmi)'s document format gemtext means only a limited subset of Markdown can be converted to gemtext. That subset is documented below. Any Markdown features not explicitly mentioned below should be assumed incompatible.
## Paragraphs
Markdown paragraphs are supported.
Explanation:
Markdown paragraphs map directly onto gemtext text lines. They are left unmodified.
## Blockquotes
Blockquotes are partially supported.
Explanation:
Markdown blockquotes map onto gemtext quote lines. Gemtext only supports flat (non-nested) quote lines that do not contain other elements like lists or headings. For compatibility, use only flat blockquotes containing no other elements.
E.g:
```markdown
> I am a multi-line
> quote for demo purposes.
> I do not contain any
> other elements.
```
## Headings
Markdown headings are partially supported.
Explanation:
Markdown supports 6 headings while gemtext only supports 3. Markdown headings 1-3 \(\#, \#\#, \#\#\#\) map to their respective gemtext heading. Markdown headings 4-6 \(\#\#\#\#, \#\#\#\#\#, \#\#\#\#\#\#\) map to the level 3 \(\#\#\#\) gemtext heading. This flattening is also reflected in the HTML through the CSS styling.
Alternate syntax for Markdown headings including == and -- is not supported. Only number signs \(\#\) may be used.
The goldmark Markdown renderer requires whitespace between the number signs and the heading name whereas the gemtext specification does not. For compatibility, do not use Markdown headings 4-6 and always put a space after the number signs.
## Whitespace
Newlines are partially supported. Line breaks are unsupported.
Explanation:
The gemtext renderer and HTML renderer handle whitespace differently. While whitespace has special meaning in Markdown, the gemtext renderer simply copies it unmodified into the output. It is possible to achieve consecutive newlines in the HTML, but the gemtext won't render it correctly. For compatibility, use exactly two literal newlines except after headings. After headings, just use one newline.
E.g:
```markdown
Do
this
```
```markdown
Don't do
this
```
```markdown
Don't do
this
```
## Emphasis
Bold and italics are partially supported.
Explanation:
Since gemtext does not support bold nor italics, bold and italic text in Markdown map onto gemtext text lines with the asterisks removed. The gemtext renderer only understands asterisks as representing bold or italics, not underscores. For compatibility, use asterisks and write text that doesn't strictly depend on the display of the bold or italics.
E.g:
Markdown input:
```markdown
*I am italic text!*
**I am bold text!**
***I am bold and italic text!***
_I am italic text!_
__I am bold text!__
___I am bold and italic text!___
```
Gemtext output:
```gemtext
I am italic text!
I am bold text!
I am bold and italic text!
_I am italic text!_
__I am bold text!__
___I am bold and italic text!___
```
## Lists
Unordered lists are partially supported. Ordered lists are unsupported.
Explanation:
Since gemtext does not support ordered lists, ordered lists in Markdown map onto text lines in Gemini.
Unordered list items in Markdown map onto unordered list items in gemtext. Gemtext does not support adding elements in lists nor nested lists. Dashes \(\-\), asterisks \(\*\), and plus signs \(\+\) can all be used to represent line items. For compatibility, use only flat lists containing no other elements.
E.g:
```
* this is
* a list
- this is
- a list
+ this is
+ a list
```
## Preformatted Text
Preformatted text is partially supported.
Explanation:
Preformatted text in Markdown maps to preformatting toggle lines and preformatted text lines in gemtext. Gemtext only supports using 3 backticks to represent preformatting toggle lines. For best compatibility, always use exactly 3 backticks.
E.g:
````
```plaintext
I love Gemini!
```
````
## Links
Links are partially supported.
Explanation:
Links in Markdown map to link lines in gemtext. The gemtext renderer does not recognize angle bracketed URLs nor reference-style links. It only recognizes links that have link text enclosed in brackets \(e.g. \[Arch Linux\]\), immediately followed by the URL in parenthesis \(e.g. \(archlinux.org\)\).
```markdown
[Arch Linux](https://archlinux.org)
```
Gemtext does not support inline links. To circumvent this limitation, the default behavior is to create link references and append them to the bottom of the blog post.
E.g:
Markdown input:
```markdown
Do you like the [Arch Linux](https://archlinux.org) distro?
What about the [Gentoo](https://www.gentoo.org/) distro?
```
Gemtext output:
```gemtext
Do you like the Arch Linux[1] distro?
What about the Gentoo[2] distro?
=> https://archlinux.org 🔗 1: Arch Linux
=> https://www.gentoo.org 🔗 2: Gentoo
```
To disable the link references at the bottom, set "makerefs" to false in the frontmatter. This changes the behavior of the gemtext renderer so that it only renders non-inline Markdown links.
E.g:
Markdown input with "makerefs" set to false:
```markdown
[Arch Linux](https://archlinux.org)
any text before [Arch Linux](https://archlinux.org) or after
```
Gemtext output:
```gemtext
=> https://archlinux.org 🔗 Arch Linux
any text before [Arch Linux](https://archlinux.org) or after
```
Inline images in Markdown can be added by putting an exclamation mark immediately before the link brackets. Gemtext does not support inline images, so they are rendered as normal links. They only show up inline in the HTML.
E.g:
Markdown input:
```markdown
```
Gemtext output:
```gemtext
Cute cat photo[1]
=> cat.png 🔗 1: Cute cat photo
```
If a Markdown link has a title and the "makerefs" variable is set to true (the default), the link reference at the bottom of the page uses the link title instead of the link text.
E.g:
Markdown input:
```markdown
Do you like the [Arch Linux](https://archlinux.org "Arch") distro?
```
Gemtext output:
```gemtext
Do you like the Arch Linux[1] distro?
=> https://archlinux.org 🔗 1: Arch
```
For compatibility, only use links with brackets and parenthesis. Always URL encode links. Do not use inline links with the "makerefs" page variable disabled.
|
