markdown.gno
8.39 Kb · 434 lines
1package markdown
2
3import "strings"
4
5// this package can be used to test markdown rendering engines.
6
7func Render(path string) string {
8 output := `# Markdown on Gno
9
10## Introduction
11
12Markdown on Gno is based on standard markdown, but also has some unique features, making it the Gno Flavored Markdown. This document describes the current markdown support in Gno, demonstrating both the syntax and its rendered output.
13
14> [!NOTE]
15> Markdown support in Gno is still evolving. New features and improvements will be added in future releases.
16
17## Basic Syntax
18
19### Headings
20
21Headings are created using hash symbols (#). The number of hash symbols indicates the heading level.
22
23±±±markdown
24# Heading 1
25## Heading 2
26### Heading 3
27#### Heading 4
28##### Heading 5
29###### Heading 6
30±±±
31
32# Heading 1
33## Heading 2
34### Heading 3
35#### Heading 4
36##### Heading 5
37###### Heading 6
38
39### Text Formatting
40
41You can format text using the following syntax:
42
43±±±markdown
44**Bold text**
45*Italic text*
46~~Strikethrough text~~
47**Bold and _nested italic_**
48***All bold and italic***
49±±±
50
51**Bold text**
52*Italic text*
53~~Strikethrough text~~
54**Bold and _nested italic_**
55***All bold and italic***
56
57### Links
58
59Links can be created using the following syntax:
60
61±±±markdown
62[Link text](https://example.com)
63[Link with title](https://example.com "Link title")
64±±±
65
66[Link text](https://example.com)
67[Link with title](https://example.com "Link title")
68
69XXX: custom CSS for internal/external links and if possible for "in the same realm/namespace".
70
71### Lists
72
73Unordered lists use asterisks, plus signs, or hyphens:
74
75±±±markdown
76* Item 1
77* Item 2
78 * Nested item 1
79 * Nested item 2
80±±±
81
82* Item 1
83* Item 2
84 * Nested item 1
85 * Nested item 2
86
87Ordered lists use numbers:
88
89±±±markdown
901. First item
912. Second item
92 1. Nested item 1
93 2. Nested item 2
94±±±
95
961. First item
972. Second item
98 1. Nested item 1
99 2. Nested item 2
100
101### Blockquotes
102
103Blockquotes are created using the > character:
104
105±±±markdown
106> This is a blockquote
107>
108> It can span multiple lines
109±±±
110
111> This is a blockquote
112>
113> It can span multiple lines
114
115### Code
116
117Inline code uses single backticks:
118
119±±±markdown
120Use ±func main()± to define the entry point.
121±±±
122
123Use ±func main()± to define the entry point.
124
125Code blocks use triple backticks with an optional language identifier:
126
127<!-- XXX: make the example with 'gno' instead of 'go' -->
128
129±±±markdown
130±±±go
131package main
132
133func main() {
134 println("Hello, Gno!")
135}
136±±±
137
138±±±go
139package main
140
141func main() {
142 println("Hello, Gno!")
143}
144±±±
145
146### Horizontal Rules
147
148Horizontal rules are created using three or more asterisks, hyphens, or underscores:
149
150±±±markdown
151---
152±±±
153
154---
155
156<!-- XXX: add again this feature that was removed -->
157<!--
158### Task Lists
159
160Gno supports task lists for tracking to-do items:
161
162±±±markdown
163- [x] Completed task
164- [ ] Pending task
165±±±
166
167- [x] Completed task
168- [ ] Pending task
169-->
170
171## Tables
172
173Tables are created using pipes and hyphens:
174
175±±±markdown
176| Header 1 | Header 2 |
177| -------- | -------- |
178| Cell 1 | Cell 2 |
179| Cell 3 | Cell 4 |
180±±±
181
182| Header 1 | Header 2 |
183| -------- | -------- |
184| Cell 1 | Cell 2 |
185| Cell 3 | Cell 4 |
186
187## Images
188
189Images can be included using the following syntax:
190
191±±±markdown
192
193±±±
194
195
196
197## Gno-Specific Features
198
199### HTML Support
200
201By design, most typical HTML support is disabled in Gno's markdown implementation. This is an intentional decision for both security and ecosystem cohesion.
202
203While traditional markdown often allows arbitrary HTML tags, Gno Flavored Markdown takes a more controlled approach:
204
205- We may progressively whitelist certain HTML components or add custom ones over time
206- Our priority is to enhance our flavored markdown to natively support all essential components
207- We aim to eventually support all the initially HTML-supported features, but with syntax that is:
208 - More readable when viewing the source directly
209 - More integrable with custom browsers such as gnobro in CLI
210
211This approach allows for a more consistent rendering experience across different Gno interfaces while maintaining security and readability as core principles.
212
213### Columns
214
215Gno Flavored Markdown introduces a column layout system using special HTML-like tags. This system allows content to be organized into multiple vertical columns using heading elements as separators.
216On GnoWeb, up to four columns can be displayed in a single row; exceeding this limit will transfer additional columns to another row, and so on.
217
218#### Basic Syntax
219Wrap your column content in ±<gno-columns>± tags and use standard markdown headings (from h1 ±#± to h6 ±######±) to define column breaks:
220
221±±±markdown
222<gno-columns>
223## Column 1 Title
224
225Column 1 content
226
227## Column 2 Title
228
229Column 2 content
230</gno-columns>
231±±±
232
233This will render as:
234
235<gno-columns>
236## Column 1 Title
237
238Column 1 content
239
240## Column 2 Title
241
242Column 2 content
243</gno-columns>
244---
245
246#### Key Features
247
2481. **Heading Levels**: Any heading level from ±#± (h1) to ±######± (h6) can be used as column separators. The first one will be the reference for subsequent separator.
249
250±±±markdown
251<gno-columns>
252# Main Section
253
254Content
255
256## Subsection
257
258More content
259
260# Second section
261
262Content
263
264## Subsection
265
266More content
267</gno-columns>
268±±±
269
270<gno-columns>
271## Main Section
272Content
273### Subsection
274More content
275## Second section
276Content
277### Subsection
278More content
279</gno-columns>
280
281---
282
2832. **Empty Headings**: Use empty headings to create columns without titles:
284
285±±±markdown
286<gno-columns>
287###
288
289
290Content without title
291
292### Second Column
293
294Another column
295</gno-columns>
296±±±
297
298<gno-columns>
299###
300
301
302Content without title
303
304### Second Column
305
306Another column
307</gno-columns>
308
309
310#### Validation Rules
311
312The column system will ignore invalid structures and generate errors in the form of comments in the following cases:
313
3141. Unclosed Tags
315±±±markdown
316<gno-columns>
317## Title
318Content
319<!-- Missing closing tag -->
320±±±
321
3222. Nested Columns
323
324Nested columns tag will be ignored, e.g.
325
326±±±markdown
327<gno-columns>
328## Parent
329<gno-columns> <!-- this tag will be ignored -->
330 ## Child
331</gno-columns>
332</gno-columns> <!-- this tag will be ignored -->
333±±±
334
3353. Invalid Headings.
336
337Invalid stating heading will generate an error, e.g.
338
339 - Headings in list:
340±±±markdown
341<gno-columns>
342- ## List Heading
343</gno-columns>
344±±±
345
346 - Headings beyond h6:
347±±±markdown
348<gno-columns>
349####### Invalid
350</gno-columns>
351±±±
352
3534. Content Before First Heading
354
355Setting content before first heading, is considered as invalid and will generate an error.
356
357±±±markdown
358<gno-columns>
359Invalid content
360## Title
361</gno-columns>
362±±±
363
364#### Best Pratices
365- Always start column content with a heading
366- Maintain consistent heading levels within a columns block
367- Close tags immediately after final column content
368- Prefer simple markdown structures within columns
369- Use empty headings (##) for image-focused columns
370
371### Usernames
372
373XXX: TODO (add again this feature that was removed)
374
375<!--
376±±±markdown
377@username
378@dev123
379±±±
380
381@username
382@dev123
383-->
384
385### Bech32 Addresses
386
387XXX: TODO
388
389Gno markdown can automatically recognize and render Bech32 addresses.
390
391±±±markdown
392g1jg955hm9a6f0yen878c2hur6q7stqz7rzpyrwpe
393±±±
394
395g1jg955hm9a6f0yen878c2hur6q7stqz7rzpyrwpe
396
397### Smart Contract Integration
398
399XXX: TODO
400
401±±±markdown
402gno.land/r/boards
403gno.land/r/boards:foo/bar
404gno.land/r/docs/markdown$source
405±±±
406
407gno.land/r/boards
408gno.land/r/boards:foo/bar
409gno.land/r/docs/markdown$source
410
411### And more...
412
413XXX: TODO
414
415## Future Enhancements
416
417The markdown support in Gno is being actively developed. Future enhancements may include:
418
419- Extended support for custom components
420- Interactive elements specific to blockchain functions
421- Rich rendering of on-chain data
422- Better integration with Gno's package system
423
424[Read more](https://github.com/gnolang/gno/issues/3255)
425
426## Conclusion
427
428Markdown on Gno provides a familiar syntax for developers who have experience with GitHub Flavored Markdown, while adding blockchain-specific extensions that make it more powerful in the context of the Gno platform.
429
430As the Gno ecosystem grows, expect the markdown capabilities to expand accordingly, providing even richer formatting and interactive elements for documentation and user interfaces.
431`
432 output = strings.ReplaceAll(output, "±", "`")
433 return output
434}
