markdown.gno
7.44 Kb · 422 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
197Currently, only a short list of content providers are supported:
198
199±±±markdown
200// Gno-related hosts
201"https://gnolang.github.io"
202"https://assets.gnoteam.com"
203"https://sa.gno.services"
204
205// Other providers should respect DMCA guidelines
206// NOTE: Feel free to open a PR to add more providers here :)
207
208// imgur
209"https://imgur.com"
210"https://*.imgur.com"
211
212// GitHub
213"https://*.github.io"
214"https://github.com"
215"https://*.githubusercontent.com"
216
217// IPFS
218"https://ipfs.io"
219"https://cloudflare-ipfs.com"
220±±±
221
222
223## Gno-Specific Features
224
225### HTML Support
226
227By design, most typical HTML support is disabled in Gno's markdown implementation. This is an intentional decision for both security and ecosystem cohesion.
228
229While traditional markdown often allows arbitrary HTML tags, Gno Flavored Markdown takes a more controlled approach:
230
231- We may progressively whitelist certain HTML components or add custom ones over time
232- Our priority is to enhance our flavored markdown to natively support all essential components
233- We aim to eventually support all the initially HTML-supported features, but with syntax that is:
234 - More readable when viewing the source directly
235 - More integrable with custom browsers such as gnobro in CLI
236
237This approach allows for a more consistent rendering experience across different Gno interfaces while maintaining security and readability as core principles.
238
239### Columns
240
241Gno-Flavored Markdown introduces a column layout system that uses special tags. You can create columns with
242±<gno-columns>± blocks and separate the content with ±|||±.
243
244#### Basic Syntax
245±±±markdown
246<gno-columns>
247Left content
248
249|||
250
251Right content
252</gno-columns>
253±±±
254
255- Renders as:
256
257---
258
259<gno-columns>
260Left content
261
262|||
263
264Right content
265</gno-columns>
266
267---
268
269#### Key Features
270
2711. **Multiple Columns**:
272
273Depending on the screen size. A maximum of four rows can be displayed in
274one row.
275
276***Note**: Any overflow will result in items being displayed in the next row. Also, keep in mind that on smaller screens
277(e.g., phones), this overflow may occur with fewer elements.*
278
279±±±markdown
280<gno-columns>
281First column
282
283|||
284
285Second column
286
287|||
288
289Third column
290
291|||
292
293Fourth column
294
295|||
296
297Fifth column
298</gno-columns>
299±±±
300
301- Renders as:
302
303---
304
305<gno-columns>
306First column
307
308|||
309
310Second column
311
312|||
313
314Third column
315
316|||
317
318Fourth column
319
320|||
321
322Fifth column
323</gno-columns>
324
325---
326
3272. **Mixed Content**:
328
329Columns can be mixed with any markdown content
330
331***Note**: Nested columns are currently not possible*
332
333±±±markdown
334<gno-columns>
335### Text Section
336Paragraph with _formatting_
337
338|||
339
340My Image 
341</gno-columns>
342±±±
343
344- Renders as:
345
346---
347
348<gno-columns>
349### Text Section
350Paragraph with _formatting_
351
352|||
353
354My Image 
355</gno-columns>
356
357---
358
359### Usernames
360
361XXX: TODO (add again this feature that was removed)
362
363<!--
364±±±markdown
365@username
366@dev123
367±±±
368
369@username
370@dev123
371-->
372
373### Bech32 Addresses
374
375XXX: TODO
376
377Gno markdown can automatically recognize and render Bech32 addresses.
378
379±±±markdown
380g1jg955hm9a6f0yen878c2hur6q7stqz7rzpyrwpe
381±±±
382
383g1jg955hm9a6f0yen878c2hur6q7stqz7rzpyrwpe
384
385### Smart Contract Integration
386
387XXX: TODO
388
389±±±markdown
390gno.land/r/boards
391gno.land/r/boards:foo/bar
392gno.land/r/docs/markdown$source
393±±±
394
395gno.land/r/boards
396gno.land/r/boards:foo/bar
397gno.land/r/docs/markdown$source
398
399### And more...
400
401XXX: TODO
402
403## Future Enhancements
404
405The markdown support in Gno is being actively developed. Future enhancements may include:
406
407- Extended support for custom components
408- Interactive elements specific to blockchain functions
409- Rich rendering of on-chain data
410- Better integration with Gno's package system
411
412[Read more](https://github.com/gnolang/gno/issues/3255)
413
414## Conclusion
415
416Markdown 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.
417
418As the Gno ecosystem grows, expect the markdown capabilities to expand accordingly, providing even richer formatting and interactive elements for documentation and user interfaces.
419`
420 output = strings.ReplaceAll(output, "±", "`")
421 return output
422}
