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