markdown.gno
12.28 Kb · 621 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### Forms
360
361Gno-Flavored Markdown introduces a secure form system that integrates directly with realms. The system uses custom HTML-like tags that are rendered with proper styling and validation.
362
363#### Basic Usage
364
365Create a form using the ±<gno-form>± tag and add inputs with ±<gno-input>±:
366
367±±±markdown
368<gno-form>
369 <gno-input name="name" placeholder="Enter your name" />
370 <gno-input name="email" placeholder="Enter your email" />
371</gno-form>
372±±±
373
374<gno-form>
375 <gno-input name="name" placeholder="Enter your name" />
376 <gno-input name="email" placeholder="Enter your email" />
377</gno-form>
378
379#### Form Structure
380
3811. **Form Container**
382 - Must start with ±<gno-form>± and end with ±</gno-form>±
383 - Optional attributes:
384 - ±path±: Render path after form submission (e.g. ±path="user"± will redirect to ±:user?[params]±)
385 - Form data is always sent as query parameters
386 - Cannot be nested (forms inside forms are not allowed)
387 - Automatically includes a header showing the realm name
388
3892. **Input Fields**
390 - Created with ±<gno-input>± tag
391 - Required attributes:
392 - ±name±: Unique identifier for the input (required)
393 - ±type±: Type of input (optional, defaults to "text")
394 - ±placeholder±: Hint text shown in the input (optional, defaults to "Enter value")
395 - Supported input types:
396 - ±type="text"± (default): For text input
397 - ±type="number"±: For numeric values only (with browser validation)
398 - ±type="email"±: For email addresses (with basic browser validation)
399 - ±type="tel"±: For phone numbers (no specific validation)
400 - ±type="password"±: For password input (masked characters)
401 - Note: Input validation is handled by the browser's HTML5 validation
402 - Any other type will default to "text"
403 - Each input must have a unique name
404 - Inputs are rendered with labels and proper styling
405
406#### Example Use Cases
407
4081. Form with Path and Query Parameters
409±±±markdown
410<gno-form path="user">
411 <gno-input name="username" type="text" placeholder="Enter username" />
412 <gno-input name="age" type="number" placeholder="Your age" />
413</gno-form>
414±±±
415
416<gno-form path="user">
417 <gno-input name="username" type="text" placeholder="Enter username" />
418 <gno-input name="age" type="number" placeholder="Your age" />
419</gno-form>
420
421This form will submit to ±:user?username=value&age=value± on the same realm.
422
4232. Form with Query Parameters Only
424±±±markdown
425<gno-form>
426 <gno-input name="recipient" type="text" placeholder="Enter recipient address" />
427 <gno-input name="email" type="email" placeholder="Your email" />
428 <gno-input name="pswd" type="password" placeholder="Your password" />
429</gno-form>
430±±±
431
432<gno-form>
433 <gno-input name="recipient" type="text" placeholder="Enter recipient address" />
434 <gno-input name="email" type="email" placeholder="Your email" />
435 <gno-input name="pswd" type="password" placeholder="Your password" />
436</gno-form>
437
438This form will submit to ±?recipient=value&email=value&pswd=value± on the same realm.
439
440#### Important Rules
441
4421. **Validation Rules**:
443 - Every ±<gno-input>± must have a ±name± attribute
444 - Duplicate attribute names are not allowed
445 - Forms must be properly closed
446 - Nested forms will not render
447
4482. **Security Features**:
449 - Forms are processed on the realm where they are defined
450 - Each form submission is associated with its realm
451 - The realm name is displayed in the form header
452 - Input validation is handled by the realm's smart contract
453
454---
455
456### Alerts
457
458Alerts are a way to highlight important information in your markdown.
459
460There are five types of alerts:
461
462- INFO
463- NOTE
464- TIP
465- SUCCESS
466- WARNING
467- CAUTION
468
469**NOTE**: The default alert type is INFO (if a wrong alert type is used).
470
471The alert boxes are expandable/collapsible and can have a title.
472By default, the alert boxes are opened. The title is optional and if not provided, the alert type will be used as the title.
473
474±±±markdown
475> [!NOTE]
476> This is a note
477±±±
478
479> [!NOTE]
480> This is a note
481
482±±±markdown
483> [!NOTE]-
484> This is a closed note
485±±±
486
487> [!NOTE]-
488> This is a closed note
489
490±±±markdown
491> [!NOTE] This is a note with title
492> This is a note with title
493±±±
494
495> [!NOTE] This is a note with title
496> This is a note with title
497
498±±±markdown
499> [!INFO]
500> This is an info
501±±±
502
503> [!INFO]
504> This is an info
505
506±±±markdown
507> [!TIP]
508> This is a tip
509±±±
510
511> [!TIP]
512> This is a tip
513
514±±±
515> [!SUCCESS]
516> This is a success
517±±±
518
519> [!SUCCESS]
520> This is a success
521
522±±±
523> [!WARNING]
524> This is a warning
525±±±
526
527> [!WARNING]
528> This is a warning
529
530±±±
531> [!CAUTION]
532> This is a caution
533±±±
534
535> [!CAUTION]
536> This is a caution
537
538±±±markdown
539> [!FOO]
540> The default alert if a wrong alert type is used
541±±±
542
543> [!FOO]
544> This is the default alert
545
546±±±markdown
547> [!NOTE]
548> This is a note
549> > [!NOTE]
550> > This is a scoped note
551±±±
552
553> [!NOTE]
554> This is a note
555> > [!NOTE]
556> > This is a scoped note
557
558### Usernames
559
560XXX: TODO (add again this feature that was removed)
561
562<!--
563±±±markdown
564@username
565@dev123
566±±±
567
568@username
569@dev123
570-->
571
572### Bech32 Addresses
573
574XXX: TODO
575
576Gno markdown can automatically recognize and render Bech32 addresses.
577
578±±±markdown
579g1jg955hm9a6f0yen878c2hur6q7stqz7rzpyrwpe
580±±±
581
582g1jg955hm9a6f0yen878c2hur6q7stqz7rzpyrwpe
583
584### Smart Contract Integration
585
586XXX: TODO
587
588±±±markdown
589gno.land/r/boards
590gno.land/r/boards:foo/bar
591gno.land/r/docs/markdown$source
592±±±
593
594gno.land/r/boards
595gno.land/r/boards:foo/bar
596gno.land/r/docs/markdown$source
597
598### And more...
599
600XXX: TODO
601
602## Future Enhancements
603
604The markdown support in Gno is being actively developed. Future enhancements may include:
605
606- Extended support for custom components
607- Interactive elements specific to blockchain functions
608- Rich rendering of on-chain data
609- Better integration with Gno's package system
610
611[Read more](https://github.com/gnolang/gno/issues/3255)
612
613## Conclusion
614
615Markdown 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.
616
617As the Gno ecosystem grows, expect the markdown capabilities to expand accordingly, providing even richer formatting and interactive elements for documentation and user interfaces.
618`
619 output = strings.ReplaceAll(output, "±", "`")
620 return output
621}
