| | @@ -0,0 +1,224 @@ |
| 1 | +# Markdown formatting rules
|
| 2 | +
|
| 3 | +In addition to its native Wiki formatting syntax, Fossil supports Mark down syntax as specified by
|
| 4 | +[John Gruber's original Markdown implementation](http://daringfireba
|
| 5 | +[syntax description](http://daringfireball.net/projects/markdown/syntax), of which the page you
|
| 6 | +are reading is an extract.
|
| 7 | +
|
| 8 | +This page itself uses Markdown formatting.
|
| 9 | +
|
| 10 | +## Summary
|
| 11 | +
|
| 12 | + - Block elements
|
| 13 | +
|
| 14 | + * A **paragraph** is a group of consecutive lines. Paragraphs are separated by blank lines.
|
| 15 | +
|
| 16 | + * A **Header** is a line of text underlined with equal signs or hyphens, or prefixed by a
|
| 17 | + in s, or prefixed by a
|
| 18 | + number of hash marks.
|
| 19 | +
|
| 20 | + * **Block quotes** are blocks of text prefixed by '>'.
|
| 21 | +
|
| 22 | + * **Ordered list** items are prefixed by a number and a period. **Unordered list** items
|
| 23 | + are prefixed by a hyphen, asterisk or plus sign. Pre
|
| 24 | +
|
| 25 | + * **Code blocks** are formed by lines of text (possibly including empty lines) prefixed by
|
| 26 | + at least 4 spaces or a tab.
|
| 27 | +
|
| 28 | + * A **horizontal rule** is a line consisting of 3 or more asterisks, hyphens or underscores,
|
| 29 | + with optional whitespace between them.
|
| 30 | +
|
| 31 | + - Span elements
|
| 32 | +
|
| 33 | + * 3 types of **links** exist:
|
| 34 | +
|
| 35 | + - **automatic links** are URLs or email addresses enclosed in angle brackets
|
| 36 | + ('<' and '>'), and are displayed as such.
|
| 37 | +
|
| 38 | + - **inline links** consist of the displayed link text in squ
|
| 39 | + followed by the
|
| 40 | +
|
| 41 | + - **reference links** separate _link instance_ from _link definition_. A link instance efinition_. A link instance
|
| 42 | + consists of the displayed link text
|
| 43 | + in square brackets. in square brackets.
|
| 44 | + The corresponding link definition can occur anywhere on the page, and consists
|
| 45 | + of the link definition name in s a colon, whitespace and the
|
| 46 | + link target.
|
| 47 | +
|
| 48 | + * **Emphasis** can be given by wrapping text in one or two asterisks or underscores - use
|
| 49 | + one for HTML `<em>`, and two for `<strong>` emphasis.
|
| 50 | +
|
| 51 | + * A **code span** is text wrapped in backticks ('`').
|
| 52 | +
|
| 53 | + * **Images** use a syntax much like inline or reference links, # Markdown formatting rules
|
| 54 | +
|
| 55 | +In addition to its native Wiki formatting syntax, Fossil supports Markdown syntax as specified by
|
| 56 | +[John Gruber's original Markdown implementation](http://daringfireball.net/projects/markdown/).
|
| 57 | +For lots of examples - not repeated here - please refer to its
|
| 58 | +[syntax description](http://daringfireball.net/projects/markdown/syntax), of which the page you
|
| 59 | +are reading is an extract.
|
| 60 | +
|
| 61 | +This page itself uses Markdown formatting.
|
| 62 | +
|
| 63 | +## Summary
|
| 64 | +
|
| 65 | + - Block elements
|
| 66 | +
|
| 67 | + * A **paragraph** is a group of consecutive lines. Paragraphs are separated by blank lines.
|
| 68 | +
|
| 69 | + * A **Header** is a line of text underlined with equal signs or hyphens, or prefixed by a
|
| 70 | + number of hash marks.
|
| 71 | +
|
| 72 | + * **Block quotes** are blocks of text prefixed by '>'.
|
| 73 | +
|
| 74 | + * **Ordered list** items are prefixed by a number and a period. **Unordered list** items
|
| 75 | + are prefixed by a hyphen, asterisk or plus sign. Prefix and item text are separated by
|
| 76 | + whitespace.
|
| 77 | +
|
| 78 | + * **Code blocks** are formed by lines of text (possibly including empty lines) prefixed by
|
| 79 | + at least 4 spaces or a tab.
|
| 80 | +
|
| 81 | + * A **horizontal rule** is a line consisting of 3 or more asterisks, hyphens or underscores,
|
| 82 | + with optional whitespace between them.
|
| 83 | +
|
| 84 | + - Span elements
|
| 85 | +
|
| 86 | + * 3 types of **links** exist:
|
| 87 | +
|
| 88 | + - **automatic links** are URLs or email addresses enclosed in angle brackets
|
| 89 | + a * **Emphasis** can be given by wrapping text in one or two asterisks or underscores - use
|
| 90 | + one for HTML `<em>`, and two for `<strong>` emphasis.
|
| 91 | +
|
| 92 | + * A **code span** is text wrapped in backticks ('`').
|
| 93 | +
|
| 94 | + * **Images** use a syntax much like inline or reference links, but with alt attribute text
|
| 95 | + ('img alt=...') instead of link text, and the first pair of square
|
| 96 | + brackets m prefix; the items will be
|
| 97 | +renumbered during rendering. However, future implementations may
|
| 98 | +for the first item in a list indicates an offset to be used for subsequent items.
|
| 99 | +
|
| 100 | +For list items spanning multiple lines, subsequent lines can be indented using an arbitrary amount
|
| 101 | +of whitespace.
|
| 102 | +
|
| 103 | +List items will be wrapped in HTML `<p>` tags if they are separated by blank lines.
|
| 104 | +
|
| 105 | +A list item may span multiple paragraphs. At least the first line
|
| 106 | +be indented using at least 4 spaces or a tab character.
|
| 107 | +
|
| 108 | +Block quotes within list items must have their '>' delimiters indented using 4 up to 7 spaces.
|
| 109 | +
|
| 110 | +Code blocks within list items need to be indented _twice_, that is, using 8 spaces or 2 tab
|
| 111 | +characters.
|
| 112 | +
|
| 113 | +### Code blocks
|
| 114 | +
|
| 115 | +Lines within a code block are rendered verbatim using HTML `<pre>` and `<code>` tags, except that
|
| 116 | +HTML punctuation characters like '<' and '&' are automatically converted to HTML entities. Thus,
|
| 117 | +there is no need to explicitly escape HTML syntax within a code block.
|
| 118 | +
|
| 119 | +A code block runs until the first non blank line with indent less than 4 spaces or 1 tab character.
|
| 120 | +
|
| 121 | +
|
| 122 | +Regular Markdown syntax is not processed within code blocks.
|
| 123 | +
|
| 124 | +### Links
|
| 125 | +
|
| 126 | +#### Automatic links
|
| 127 | +
|
| 128 | +When rendering automatic links to email addresses, HTML enco
|
| 129 | +prevent some spambots from harvesting.
|
| 130 | +
|
| 131 | +#### Inline links
|
| 132 | +
|
| 133 | +Links to resources on the same server can use relative paths (i.e. can start with a '/').
|
| 134 | +
|
| 135 | +An optional title for the link (e.g. to have mouseover text in the b rowser) may be given behind
|
| 136 | +the link target but within the parentheses, in single and double quo
|
| 137 | +link target by whitespace.
|
| 138 | +link target by whitespace.
|
| 139 | +
|
| 140 | +# reference link consists of
|
| 141 | +>
|
| 142 | +> - one or more _link instances_ at appropriate locations in the page text
|
| 143 | +> - a single _link definition_ at an arbit
|
| 144 | +> During rendering, each link instance is resolved, and the corresponding definition is
|
| 145 | +> filled in. No separate link definition clauses occu r in the rendered output.
|
| 146 | +>
|
| 147 | +> There are 3 fields involved in link instances and definitions:
|
| 148 | +>
|
| 149 | +> - link text (i.e. the text that is displayed at the resulting link)
|
| 150 | +> - link definition name (i.e. an unique ID binding link instances to link definition)
|
| 151 | +> - link target (a target URL for the link)
|
| 152 | +
|
| 153 | +Multiple link instances may reference the same link definition using its link definition
|
| 154 | +name.
|
| 155 | +
|
| 156 | +Link definition names are case insensitive, and may contain letters, numbers, spaces and
|
| 157 | +punctuation.
|
| 158 | +
|
| 159 | +##### Link instance
|
| 160 | +
|
| 161 | +A space may be inserted between the bracket pairs for link text and link definition name.
|
| 162 | +
|
| 163 | +A link instance can use an _implicit link definition name_ shortcut, in which case the link
|
| 164 | +text is used as the link definition name. The second set of brackets then remains empty, e.g.
|
| 165 | +'[Google][]' ('Google' being used as both link text and link definition name).
|
| 166 | +
|
| 167 | +##### Link definition
|
| 168 | +
|
| 169 | +The first bracket pair containing the link definition name may be indented using up to 3 spaces.
|
| 170 | +
|
| 171 | +The link target may optionally be surrounded by angle brackets ('<' and '>').
|
| 172 | +
|
| 173 | +A link target may be followed by an optional title (e.g. to have mouseover text in the browser).
|
| 174 | +This title may be enclosed in parentheses, single or double quotes.
|
| 175 | +
|
| 176 | +Link definitions may be split into 2 lines, with the title on the second line, arbitrarily
|
| 177 | +indented. This may be more visually pleasing when using long link targets.
|
| 178 | +
|
| 179 | +### Emphasis
|
| 180 | +
|
| 181 | +The same character(s) used for starting the emphasis must be used to end it; don't mix
|
| 182 | +asterisks and underscores.
|
| 183 | +
|
| 184 | +Emphasis can be used in the middle of a word. That is, there need not be whitespace on either
|
| 185 | +side of emphasis start or end punctuation characters.
|
| 186 | +
|
| 187 | +### Code spans
|
| 188 | +
|
| 189 | +To include a literal backtick character in a code span, use multiple backticks as opening and
|
| 190 | +closing delimiters.
|
| 191 | +
|
| 192 | +Whitespace may exist immediately after the opening delimiter and b Markdown formatting rules
|
| 193 | +
|
| 194 | +In addition to its native Wiki formatting syntax, Fossil supports Markdown syntax as specified by
|
| 195 | +[John Gruber's original Markdown implementation](http://daringfireball.net/projects/markdown/).
|
| 196 | +For lots of examples - not repeated here - please refer to its
|
| 197 | +[syntax description](http://daringfireball.net/projects/markdownr
|
| 198 | +a HTML block level construct (`<div>`, `<table>` etc) must be separated from surrounding
|
| 199 | +context using blank lines, and must both occur at the start of a line.
|
| 200 | +
|
| 201 | +No extra unwanted `<p>` HTML tags are added around HTML block level tags.
|
| 202 | +
|
| 203 | +Markdown formatting within HTML block level tags is not processed; however, formatting within
|
| 204 | +span level tags (e.g. `<mark>`) is processed normally.
|
| 205 | +
|
| 206 | +### Escaping Markdown punctuation
|
| 207 | +
|
| 208 | +The following punctuation characters can be escaped using backslash:
|
| 209 | +
|
| 210 | + - \\ backslash
|
| 211 | + - ` backtick
|
| 212 | + - * asterisk
|
| 213 | + - _ underscore
|
| 214 | + - {} curly braces
|
| 215 | + - [] square brackets
|
| 216 | + - () parentheses
|
| 217 | + - # hash mark
|
| 218 | + - + plus sign
|
| 219 | + - - minus sign (hyphen)
|
| 220 | + - . dot
|
| 221 | + - ! exclamation mark
|
| 222 | +
|
| 223 | +To render a literal backslash, use 2 backslashes ('\\\\').
|
| 224 | +
|