aleph1.co.uk Git - yaffs-website/blob - vendor/cebe/markdown/tests/markdown-data/md1_markdown_documentation_basics.md

   1 Markdown: Basics
   2 ================
   3
   4 <ul id="ProjectSubmenu">
   5     <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
   6     <li><a class="selected" title="Markdown Basics">Basics</a></li>
   7     <li><a href="/projects/markdown/syntax" title="Markdown Syntax Documentation">Syntax</a></li>
   8     <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
   9     <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
  10 </ul>
  11
  12
  13 Getting the Gist of Markdown's Formatting Syntax
  14 ------------------------------------------------
  15
  16 This page offers a brief overview of what it's like to use Markdown.
  17 The [syntax page] [s] provides complete, detailed documentation for
  18 every feature, but Markdown should be very easy to pick up simply by
  19 looking at a few examples of it in action. The examples on this page
  20 are written in a before/after style, showing example syntax and the
  21 HTML output produced by Markdown.
  22
  23 It's also helpful to simply try Markdown out; the [Dingus] [d] is a
  24 web application that allows you type your own Markdown-formatted text
  25 and translate it to XHTML.
  26
  27 **Note:** This document is itself written using Markdown; you
  28 can [see the source for it by adding '.text' to the URL] [src].
  29
  30   [s]: /projects/markdown/syntax  "Markdown Syntax"
  31   [d]: /projects/markdown/dingus  "Markdown Dingus"
  32   [src]: /projects/markdown/basics.text
  33
  34
  35 ## Paragraphs, Headers, Blockquotes ##
  36
  37 A paragraph is simply one or more consecutive lines of text, separated
  38 by one or more blank lines. (A blank line is any line that looks like a
  39 blank line -- a line containing nothing spaces or tabs is considered
  40 blank.) Normal paragraphs should not be intended with spaces or tabs.
  41
  42 Markdown offers two styles of headers: *Setext* and *atx*.
  43 Setext-style headers for `<h1>` and `<h2>` are created by
  44 "underlining" with equal signs (`=`) and hyphens (`-`), respectively.
  45 To create an atx-style header, you put 1-6 hash marks (`#`) at the
  46 beginning of the line -- the number of hashes equals the resulting
  47 HTML header level.
  48
  49 Blockquotes are indicated using email-style '`>`' angle brackets.
  50
  51 Markdown:
  52
  53     A First Level Header
  54     ====================
  55
  56     A Second Level Header
  57     ---------------------
  58
  59     Now is the time for all good men to come to
  60     the aid of their country. This is just a
  61     regular paragraph.
  62
  63     The quick brown fox jumped over the lazy
  64     dog's back.
  65
  66     ### Header 3
  67
  68     > This is a blockquote.
  69     >
  70     > This is the second paragraph in the blockquote.
  71     >
  72     > ## This is an H2 in a blockquote
  73
  74
  75 Output:
  76
  77     <h1>A First Level Header</h1>
  78
  79     <h2>A Second Level Header</h2>
  80
  81     <p>Now is the time for all good men to come to
  82     the aid of their country. This is just a
  83     regular paragraph.</p>
  84
  85     <p>The quick brown fox jumped over the lazy
  86     dog's back.</p>
  87
  88     <h3>Header 3</h3>
  89
  90     <blockquote>
  91         <p>This is a blockquote.</p>
  92
  93         <p>This is the second paragraph in the blockquote.</p>
  94
  95         <h2>This is an H2 in a blockquote</h2>
  96     </blockquote>
  97
  98
  99
 100 ### Phrase Emphasis ###
 101
 102 Markdown uses asterisks and underscores to indicate spans of emphasis.
 103
 104 Markdown:
 105
 106     Some of these words *are emphasized*.
 107     Some of these words _are emphasized also_.
 108
 109     Use two asterisks for **strong emphasis**.
 110     Or, if you prefer, __use two underscores instead__.
 111
 112 Output:
 113
 114     <p>Some of these words <em>are emphasized</em>.
 115     Some of these words <em>are emphasized also</em>.</p>
 116
 117     <p>Use two asterisks for <strong>strong emphasis</strong>.
 118     Or, if you prefer, <strong>use two underscores instead</strong>.</p>
 119
 120
 121
 122 ## Lists ##
 123
 124 Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
 125 `+`, and `-`) as list markers. These three markers are
 126 interchangable; this:
 127
 128     *   Candy.
 129     *   Gum.
 130     *   Booze.
 131
 132 this:
 133
 134     +   Candy.
 135     +   Gum.
 136     +   Booze.
 137
 138 and this:
 139
 140     -   Candy.
 141     -   Gum.
 142     -   Booze.
 143
 144 all produce the same output:
 145
 146     <ul>
 147     <li>Candy.</li>
 148     <li>Gum.</li>
 149     <li>Booze.</li>
 150     </ul>
 151
 152 Ordered (numbered) lists use regular numbers, followed by periods, as
 153 list markers:
 154
 155     1.  Red
 156     2.  Green
 157     3.  Blue
 158
 159 Output:
 160
 161     <ol>
 162     <li>Red</li>
 163     <li>Green</li>
 164     <li>Blue</li>
 165     </ol>
 166
 167 If you put blank lines between items, you'll get `<p>` tags for the
 168 list item text. You can create multi-paragraph list items by indenting
 169 the paragraphs by 4 spaces or 1 tab:
 170
 171     *   A list item.
 172
 173         With multiple paragraphs.
 174
 175     *   Another item in the list.
 176
 177 Output:
 178
 179     <ul>
 180     <li><p>A list item.</p>
 181     <p>With multiple paragraphs.</p></li>
 182     <li><p>Another item in the list.</p></li>
 183     </ul>
 184
 185
 186
 187 ### Links ###
 188
 189 Markdown supports two styles for creating links: *inline* and
 190 *reference*. With both styles, you use square brackets to delimit the
 191 text you want to turn into a link.
 192
 193 Inline-style links use parentheses immediately after the link text.
 194 For example:
 195
 196     This is an [example link](http://example.com/).
 197
 198 Output:
 199
 200     <p>This is an <a href="http://example.com/">
 201     example link</a>.</p>
 202
 203 Optionally, you may include a title attribute in the parentheses:
 204
 205     This is an [example link](http://example.com/ "With a Title").
 206
 207 Output:
 208
 209     <p>This is an <a href="http://example.com/" title="With a Title">
 210     example link</a>.</p>
 211
 212 Reference-style links allow you to refer to your links by names, which
 213 you define elsewhere in your document:
 214
 215     I get 10 times more traffic from [Google][1] than from
 216     [Yahoo][2] or [MSN][3].
 217
 218     [1]: http://google.com/        "Google"
 219     [2]: http://search.yahoo.com/  "Yahoo Search"
 220     [3]: http://search.msn.com/    "MSN Search"
 221
 222 Output:
 223
 224     <p>I get 10 times more traffic from <a href="http://google.com/"
 225     title="Google">Google</a> than from <a href="http://search.yahoo.com/"
 226     title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
 227     title="MSN Search">MSN</a>.</p>
 228
 229 The title attribute is optional. Link names may contain letters,
 230 numbers and spaces, but are *not* case sensitive:
 231
 232     I start my morning with a cup of coffee and
 233     [The New York Times][NY Times].
 234
 235     [ny times]: http://www.nytimes.com/
 236
 237 Output:
 238
 239     <p>I start my morning with a cup of coffee and
 240     <a href="http://www.nytimes.com/">The New York Times</a>.</p>
 241
 242
 243 ### Images ###
 244
 245 Image syntax is very much like link syntax.
 246
 247 Inline (titles are optional):
 248
 249     ![alt text](/path/to/img.jpg "Title")
 250
 251 Reference-style:
 252
 253     ![alt text][id]
 254
 255     [id]: /path/to/img.jpg "Title"
 256
 257 Both of the above examples produce the same output:
 258
 259     <img src="/path/to/img.jpg" alt="alt text" title="Title" />
 260
 261
 262
 263 ### Code ###
 264
 265 In a regular paragraph, you can create code span by wrapping text in
 266 backtick quotes. Any ampersands (`&`) and angle brackets (`<` or
 267 `>`) will automatically be translated into HTML entities. This makes
 268 it easy to use Markdown to write about HTML example code:
 269
 270     I strongly recommend against using any `<blink>` tags.
 271
 272     I wish SmartyPants used named entities like `&mdash;`
 273     instead of decimal-encoded entites like `&#8212;`.
 274
 275 Output:
 276
 277     <p>I strongly recommend against using any
 278     <code>&lt;blink&gt;</code> tags.</p>
 279
 280     <p>I wish SmartyPants used named entities like
 281     <code>&amp;mdash;</code> instead of decimal-encoded
 282     entites like <code>&amp;#8212;</code>.</p>
 283
 284
 285 To specify an entire block of pre-formatted code, indent every line of
 286 the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`,
 287 and `>` characters will be escaped automatically.
 288
 289 Markdown:
 290
 291     If you want your page to validate under XHTML 1.0 Strict,
 292     you've got to put paragraph tags in your blockquotes:
 293
 294         <blockquote>
 295             <p>For example.</p>
 296         </blockquote>
 297
 298 Output:
 299
 300     <p>If you want your page to validate under XHTML 1.0 Strict,
 301     you've got to put paragraph tags in your blockquotes:</p>
 302
 303     <pre><code>&lt;blockquote&gt;
 304         &lt;p&gt;For example.&lt;/p&gt;
 305     &lt;/blockquote&gt;
 306     </code></pre>