Fossil SCM

fossil-scm / src / markdown.md
Source Blame History 253 lines
5fcc1d5… drh 1 # Markdown Overview #
5fcc1d5… drh 2
5fcc1d5… drh 3 ## Paragraphs ##
5fcc1d5… drh 4
1e491f6… andygoth 5 > Paragraphs are divided by blank lines.
3bfdafe… andygoth 6 > End a line with two or more spaces to force a mid-paragraph line break.
5fcc1d5… drh 7
5fcc1d5… drh 8 ## Headings ##
5fcc1d5… drh 9
5fcc1d5… drh 10 >
02403f0… andygoth 11 # Top Level Heading Alternative Top Level Heading
02403f0… andygoth 12 # Top Level Heading Variant # =============================
02403f0… andygoth 13 >
02403f0… andygoth 14 ## 2nd Level Heading Alternative 2nd Level Heading
02403f0… andygoth 15 ## 2nd Level Heading Variant ## -----------------------------
5fcc1d5… drh 16 >
02403f0… andygoth 17 ### 3rd Level Heading ### 3rd Level Heading Variant ###
02403f0… andygoth 18 #### 4th Level Heading #### 4th Level Heading Variant ####
02403f0… andygoth 19 ##### 5th Level Heading ##### 5th Level Heading Variant #####
02403f0… andygoth 20 ###### 6th Level Heading ###### 6th Level Heading Variant ######
5fcc1d5… drh 21
5fcc1d5… drh 22 ## Links ##
5fcc1d5… drh 23
5fcc1d5… drh 24 > 1. **\[display text\]\(URL\)**
5fcc1d5… drh 25 > 2. **\[display text\]\(URL "Title"\)**
3bfdafe… andygoth 26 > 3. **\[display text\]\(URL 'Title'\)**
3bfdafe… andygoth 27 > 4. **\<URL\>**
3bfdafe… andygoth 28 > 5. **\[display text\]\[label\]**
3bfdafe… andygoth 29 > 6. **\[display text\]\[\]**
2856830… andygoth 30 > 7. **\[display text\]**
774fb77… drh 31 > 8. **\[\]\(URL\)**
3bfdafe… andygoth 32
774fb77… drh 33 > With link formats 5, 6, and 7 ("reference links"), the URL is supplied
774fb77… drh 34 > elsewhere in the document, as shown below. Link formats 6 and 7 reuse
774fb77… drh 35 > the display text as the label. Labels are case-insensitive. The title
774fb77… drh 36 > may be split onto the next line with optional indenting.
3bfdafe… andygoth 37
3bfdafe… andygoth 38 > * **\[label\]:&nbsp;URL**
3bfdafe… andygoth 39 > * **\[label\]:&nbsp;URL&nbsp;"Title"**
3bfdafe… andygoth 40 > * **\[label\]:&nbsp;URL&nbsp;'Title'**
3bfdafe… andygoth 41 > * **\[label\]:&nbsp;URL&nbsp;(Title)**
3bfdafe… andygoth 42
b8fac03… drh 43 > If **URL** begins with "http:", "https:', "ftp:' or "mailto:",
b8fac03… drh 44 > it may optionally be written **\<URL\>** (format 4).
b8fac03… drh 45 > Other **URL** formats include:
774fb77… drh 46 > <ul>
b8fac03… drh 47 > <li> A relative pathname.
774fb77… drh 48 > <li> A pathname starting with "/" in which case the Fossil server
f4dc114… drh 49 > URL prefix is prepended
774fb77… drh 50 > <li> A wiki page name, or a wiki page name preceded by "wiki:"
f4dc114… drh 51 > <li> An artifact or ticket hash or hash prefix
774fb77… drh 52 > <li> A date and time stamp: "YYYY-MM-DD HH:MM:SS" or a subset that
f4dc114… drh 53 > includes at least the day of the month.
f4dc114… drh 54 > <li> An [interwiki link](#intermap) of the form "<i>Tag</i><b>:</b><i>PageName</i>"</ul>
774fb77… drh 55
b8fac03… drh 56 > In format 8, then the URL becomes the display text. This is useful for
774fb77… drh 57 > hyperlinks that refer to wiki pages and check-in and ticket hashes.
774fb77… drh 58
c5e4c8b… drh 59 ## Text Style ##
5fcc1d5… drh 60
5fcc1d5… drh 61 > * _\*italic\*_
5fcc1d5… drh 62 > * *\_italic\_*
5fcc1d5… drh 63 > * __\*\*bold\*\*__
5fcc1d5… drh 64 > * **\_\_bold\_\_**
9e67b8a… andygoth 65 > * ___\*\*\*italic+bold\*\*\*___
9e67b8a… andygoth 66 > * ***\_\_\_italic+bold\_\_\_***
3bfdafe… andygoth 67 > * \``code`\`
5fcc1d5… drh 68
3bfdafe… andygoth 69 > The **\`code\`** construct disables HTML markup, so one can write, for
3bfdafe… andygoth 70 > example, **\`\<html\>\`** to yield **`<html>`**.
5fcc1d5… drh 71
5fcc1d5… drh 72 ## Lists ##
5fcc1d5… drh 73
c5e4c8b… drh 74 > ~~~
c5e4c8b… drh 75 * bullet item
c5e4c8b… drh 76 + bullet item
c5e4c8b… drh 77 - bullet item
c5e4c8b… drh 78 1. numbered item
c5e4c8b… drh 79 2) numbered item
c5e4c8b… drh 80 ~~~
3bfdafe… andygoth 81
3bfdafe… andygoth 82 > A two-level list is created by placing additional whitespace before the
3bfdafe… andygoth 83 > **\***/**+**/**-**/**1.** of the secondary items.
3bfdafe… andygoth 84
c5e4c8b… drh 85 > ~~~
c5e4c8b… drh 86 * top-level item
c5e4c8b… drh 87 * second-level item
c5e4c8b… drh 88 ~~~
5fcc1d5… drh 89
5fcc1d5… drh 90 ## Block Quotes ##
5fcc1d5… drh 91
3bfdafe… andygoth 92 > Begin each line of a paragraph with **>** to block quote that paragraph.
5fcc1d5… drh 93
5fcc1d5… drh 94 > >
5fcc1d5… drh 95 > This paragraph is indented
5fcc1d5… drh 96 > >
5fcc1d5… drh 97 > > Double-indented paragraph
5fcc1d5… drh 98
18a84ed… drh 99 ## Literal/Verbatim Text - Code Blocks ##
1b2d6c3… wyoung 100
1b2d6c3… wyoung 101 > For inline text, you can either use \``backticks`\` or the HTML
1b2d6c3… wyoung 102 > `<code>` tag.
1b2d6c3… wyoung 103 >
18a84ed… drh 104 > For blocks of text or code:
1b2d6c3… wyoung 105 >
1b2d6c3… wyoung 106 > 1. Indent the text using a tab character or at least four spaces.
1b2d6c3… wyoung 107 > 2. Precede the block with an HTML `<pre>` tag and follow it with `</pre>`.
06a3361… wyoung 108 > 3. Surround the block by <tt>\`\`\`</tt> (three or more) or <tt>\~\~\~</tt> either at the
06a3361… wyoung 109 > left margin or indented no more than three spaces. The first word
06a3361… wyoung 110 > on that same line (if any) is used in a “`language-WORD`” CSS style in
06a3361… wyoung 111 > the HTML rendering of that code block and is intended for use by
06a3361… wyoung 112 > code syntax highlighters. Thus <tt>\`\`\`c</tt> would mark a block of code
06a3361… wyoung 113 > in the C programming language. Text to be rendered inside the code block
06a3361… wyoung 114 > should therefore start on the next line, not be cuddled up with the
4083e5d… drh 115 > backticks or tildes. See the "Diagrams" section below for the case where
4083e5d… drh 116 > "`language-WORD`" is "pikchr".
1b2d6c3… wyoung 117
1b2d6c3… wyoung 118 > With the standard skins, verbatim text is rendered in a fixed-width font,
1b2d6c3… wyoung 119 > but that is purely a presentation matter, controlled by the skin’s CSS.
4083e5d… drh 120
6f69ccd… andygoth 121
6f69ccd… andygoth 122 ## Tables ##
6f69ccd… andygoth 123
6f69ccd… andygoth 124 >
02403f0… andygoth 125 | Header 1 | Header 2 | Header 3 |
02403f0… andygoth 126 ----------------------------------------------
02403f0… andygoth 127 | Row 1 Col 1 | Row 1 Col 2 | Row 1 Col 3 |
02403f0… andygoth 128 |:Left-aligned |:Centered :| Right-aligned:|
02403f0… andygoth 129 | | ← Blank → | |
02403f0… andygoth 130 | Row 4 Col 1 | Row 4 Col 2 | Row 4 Col 3 |
6f69ccd… andygoth 131
7a131cf… danield 132 > The first row is a header if followed by a line consisting only of whitespace,
7a131cf… danield 133 > dashes, colons, or pipes.
6f69ccd… andygoth 134
6f69ccd… andygoth 135 > Placing **:** at the left, both, or right sides of a cell gives left-aligned,
f141791… danield 136 > centered, or right-aligned text, respectively. By default, both header and
7a131cf… danield 137 > body cells are left-aligned. If there are properly placed pipes and colons
7a131cf… danield 138 > within the line following the header, then these mandate the default
7a131cf… danield 139 > alignments for the respective columns.
08e4371… andygoth 140
08e4371… andygoth 141 > The leftmost or rightmost **\|** is required only if the first or last column,
08e4371… andygoth 142 > respectively, contains at least one blank cell.
08e4371… andygoth 143
4083e5d… drh 144 ## Diagrams ##
4083e5d… drh 145
4083e5d… drh 146 >
4083e5d… drh 147 ~~~~~
4083e5d… drh 148 ~~~ pikchr
4083e5d… drh 149 oval "Start" fit; arrow; box "Hello, World!" fit; arrow; oval "Done" fit
4083e5d… drh 150 ~~~
4083e5d… drh 151 ~~~~~
4083e5d… drh 152
4083e5d… drh 153 > Formatted using [Pikchr](https://pikchr.org/home), resulting in:
4083e5d… drh 154
4083e5d… drh 155 >
4083e5d… drh 156 ~~~ pikchr
4083e5d… drh 157 oval "Start" fit; arrow; box "Hello, World!" fit; arrow; oval "Done" fit
4083e5d… drh 158 ~~~
4083e5d… drh 159
3990518… george 160 <a id="ftnts"></a>
3990518… george 161 ## Footnotes ##
3990518… george 162
f3adbd8… drh 163 > Footnotes (or "endnotes") is a Fossil extension of classical Markdown.
3990518… george 164 > Fossil's syntax for footnotes is similar to links and
3990518… george 165 > is distinguished by the use of character **^**
3990518… george 166 > that *immediately* follows an opening bracket.
3990518… george 167
3990518… george 168 > 1. **\(^** footnote's text **)**
3990518… george 169 > 2. **\[** fragment of text **]\(^** a comment about that fragment **\)**
3990518… george 170 > 3. **\[^**&nbsp;label&nbsp;**\]**
3990518… george 171 > 4. **\[** fragment of text **\]\[^**&nbsp;label&nbsp;**\]**
3990518… george 172 > 5. **\[** fragment of text **\]\[^\]**
3990518… george 173
3990518… george 174 > With formats 1 and 2 ("inline footnotes") text of a footnote is provided
3990518… george 175 > in the place where the corresponding numeric mark will be rendered.
3990518… george 176 > With formats 3, 4, and 5 ("reference footnotes") text of a footnote
3990518… george 177 > is supplied elsewhere in the document, as shown below.
3990518… george 178 > Formats 2, 4 and 5 ("span-specific footnotes") mark a specific fragment
3990518… george 179 > that is being commented in the footnote.
3990518… george 180 > Format 5 reuses a fragment of text as a label.
3990518… george 181 > Labels are case-insensitive.
3990518… george 182
3990518… george 183 > ```
3990518… george 184 > [^label]: Footnote definition must start on the first column.
3990518… george 185 > The second line (if any) must be indented by two or more spaces.
3990518… george 186 > Definition continues until indentation drops below that of the 2nd line.
3990518… george 187 >```
3990518… george 188 > Character **^** is not part of a label, it is part of the syntax.
3990518… george 189 > Both a footnote's text and a fragment to which a footnote applies
3990518… george 190 > are subject to further interpretation as Markdown sources.
3990518… george 191
6436ecf… wyoung 192 ## Safe HTML ##
6436ecf… wyoung 193
6436ecf… wyoung 194 > Markdown documents may contain raw HTML, filtered to allow the following:
6436ecf… wyoung 195 >
6436ecf… wyoung 196 > &lt;a&gt; &lt;abbr&gt; &lt;address&gt; &lt;article&gt; &lt;aside&gt;
6436ecf… wyoung 197 > &lt;b&gt; &lt;big&gt; &lt;blockquote&gt; &lt;br&gt; &lt;caption&gt;
6436ecf… wyoung 198 > &lt;center&gt; &lt;cite&gt; &lt;code&gt; &lt;col&gt; &lt;colgroup&gt;
6436ecf… wyoung 199 > &lt;dd&gt; &lt;del&gt; &lt;details&gt; &lt;dfn&gt; &lt;div&gt; &lt;dl&gt;
6436ecf… wyoung 200 > &lt;dt&gt; &lt;em&gt; &lt;figcaption&gt; &lt;figure&gt; &lt;font&gt;
6436ecf… wyoung 201 > &lt;footer&gt; &lt;h1&gt; &lt;h2&gt; &lt;h3&gt; &lt;h4&gt; &lt;h5&gt;
6436ecf… wyoung 202 > &lt;h6&gt; &lt;header&gt; &lt;hr&gt; &lt;i&gt; &lt;img&gt; &lt;ins&gt;
6436ecf… wyoung 203 > &lt;kbd&gt; &lt;label&gt; &lt;li&gt; &lt;mark&gt; &lt;meter&gt; &lt;nav&gt;
6436ecf… wyoung 204 > &lt;nobr&gt; &lt;nowiki&gt; &lt;ol&gt; &lt;p&gt; &lt;picture&gt; &lt;pre&gt;
6436ecf… wyoung 205 > &lt;progress&gt; &lt;q&gt; &lt;s&gt; &lt;samp&gt; &lt;section&gt; &lt;small&gt;
6436ecf… wyoung 206 > &lt;source&gt; &lt;span&gt; &lt;strike&gt; &lt;strong&gt; &lt;sub&gt;
6436ecf… wyoung 207 > &lt;summary&gt; &lt;sup&gt; &lt;table&gt; &lt;tbody&gt; &lt;td&gt;
6436ecf… wyoung 208 > &lt;tfoot&gt; &lt;th&gt; &lt;thead&gt; &lt;time&gt; &lt;title&gt; &lt;tr&gt;
6436ecf… wyoung 209 > &lt;tt&gt; &lt;u&gt; &lt;ul&gt; &lt;var&gt; &lt;wbr&gt; &lt;verbatim&gt;
6436ecf… wyoung 210 >
6436ecf… wyoung 211 > Any other tag is sent through to the output in a way that causes it to be
6436ecf… wyoung 212 > visibly called out as disallowed. This is the same whitelist as for
6436ecf… wyoung 213 > [Fossil Wiki](/wiki_rules) markup.
6436ecf… wyoung 214 >
6436ecf… wyoung 215 > Fossil-specific elements **&lt;nowiki&gt;** and **&lt;verbatim&gt;** disable
6436ecf… wyoung 216 > wiki and Markdown processing within their spans; see
6436ecf… wyoung 217 > [Wiki formatting rules](/wiki_rules) for details.
6436ecf… wyoung 218 >
6436ecf… wyoung 219 > Only a fixed set of attributes is permitted (for example **id**,
6436ecf… wyoung 220 > **class**, **style**, **href**, **src**, **srcset**, **alt**, **type**,
6436ecf… wyoung 221 > **datetime**, and **value**). Event handlers, **javascript:** URLs, and
6436ecf… wyoung 222 > similar constructs are stripped.
6436ecf… wyoung 223 >
6436ecf… wyoung 224 > Repository administrators may allow additional unsafe HTML (such as
6436ecf… wyoung 225 > **&lt;script&gt;** and **&lt;form&gt;**) in some contexts using the
6436ecf… wyoung 226 > [safe-html setting](/help/safe-html) on the Admin/Wiki page.
6436ecf… wyoung 227
5fcc1d5… drh 228 ## Miscellaneous ##
5fcc1d5… drh 229
3bfdafe… andygoth 230 > * In-line images are made using **\!\[alt-text\]\(image-URL\)**.
6436ecf… wyoung 231 > * Use HTML for advanced formatting; see [Safe HTML](#safe-html) above.
ea92c2b… wyoung 232 > * **\<!--** HTML-style comments **-->** are allowed through only when
ea92c2b… wyoung 233 > the safe-HTML rules are bypassed.
6f69ccd… andygoth 234 > * Escape special characters (ex: **\[** **\(** **\|** **\***)
6f69ccd… andygoth 235 > using backslash (ex: **\\\[** **\\\(** **\\\|** **\\\***).
3bfdafe… andygoth 236 > * A line consisting of **---**, **\*\*\***, or **\_\_\_** is a horizontal
3bfdafe… andygoth 237 > rule. Spaces and extra **-**/**\***/**_** are allowed.
f0fa7f2… drh 238 > * Paragraphs enclosed in **\<html\>...\</html\>** is passed through unchanged.
3bfdafe… andygoth 239 > * See [daringfireball.net][] for additional information.
369d7d1… stephan 240 > * See this page's [Markdown source](/md_rules?txt=1) for more examples.
a6725ea… drh 241
a6725ea… drh 242 ## Special Features For Fossil ##
a6725ea… drh 243
6f69ccd… andygoth 244 > * In hyperlinks, if the URL begins with **/** then the root of the Fossil
a6725ea… drh 245 > repository is prepended. This allows for repository-relative hyperlinks.
6f69ccd… andygoth 246 > * For documents that begin with a top-level heading (ex: **# heading #**),
6f69ccd… andygoth 247 > the heading is omitted from the body of the document and becomes the
6f69ccd… andygoth 248 > document title displayed at the top of the Fossil page.
3bfdafe… andygoth 249
3bfdafe… andygoth 250 [daringfireball.net]: http://daringfireball.net/projects/markdown/syntax
0ae2dbd… drh 251
f4dc114… drh 252 <a name="intermap"></a>
5061599… george 253 ## Interwiki Tag [Map](/intermap)

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button