basics.md

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