markdown.gno
20.97 Kb · 813 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
69### Lists
70
71Unordered lists use asterisks, plus signs, or hyphens:
72
73±±±markdown
74* Item 1
75* Item 2
76 * Nested item 1
77 * Nested item 2
78±±±
79
80* Item 1
81* Item 2
82 * Nested item 1
83 * Nested item 2
84
85Ordered lists use numbers:
86
87±±±markdown
881. First item
892. Second item
90 1. Nested item 1
91 2. Nested item 2
92±±±
93
941. First item
952. Second item
96 1. Nested item 1
97 2. Nested item 2
98
99### Blockquotes
100
101Blockquotes are created using the > character:
102
103±±±markdown
104> This is a blockquote
105>
106> It can span multiple lines
107±±±
108
109> This is a blockquote
110>
111> It can span multiple lines
112
113### Code
114
115Inline code uses single backticks:
116
117±±±markdown
118Use ±func main()± to define the entry point.
119±±±
120
121Use ±func main()± to define the entry point.
122
123Code blocks use triple backticks with an optional language identifier:
124
125<!-- XXX: make the example with 'gno' instead of 'go' -->
126
127±±±markdown
128±±±go
129package main
130
131func main() {
132 println("Hello, Gno!")
133}
134±±±
135
136±±±go
137package main
138
139func main() {
140 println("Hello, Gno!")
141}
142±±±
143
144### Horizontal Rules
145
146Horizontal rules are created using three or more asterisks, hyphens, or underscores:
147
148±±±markdown
149---
150±±±
151
152---
153
154### Task Lists
155
156Gno supports task lists for tracking to-do items:
157
158±±±markdown
159- [x] Completed task
160- [ ] Pending task
161- [ ] Another pending task
162- [x] Another completed task
163±±±
164
165- [x] Completed task
166- [ ] Pending task
167- [ ] Another pending task
168- [x] Another completed task
169
170### Footnotes
171
172Gno supports footnotes for adding references and citations:
173
174±±±markdown
175Here is a sentence with a footnote[^1].
176
177[^1]: This is the footnote content.
178±±±
179
180Here is a sentence with a footnote[^1].
181
182[^1]: This is the footnote content.
183
184You can also use multiple footnotes in the same document:
185
186±±±markdown
187This is the first sentence with a footnote[^1].
188This is another sentence with a different footnote[^2].
189
190[^1]: First footnote content.
191[^2]: Second footnote content with more details.
192±±±
193
194This is the first sentence with a footnote[^1].
195This is another sentence with a different footnote[^2].
196
197[^1]: First footnote content.
198[^2]: Second footnote content with more details.
199
200## Tables
201
202Tables are created using pipes and hyphens:
203
204±±±markdown
205| Header 1 | Header 2 |
206| -------- | -------- |
207| Cell 1 | Cell 2 |
208| Cell 3 | Cell 4 |
209±±±
210
211| Header 1 | Header 2 |
212| -------- | -------- |
213| Cell 1 | Cell 2 |
214| Cell 3 | Cell 4 |
215
216## Images
217
218Images can be included using the following syntax:
219
220±±±markdown
221
222±±±
223
224
225
226Currently, only a short list of content providers are supported:
227
228±±±markdown
229// Gno-related hosts
230"https://gnolang.github.io"
231"https://assets.gnoteam.com"
232"https://sa.gno.services"
233
234// Other providers should respect DMCA guidelines
235// NOTE: Feel free to open a PR to add more providers here :)
236
237// imgur
238"https://imgur.com"
239"https://*.imgur.com"
240
241// GitHub
242"https://*.github.io"
243"https://github.com"
244"https://*.githubusercontent.com"
245
246// IPFS
247"https://ipfs.io"
248"https://cloudflare-ipfs.com"
249±±±
250
251
252## Gno-Specific Features
253
254### HTML Support
255
256By design, most typical HTML support is disabled in Gno's markdown implementation. This is an intentional decision for both security and ecosystem cohesion.
257
258While traditional markdown often allows arbitrary HTML tags, Gno Flavored Markdown takes a more controlled approach:
259
260- We may progressively whitelist certain HTML components or add custom ones over time
261- Our priority is to enhance our flavored markdown to natively support all essential components
262- We aim to eventually support all the initially HTML-supported features, but with syntax that is:
263 - More readable when viewing the source directly
264 - More integrable with custom browsers such as gnobro in CLI
265
266This approach allows for a more consistent rendering experience across different Gno interfaces while maintaining security and readability as core principles.
267
268### Columns
269
270Gno-Flavored Markdown introduces a column layout system that uses special tags. You can create columns with
271±<gno-columns>± blocks and separate the content with ±|||±.
272
273#### Basic Syntax
274±±±markdown
275<gno-columns>
276Left content
277
278|||
279
280Right content
281</gno-columns>
282±±±
283
284- Renders as:
285
286---
287
288<gno-columns>
289Left content
290
291|||
292
293Right content
294</gno-columns>
295
296---
297
298#### Key Features
299
3001. **Multiple Columns**:
301
302Depending on the screen size. A maximum of four rows can be displayed in
303one row.
304
305***Note**: Any overflow will result in items being displayed in the next row. Also, keep in mind that on smaller screens
306(e.g., phones), this overflow may occur with fewer elements.*
307
308±±±markdown
309<gno-columns>
310First column
311
312|||
313
314Second column
315
316|||
317
318Third column
319
320|||
321
322Fourth column
323
324|||
325
326Fifth column
327</gno-columns>
328±±±
329
330- Renders as:
331
332---
333
334<gno-columns>
335First column
336
337|||
338
339Second column
340
341|||
342
343Third column
344
345|||
346
347Fourth column
348
349|||
350
351Fifth column
352</gno-columns>
353
354---
355
3562. **Mixed Content**:
357
358Columns can be mixed with any markdown content
359
360***Note**: Nested columns are currently not possible*
361
362±±±markdown
363<gno-columns>
364### Text Section
365Paragraph with _formatting_
366
367|||
368
369My Image 
370</gno-columns>
371±±±
372
373- Renders as:
374
375---
376
377<gno-columns>
378### Text Section
379Paragraph with _formatting_
380
381|||
382
383My Image 
384</gno-columns>
385
386---
387
388### Forms
389
390Gno-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.
391
392#### Basic Usage
393
394Create a form using the ±<gno-form>± tag and add inputs with ±<gno-input>±:
395
396±±±markdown
397<gno-form>
398 <gno-input name="name" placeholder="Enter your name" />
399 <gno-input name="email" placeholder="Enter your email" />
400</gno-form>
401±±±
402
403<gno-form>
404 <gno-input name="name" placeholder="Enter your name" />
405 <gno-input name="email" placeholder="Enter your email" />
406</gno-form>
407
408#### Form Structure
409
4101. **Form Container**
411 - Must start with ±<gno-form>± and end with ±</gno-form>±
412 - Optional attributes:
413 - ±path±: Render path after form submission (e.g. ±path="user"± will redirect to ±:user?[params]±)
414 - Form data is always sent as query parameters
415 - Cannot be nested (forms inside forms are not allowed)
416 - Automatically includes a header showing the realm name
417
4182. **Input Fields**
419 - Created with ±<gno-input>± tag
420 - Required attributes:
421 - ±name±: Unique identifier for the input (required)
422 - ±type±: Type of input (optional, defaults to "text")
423 - ±placeholder±: Hint text shown in the input (optional, defaults to "Enter value")
424 - ±description±: Description of the input as title (optional - can be used as title for group of one or multiple inputs)
425 - Supported input types:
426 - ±type="text"± (default): For text input
427 - ±type="number"±: For numeric values only (with browser validation)
428 - ±type="email"±: For email addresses (with basic browser validation)
429 - ±type="tel"±: For phone numbers (no specific validation)
430 - ±type="password"±: For password input (masked characters)
431 - ±type="radio"±: For single selection from a group (requires ±value± attribute)
432 - ±type="checkbox"±: For multiple selections (requires ±value± attribute)
433 - Additional attributes for radio/checkbox:
434 - ±value±: The value to submit when selected (required for radio/checkbox)
435 - ±checked±: Set to "true" to pre-select the option (optional)
436 - Note: Input validation is handled by the browser's HTML5 validation
437 - Any other type will default to "text"
438 - Each input must have a unique name
439 - Inputs are rendered with labels and proper styling
440
4413. **Textarea Fields**
442 - Created with ±<gno-textarea>± tag
443 - Required attributes:
444 - ±name±: Unique identifier for the textarea (required)
445 - ±placeholder±: Hint text shown in the textarea (optional, defaults to "Enter value")
446 - Optional attributes:
447 - ±rows±: Number of visible rows (2-10, defaults to 4)
448 - Perfect for longer text input like messages, descriptions, or comments
449 - Each textarea must have a unique name
450 - Textareas are rendered with labels and proper styling
451
4524. **Select Fields**
453 - Created with ±<gno-select>± tag (similar to radio buttons)
454 - Required attributes:
455 - ±name±: Unique identifier for the select group (required). Use underscores to separate words.
456 - ±value±: The value to submit and display text (required)
457 - Optional attributes:
458 - ±description±: Description of the select group (optional)
459 - ±selected±: Set to "true" to pre-select the option (optional)
460 - Multiple ±<gno-select>± elements with the same ±name± form a select group
461 - All options with the same ±name± form a group where only one can be selected
462 - The ±value± attribute serves both as the submitted value and the displayed text
463
464#### Example Use Cases
465
4661. Form with Path and Query Parameters
467±±±markdown
468<gno-form path="user">
469 <gno-input name="username" type="text" placeholder="Enter username" />
470 <gno-input name="age" type="number" placeholder="Your age" />
471</gno-form>
472±±±
473
474<gno-form path="user">
475 <gno-input name="username" type="text" placeholder="Enter username" />
476 <gno-input name="age" type="number" placeholder="Your age" />
477</gno-form>
478
479This form will submit to ±:user?username=value&age=value± on the same realm.
480
4812. Form with Query Parameters Only
482±±±markdown
483<gno-form>
484 <gno-input name="recipient" type="text" placeholder="Enter recipient address" description="Recipient Information" />
485 <gno-input name="email" type="email" placeholder="Your email" />
486 <gno-input name="pswd" type="password" placeholder="Your password" />
487</gno-form>
488±±±
489
490<gno-form>
491 <gno-input name="recipient" type="text" placeholder="Enter recipient address" description="Recipient Information" />
492 <gno-input name="email" type="email" placeholder="Your email" />
493 <gno-input name="pswd" type="password" placeholder="Your password" />
494</gno-form>
495
496This form will submit to ±?recipient=value&email=value&pswd=value± on the same realm.
497
4983. Form with Radio Buttons
499±±±markdown
500<gno-form>
501 <gno-input name="color" type="radio" value="blue" description="What is your favorite color?" />
502 <gno-input name="color" type="radio" value="red" />
503 <gno-input name="color" type="radio" value="green" />
504</gno-form>
505±±±
506
507<gno-form>
508 <gno-input name="color" type="radio" value="blue" description="What is your favorite color?" />
509 <gno-input name="color" type="radio" value="red" />
510 <gno-input name="color" type="radio" value="green" />
511</gno-form>
512
513Radio buttons allow users to select one option from a group. All radio buttons with the same ±name± form a group where only one can be selected.
514
5154. Form with Checkboxes
516±±±markdown
517<gno-form>
518 <gno-input name="interests" type="checkbox" value="coding" description="What do you like to do?"/>
519 <gno-input name="interests" type="checkbox" value="gaming" />
520 <gno-input name="interests" type="checkbox" value="reading" />
521 <gno-input name="newsletter" type="checkbox" value="subscribe" description="Subscribe to newsletter" placeholder="To get the latest news" checked="true" />
522</gno-form>
523±±±
524
525<gno-form>
526 <gno-input name="interests" type="checkbox" value="coding" description="What do you like to do?" />
527 <gno-input name="interests" type="checkbox" value="gaming" />
528 <gno-input name="interests" type="checkbox" value="reading" />
529 <gno-input name="newsletter" type="checkbox" value="subscribe" description="Subscribe to newsletter" placeholder="To get the latest news" checked="true" />
530</gno-form>
531
532Checkboxes allow users to select multiple options. Use ±checked="true"± to pre-select a checkbox.
533
5345. Form with Textarea
535±±±markdown
536<gno-form>
537 <gno-input name="message" type="text" placeholder="Subject" />
538 <gno-textarea name="content" placeholder="Enter your message here" rows="6" />
539</gno-form>
540±±±
541
542<gno-form>
543 <gno-input name="message" type="text" placeholder="Subject" />
544 <gno-textarea name="content" placeholder="Enter your message here" rows="6" />
545</gno-form>
546
547Textareas are perfect for longer text input. The ±rows± attribute controls the height (4-10 rows, default is 4).
548
5496. Form with Select Options
550±±±markdown
551<gno-form>
552 <gno-select name="country" value="United States" description="Select your country" />
553 <gno-select name="country" value="France" />
554 <gno-select name="country" value="Germany" />
555</gno-form>
556±±±
557
558<gno-form>
559 <gno-select name="country" value="United States" description="Select your country" selected="true" />
560 <gno-select name="country" value="France" />
561 <gno-select name="country" value="Germany" />
562</gno-form>
563
564Select options work like radio buttons but with a more semantic meaning. All ±<gno-select>± elements with the same ±name± form a group where only one can be selected. Use ±selected="true"± to pre-select an option. The ±value± attribute serves both as the submitted value and the displayed text.
565
5667. Complex Form with Mixed Elements
567±±±markdown
568<gno-form path="contact">
569 <gno-input name="name" type="text" placeholder="Your full name" description="Your Information" />
570 <gno-input name="email" type="email" placeholder="Your email address" />
571 <gno-input name="age" type="number" placeholder="Your age" />
572
573 <gno-input name="color" type="radio" value="blue" description="What is your favorite color?" />
574 <gno-input name="color" type="radio" value="red" />
575 <gno-input name="color" type="radio" value="green" />
576
577 <gno-input name="interests" type="checkbox" value="tech" description="What do you like to do?" />
578 <gno-input name="interests" type="checkbox" value="sports" />
579 <gno-input name="interests" type="checkbox" value="music"/>
580
581 <gno-select name="country" value="us" text="United States" description="Select your country" />
582 <gno-select name="country" value="fr" text="France" />
583 <gno-select name="country" value="de" text="Germany" />
584
585 <gno-textarea name="message" placeholder="Tell us about yourself" rows="5" />
586</gno-form>
587±±±
588
589<gno-form path="contact">
590 <gno-input name="name" type="text" placeholder="Your full name" description="Your Information" />
591 <gno-input name="email" type="email" placeholder="Your email address" />
592 <gno-input name="age" type="number" placeholder="Your age" />
593
594 <gno-input name="color" type="radio" value="blue" description="What is your favorite color?" />
595 <gno-input name="color" type="radio" value="red" />
596 <gno-input name="color" type="radio" value="green" />
597
598 <gno-input name="interests" type="checkbox" value="tech" description="What do you like to do?" />
599 <gno-input name="interests" type="checkbox" value="sports" />
600 <gno-input name="interests" type="checkbox" value="music"/>
601
602 <gno-select name="country" value="us" text="United States" description="Select your country" />
603 <gno-select name="country" value="fr" text="France" />
604 <gno-select name="country" value="de" text="Germany" />
605
606 <gno-textarea name="message" placeholder="Tell us about yourself" rows="5" />
607</gno-form>
608
609This example shows how to combine all form element types in a single form.
610
611#### Important Rules
612
6131. **Validation Rules**:
614 - Every ±<gno-input>± must have a ±name± attribute
615 - Every ±<gno-textarea>± must have a ±name± attribute
616 - Every ±<gno-select>± must have a ±name± and ±value± attribute
617 - Duplicate attribute names are not allowed (except for radio, checkbox, and select groups)
618 - Forms must be properly closed
619 - Nested forms will not render
620 - Radio and checkbox inputs must have a ±value± attribute
621 - The ±checked± attribute is only valid for radio and checkbox inputs
622 - The ±selected± attribute is only valid for ±<gno-select>± elements
623 - Textarea ±rows± attribute must be between 2 and 10 (defaults to 4 if invalid or not specified)
624
6252. **Security Features**:
626 - Forms are processed on the realm where they are defined
627 - Each form submission is associated with its realm
628 - The realm name is displayed in the form header
629 - Input validation is handled by the realm's smart contract
630
631---
632
633### Alerts
634
635Alerts are a way to highlight important information in your markdown.
636
637There are five types of alerts:
638
639- INFO
640- NOTE
641- TIP
642- SUCCESS
643- WARNING
644- CAUTION
645
646**NOTE**: The default alert type is INFO (if a wrong alert type is used).
647
648The alert boxes are expandable/collapsible and can have a title.
649By default, the alert boxes are opened. The title is optional and if not provided, the alert type will be used as the title.
650
651±±±markdown
652> [!NOTE]
653> This is a note
654±±±
655
656> [!NOTE]
657> This is a note
658
659±±±markdown
660> [!NOTE]-
661> This is a closed note
662±±±
663
664> [!NOTE]-
665> This is a closed note
666
667±±±markdown
668> [!NOTE] This is a note with title
669> This is a note with title
670±±±
671
672> [!NOTE] This is a note with title
673> This is a note with title
674
675±±±markdown
676> [!INFO]
677> This is an info
678±±±
679
680> [!INFO]
681> This is an info
682
683±±±markdown
684> [!TIP]
685> This is a tip
686±±±
687
688> [!TIP]
689> This is a tip
690
691±±±
692> [!SUCCESS]
693> This is a success
694±±±
695
696> [!SUCCESS]
697> This is a success
698
699±±±
700> [!WARNING]
701> This is a warning
702±±±
703
704> [!WARNING]
705> This is a warning
706
707±±±
708> [!CAUTION]
709> This is a caution
710±±±
711
712> [!CAUTION]
713> This is a caution
714
715±±±markdown
716> [!FOO]
717> The default alert if a wrong alert type is used
718±±±
719
720> [!FOO]
721> This is the default alert
722
723±±±markdown
724> [!NOTE]
725> This is a note
726> > [!NOTE]
727> > This is a scoped note
728±±±
729
730> [!NOTE]
731> This is a note
732> > [!NOTE]
733> > This is a scoped note
734
735### User Mentions and Bech32 Addresses
736
737Gno markdown automatically recognizes and renders user mentions and Bech32 addresses as clickable links.
738
739#### User Mentions
740
741// You can mention users using the "@" symbol followed by a username. The username can contain letters, numbers, and underscores.
742
743±±±markdown
744Hello @alice, how are you doing?
745
746This is a mention of @bob_user and @test-123.
747
748You can also mention users like @user_name_123.
749±±±
750
751
752Hello @alice, how are you doing?
753
754This is a mention of @bob_user.
755
756You can also mention users like @user_name_123.
757
758#### Bech32 Addresses
759
760Gno markdown can automatically recognize and render valid Bech32 addresses as clickable links.
761
762±±±markdown
763This is a GNO address: g1jg8mtutu9khhfwc4nxmuhcpftf0pajdhfvsqf5
764
765You can also reference g1abc123def456ghi789jkl012mno345pqr678stu901vwx234yz5.
766±±±
767
768This is a GNO address: g1jg8mtutu9khhfwc4nxmuhcpftf0pajdhfvsqf5
769
770You can also reference g1abc123def456ghi789jkl012mno345pqr678stu901vwx234yz5.
771
772### Smart Contract Integration
773
774XXX: TODO
775
776±±±markdown
777gno.land/r/boards
778gno.land/r/boards:foo/bar
779gno.land/r/docs/markdown$source
780±±±
781
782gno.land/r/boards
783gno.land/r/boards:foo/bar
784gno.land/r/docs/markdown$source
785
786### And more...
787
788XXX: TODO
789
790## Future Enhancements
791
792The markdown support in Gno is being actively developed. Future enhancements may include:
793
794- Extended support for custom components
795- Interactive elements specific to blockchain functions
796- Rich rendering of on-chain data
797- Better integration with Gno's package system
798
799[Read more](https://github.com/gnolang/gno/issues/3255)
800
801## Conclusion
802
803Markdown 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.
804
805As the Gno ecosystem grows, expect the markdown capabilities to expand accordingly, providing even richer formatting and interactive elements for documentation and user interfaces.
806
807## See Also
808
809For programmatic markdown generation using Go code, check out the [±p/moul/md± demo](/r/docs/moul_md) which demonstrates how to use the ±p/moul/md± package to generate markdown content in your Gno realms.
810`
811 output = strings.ReplaceAll(output, "±", "`")
812 return output
813}
