sample.my (5592B)
1 # Mymarkdown syntax showcase 2 3 @@ $toc.generate() 4 5 ## Block syntaxes 6 7 ### Paragraphs 8 9 Normal blocks of text separated by newlines, constitute paragraphs. 10 This sentence is part of the same paragraph as above. 11 12 While the first line of a paragraph may not be indented, 13 subsequent lines may be indented relative to the first line. 14 15 > This is a paragraph. 16 17 This is a syntax error. 18 19 In general, indented blocks are not allowed unless explicitly introduced by a marker. 20 In particular, indented code blocks do not exist in mymarkdown. 21 This is because indented blocks can easily arise from having insufficient indentation on the previous element. 22 23 ; Paragraphs may also be introduced with the `;` marker, 24 similar to other block syntaxes. 25 An indented set of blocks follows the `;` marker. 26 27 ### Headings 28 29 Headings are introduced with hashes. 30 The number of hashes indicates the level of the heading (h1 = `#`, h2 = `##`, ...). 31 A single indented inline block follows the marker. 32 33 Note that indented blocks in mymarkdown are strict --- 34 the first non-whitespace character after the marker is used to determine the indentation, 35 after which all subsequent lines must have matching or more indentation. 36 37 > #### This is a 38 multiline heading. 39 40 #### This is also a 41 multiline heading. 42 43 #### This is a syntax error. 44 45 This is because there are two paragraphs following the marker. 46 47 #### This heading itself is not a syntax error. 48 But this misaligned second line is interpreted as an indented paragraph, which is a syntax error. 49 50 ### Blocks 51 52 > Blocks are introduced by the `>` marker. 53 54 An indented set of blocks follows the `>` marker. 55 56 > Unlike markdown, placing `>` before each line is probably a mistake. 57 > This is because each `>` introduces a new block quote, making this the third blockquote in this section. 58 59 ### Lists 60 61 There are many types of lists in mymarkdown. They are: 62 - Unordered list, introduced by `-` 63 - Ordered list, introduced by `.` 64 - Description list, introduced by `:` 65 - Task list, introduced by `- [ ]`, `- [x]`, or `- [X]` 66 67 In all cases, the list is formed by grouping list items of the same marker type, 68 and an indented inline block follows the list item marker. 69 70 The level of nesting can be increased by repeating the marker: 71 - Level-2 unordered list marker: `--` 72 - Level-2 ordered list marker: `..` 73 - Level-2 description list marker: `::` 74 - Level-2 task list marker: `-- [ ]`, `-- [x]`, or `-- [X]` 75 76 Note that for ordered lists, no numbers or letters are allowed before the marker. 77 Instead they are simply automatically numbered from 1. 78 Use directives to adjust the starting index. 79 80 Nested labels extend the parent's counter rather than beginning a new counter. 81 82 . List item 1 83 . List item 2 84 .. List item 2.1 85 .. List item 2.2 86 . List item 3 87 88 For all list items, an indented //inline// block follows the list marker, 89 **not** an arbitrary **set** of indented blocks. 90 That means the following is a syntax error: 91 92 > - This is a syntax error. 93 94 One should not use multiple paragraphs in a list item. 95 96 To have items that contain multiple paragraphs, instead use a short phrase or sentence for the list item itself, 97 and follow it up with a longer series of paragraphs that [//elaborate//](#List item elaborations) on the list item. 98 99 ### List item elaborations 100 101 Sometimes, lists are used not to convey merely a list of items, 102 but also come with a **elaboration** or **description** of the item. 103 In such cases, elaboration blocks introduced by `+` markers matching the level of the list item 104 can be added immediately after the list item to be described or elaborated on. 105 This way, the main list marker itself can be used to contain just the key point or phrase. 106 107 An indented set of blocks follows the list item elaboration marker. 108 109 #### Examples 110 111 - Some examples of when list item elaborations can be used: 112 -- **In a list of pros and cons.** 113 ++ The main list items can be used to list the actual pros and cons, 114 while list item elaborations can be used to justify them. 115 116 -- **In a list of examples.** 117 ++ The main list items can be used for the names of the examples, 118 while elaborations go into more detail about how the examples work. 119 Like this example! 120 121 - Some examples of when list item elaborations must be used: 122 -- **When you want to nest multiple paragraphs within a bullet.** 123 ++ As the list item markers themselves only take in one indented inline block, 124 they physically cannot contain multiple paragraphs. 125 This limitation is meant to discourage using lists in situations 126 where a subsection would be more appropriate. 127 128 In such cases, it is usually beneficial to add a short "name" or "title" for your paragraphs 129 in the actual list item (and emphasize or strongly emphasize them), 130 and then place the paragraphs themselves inside the list item elaboration. 131 132 If that is not desirable however, the workaround is to use an //empty// list item, 133 so that the paragraphs you place inside the list item elaboration 134 become the only paragraphs nested under the bullet. 135 136 - Some examples of when list item elaborations should not be used: 137 -- **When you simply have long list items.** 138 ++ Regardless of the length of the content you wish to place in the list items, 139 the key consideration to keep in mind is whether the content "belongs" to the main list, 140 or simply to the current list item. 141 142 If the content does truly belong to the main list, then the content should be used as the list item itself. 143 In such cases, it may be worth making the list a //loose// list, which means placing empty lines after each list item.