Home | History | Annotate | Download | only in markdown-test
      1 Markdown: Syntax
      2 ================
      3 
      4 <ul id="ProjectSubmenu">
      5     <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
      6     <li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
      7     <li><a class="selected" 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 *   [Overview](#overview)
     14     *   [Philosophy](#philosophy)
     15     *   [Inline HTML](#html)
     16     *   [Automatic Escaping for Special Characters](#autoescape)
     17 *   [Block Elements](#block)
     18     *   [Paragraphs and Line Breaks](#p)
     19     *   [Headers](#header)
     20     *   [Blockquotes](#blockquote)
     21     *   [Lists](#list)
     22     *   [Code Blocks](#precode)
     23     *   [Horizontal Rules](#hr)
     24 *   [Span Elements](#span)
     25     *   [Links](#link)
     26     *   [Emphasis](#em)
     27     *   [Code](#code)
     28     *   [Images](#img)
     29 *   [Miscellaneous](#misc)
     30     *   [Backslash Escapes](#backslash)
     31     *   [Automatic Links](#autolink)
     32 
     33 
     34 **Note:** This document is itself written using Markdown; you
     35 can [see the source for it by adding '.text' to the URL][src].
     36 
     37   [src]: /projects/markdown/syntax.text
     38 
     39 * * *
     40 
     41 <h2 id="overview">Overview</h2>
     42 
     43 <h3 id="philosophy">Philosophy</h3>
     44 
     45 Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
     46 
     47 Readability, however, is emphasized above all else. A Markdown-formatted
     48 document should be publishable as-is, as plain text, without looking
     49 like it's been marked up with tags or formatting instructions. While
     50 Markdown's syntax has been influenced by several existing text-to-HTML
     51 filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
     52 [Grutatext] [5], and [EtText] [6] -- the single biggest source of
     53 inspiration for Markdown's syntax is the format of plain text email.
     54 
     55   [1]: http://docutils.sourceforge.net/mirror/setext.html
     56   [2]: http://www.aaronsw.com/2002/atx/
     57   [3]: http://textism.com/tools/textile/
     58   [4]: http://docutils.sourceforge.net/rst.html
     59   [5]: http://www.triptico.com/software/grutatxt.html
     60   [6]: http://ettext.taint.org/doc/
     61 
     62 To this end, Markdown's syntax is comprised entirely of punctuation
     63 characters, which punctuation characters have been carefully chosen so
     64 as to look like what they mean. E.g., asterisks around a word actually
     65 look like \*emphasis\*. Markdown lists look like, well, lists. Even
     66 blockquotes look like quoted passages of text, assuming you've ever
     67 used email.
     68 
     69 
     70 
     71 <h3 id="html">Inline HTML</h3>
     72 
     73 Markdown's syntax is intended for one purpose: to be used as a
     74 format for *writing* for the web.
     75 
     76 Markdown is not a replacement for HTML, or even close to it. Its
     77 syntax is very small, corresponding only to a very small subset of
     78 HTML tags. The idea is *not* to create a syntax that makes it easier
     79 to insert HTML tags. In my opinion, HTML tags are already easy to
     80 insert. The idea for Markdown is to make it easy to read, write, and
     81 edit prose. HTML is a *publishing* format; Markdown is a *writing*
     82 format. Thus, Markdown's formatting syntax only addresses issues that
     83 can be conveyed in plain text.
     84 
     85 For any markup that is not covered by Markdown's syntax, you simply
     86 use HTML itself. There's no need to preface it or delimit it to
     87 indicate that you're switching from Markdown to HTML; you just use
     88 the tags.
     89 
     90 The only restrictions are that block-level HTML elements -- e.g. `<div>`,
     91 `<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
     92 content by blank lines, and the start and end tags of the block should
     93 not be indented with tabs or spaces. Markdown is smart enough not
     94 to add extra (unwanted) `<p>` tags around HTML block-level tags.
     95 
     96 For example, to add an HTML table to a Markdown article:
     97 
     98     This is a regular paragraph.
     99 
    100     <table>
    101         <tr>
    102             <td>Foo</td>
    103         </tr>
    104     </table>
    105 
    106     This is another regular paragraph.
    107 
    108 Note that Markdown formatting syntax is not processed within block-level
    109 HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
    110 HTML block.
    111 
    112 Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
    113 used anywhere in a Markdown paragraph, list item, or header. If you
    114 want, you can even use HTML tags instead of Markdown formatting; e.g. if
    115 you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
    116 link or image syntax, go right ahead.
    117 
    118 Unlike block-level HTML tags, Markdown syntax *is* processed within
    119 span-level tags.
    120 
    121 
    122 <h3 id="autoescape">Automatic Escaping for Special Characters</h3>
    123 
    124 In HTML, there are two characters that demand special treatment: `<`
    125 and `&`. Left angle brackets are used to start tags; ampersands are
    126 used to denote HTML entities. If you want to use them as literal
    127 characters, you must escape them as entities, e.g. `&lt;`, and
    128 `&amp;`.
    129 
    130 Ampersands in particular are bedeviling for web writers. If you want to
    131 write about 'AT&T', you need to write '`AT&amp;T`'. You even need to
    132 escape ampersands within URLs. Thus, if you want to link to:
    133 
    134     http://images.google.com/images?num=30&q=larry+bird
    135 
    136 you need to encode the URL as:
    137 
    138     http://images.google.com/images?num=30&q=larry+bird
    139 
    140 in your anchor tag `href` attribute. Needless to say, this is easy to
    141 forget, and is probably the single most common source of HTML validation
    142 errors in otherwise well-marked-up web sites.
    143 
    144 Markdown allows you to use these characters naturally, taking care of
    145 all the necessary escaping for you. If you use an ampersand as part of
    146 an HTML entity, it remains unchanged; otherwise it will be translated
    147 into `&amp;`.
    148 
    149 So, if you want to include a copyright symbol in your article, you can write:
    150 
    151     &copy;
    152 
    153 and Markdown will leave it alone. But if you write:
    154 
    155     AT&T
    156 
    157 Markdown will translate it to:
    158 
    159     AT&amp;T
    160 
    161 Similarly, because Markdown supports [inline HTML](#html), if you use
    162 angle brackets as delimiters for HTML tags, Markdown will treat them as
    163 such. But if you write:
    164 
    165     4 < 5
    166 
    167 Markdown will translate it to:
    168 
    169     4 &lt; 5
    170 
    171 However, inside Markdown code spans and blocks, angle brackets and
    172 ampersands are *always* encoded automatically. This makes it easy to use
    173 Markdown to write about HTML code. (As opposed to raw HTML, which is a
    174 terrible format for writing about HTML syntax, because every single `<`
    175 and `&` in your example code needs to be escaped.)
    176 
    177 
    178 * * *
    179 
    180 
    181 <h2 id="block">Block Elements</h2>
    182 
    183 
    184 <h3 id="p">Paragraphs and Line Breaks</h3>
    185 
    186 A paragraph is simply one or more consecutive lines of text, separated
    187 by one or more blank lines. (A blank line is any line that looks like a
    188 blank line -- a line containing nothing but spaces or tabs is considered
    189 blank.) Normal paragraphs should not be intended with spaces or tabs.
    190 
    191 The implication of the "one or more consecutive lines of text" rule is
    192 that Markdown supports "hard-wrapped" text paragraphs. This differs
    193 significantly from most other text-to-HTML formatters (including Movable
    194 Type's "Convert Line Breaks" option) which translate every line break
    195 character in a paragraph into a `<br />` tag.
    196 
    197 When you *do* want to insert a `<br />` break tag using Markdown, you
    198 end a line with two or more spaces, then type return.
    199 
    200 Yes, this takes a tad more effort to create a `<br />`, but a simplistic
    201 "every line break is a `<br />`" rule wouldn't work for Markdown.
    202 Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
    203 work best -- and look better -- when you format them with hard breaks.
    204 
    205   [bq]: #blockquote
    206   [l]:  #list
    207 
    208 
    209 
    210 <h3 id="header">Headers</h3>
    211 
    212 Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
    213 
    214 Setext-style headers are "underlined" using equal signs (for first-level
    215 headers) and dashes (for second-level headers). For example:
    216 
    217     This is an H1
    218     =============
    219 
    220     This is an H2
    221     -------------
    222 
    223 Any number of underlining `=`'s or `-`'s will work.
    224 
    225 Atx-style headers use 1-6 hash characters at the start of the line,
    226 corresponding to header levels 1-6. For example:
    227 
    228     # This is an H1
    229 
    230     ## This is an H2
    231 
    232     ###### This is an H6
    233 
    234 Optionally, you may "close" atx-style headers. This is purely
    235 cosmetic -- you can use this if you think it looks better. The
    236 closing hashes don't even need to match the number of hashes
    237 used to open the header. (The number of opening hashes
    238 determines the header level.) :
    239 
    240     # This is an H1 #
    241 
    242     ## This is an H2 ##
    243 
    244     ### This is an H3 ######
    245 
    246 
    247 <h3 id="blockquote">Blockquotes</h3>
    248 
    249 Markdown uses email-style `>` characters for blockquoting. If you're
    250 familiar with quoting passages of text in an email message, then you
    251 know how to create a blockquote in Markdown. It looks best if you hard
    252 wrap the text and put a `>` before every line:
    253 
    254     > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
    255     > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
    256     > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
    257     > 
    258     > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
    259     > id sem consectetuer libero luctus adipiscing.
    260 
    261 Markdown allows you to be lazy and only put the `>` before the first
    262 line of a hard-wrapped paragraph:
    263 
    264     > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
    265     consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
    266     Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
    267 
    268     > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
    269     id sem consectetuer libero luctus adipiscing.
    270 
    271 Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
    272 adding additional levels of `>`:
    273 
    274     > This is the first level of quoting.
    275     >
    276     > > This is nested blockquote.
    277     >
    278     > Back to the first level.
    279 
    280 Blockquotes can contain other Markdown elements, including headers, lists,
    281 and code blocks:
    282 
    283 	> ## This is a header.
    284 	> 
    285 	> 1.   This is the first list item.
    286 	> 2.   This is the second list item.
    287 	> 
    288 	> Here's some example code:
    289 	> 
    290 	>     return shell_exec("echo $input | $markdown_script");
    291 
    292 Any decent text editor should make email-style quoting easy. For
    293 example, with BBEdit, you can make a selection and choose Increase
    294 Quote Level from the Text menu.
    295 
    296 
    297 <h3 id="list">Lists</h3>
    298 
    299 Markdown supports ordered (numbered) and unordered (bulleted) lists.
    300 
    301 Unordered lists use asterisks, pluses, and hyphens -- interchangably
    302 -- as list markers:
    303 
    304     *   Red
    305     *   Green
    306     *   Blue
    307 
    308 is equivalent to:
    309 
    310     +   Red
    311     +   Green
    312     +   Blue
    313 
    314 and:
    315 
    316     -   Red
    317     -   Green
    318     -   Blue
    319 
    320 Ordered lists use numbers followed by periods:
    321 
    322     1.  Bird
    323     2.  McHale
    324     3.  Parish
    325 
    326 It's important to note that the actual numbers you use to mark the
    327 list have no effect on the HTML output Markdown produces. The HTML
    328 Markdown produces from the above list is:
    329 
    330     <ol>
    331     <li>Bird</li>
    332     <li>McHale</li>
    333     <li>Parish</li>
    334     </ol>
    335 
    336 If you instead wrote the list in Markdown like this:
    337 
    338     1.  Bird
    339     1.  McHale
    340     1.  Parish
    341 
    342 or even:
    343 
    344     3. Bird
    345     1. McHale
    346     8. Parish
    347 
    348 you'd get the exact same HTML output. The point is, if you want to,
    349 you can use ordinal numbers in your ordered Markdown lists, so that
    350 the numbers in your source match the numbers in your published HTML.
    351 But if you want to be lazy, you don't have to.
    352 
    353 If you do use lazy list numbering, however, you should still start the
    354 list with the number 1. At some point in the future, Markdown may support
    355 starting ordered lists at an arbitrary number.
    356 
    357 List markers typically start at the left margin, but may be indented by
    358 up to three spaces. List markers must be followed by one or more spaces
    359 or a tab.
    360 
    361 To make lists look nice, you can wrap items with hanging indents:
    362 
    363     *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    364         Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    365         viverra nec, fringilla in, laoreet vitae, risus.
    366     *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    367         Suspendisse id sem consectetuer libero luctus adipiscing.
    368 
    369 But if you want to be lazy, you don't have to:
    370 
    371     *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
    372     Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
    373     viverra nec, fringilla in, laoreet vitae, risus.
    374     *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
    375     Suspendisse id sem consectetuer libero luctus adipiscing.
    376 
    377 If list items are separated by blank lines, Markdown will wrap the
    378 items in `<p>` tags in the HTML output. For example, this input:
    379 
    380     *   Bird
    381     *   Magic
    382 
    383 will turn into:
    384 
    385     <ul>
    386     <li>Bird</li>
    387     <li>Magic</li>
    388     </ul>
    389 
    390 But this:
    391 
    392     *   Bird
    393 
    394     *   Magic
    395 
    396 will turn into:
    397 
    398     <ul>
    399     <li><p>Bird</p></li>
    400     <li><p>Magic</p></li>
    401     </ul>
    402 
    403 List items may consist of multiple paragraphs. Each subsequent
    404 paragraph in a list item must be intended by either 4 spaces
    405 or one tab:
    406 
    407     1.  This is a list item with two paragraphs. Lorem ipsum dolor
    408         sit amet, consectetuer adipiscing elit. Aliquam hendrerit
    409         mi posuere lectus.
    410 
    411         Vestibulum enim wisi, viverra nec, fringilla in, laoreet
    412         vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
    413         sit amet velit.
    414 
    415     2.  Suspendisse id sem consectetuer libero luctus adipiscing.
    416 
    417 It looks nice if you indent every line of the subsequent
    418 paragraphs, but here again, Markdown will allow you to be
    419 lazy:
    420 
    421     *   This is a list item with two paragraphs.
    422 
    423         This is the second paragraph in the list item. You're
    424     only required to indent the first line. Lorem ipsum dolor
    425     sit amet, consectetuer adipiscing elit.
    426 
    427     *   Another item in the same list.
    428 
    429 To put a blockquote within a list item, the blockquote's `>`
    430 delimiters need to be indented:
    431 
    432     *   A list item with a blockquote:
    433 
    434         > This is a blockquote
    435         > inside a list item.
    436 
    437 To put a code block within a list item, the code block needs
    438 to be indented *twice* -- 8 spaces or two tabs:
    439 
    440     *   A list item with a code block:
    441 
    442             <code goes here>
    443 
    444 
    445 It's worth noting that it's possible to trigger an ordered list by
    446 accident, by writing something like this:
    447 
    448     1986. What a great season.
    449 
    450 In other words, a *number-period-space* sequence at the beginning of a
    451 line. To avoid this, you can backslash-escape the period:
    452 
    453     1986\. What a great season.
    454 
    455 
    456 
    457 <h3 id="precode">Code Blocks</h3>
    458 
    459 Pre-formatted code blocks are used for writing about programming or
    460 markup source code. Rather than forming normal paragraphs, the lines
    461 of a code block are interpreted literally. Markdown wraps a code block
    462 in both `<pre>` and `<code>` tags.
    463 
    464 To produce a code block in Markdown, simply indent every line of the
    465 block by at least 4 spaces or 1 tab. For example, given this input:
    466 
    467     This is a normal paragraph:
    468 
    469         This is a code block.
    470 
    471 Markdown will generate:
    472 
    473     <p>This is a normal paragraph:</p>
    474 
    475     <pre><code>This is a code block.
    476     </code></pre>
    477 
    478 One level of indentation -- 4 spaces or 1 tab -- is removed from each
    479 line of the code block. For example, this:
    480 
    481     Here is an example of AppleScript:
    482 
    483         tell application "Foo"
    484             beep
    485         end tell
    486 
    487 will turn into:
    488 
    489     <p>Here is an example of AppleScript:</p>
    490 
    491     <pre><code>tell application "Foo"
    492         beep
    493     end tell
    494     </code></pre>
    495 
    496 A code block continues until it reaches a line that is not indented
    497 (or the end of the article).
    498 
    499 Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
    500 are automatically converted into HTML entities. This makes it very
    501 easy to include example HTML source code using Markdown -- just paste
    502 it and indent it, and Markdown will handle the hassle of encoding the
    503 ampersands and angle brackets. For example, this:
    504 
    505         <div class="footer">
    506             &copy; 2004 Foo Corporation
    507         </div>
    508 
    509 will turn into:
    510 
    511     <pre><code>&lt;div class="footer"&gt;
    512         &amp;copy; 2004 Foo Corporation
    513     &lt;/div&gt;
    514     </code></pre>
    515 
    516 Regular Markdown syntax is not processed within code blocks. E.g.,
    517 asterisks are just literal asterisks within a code block. This means
    518 it's also easy to use Markdown to write about Markdown's own syntax.
    519 
    520 
    521 
    522 <h3 id="hr">Horizontal Rules</h3>
    523 
    524 You can produce a horizontal rule tag (`<hr />`) by placing three or
    525 more hyphens, asterisks, or underscores on a line by themselves. If you
    526 wish, you may use spaces between the hyphens or asterisks. Each of the
    527 following lines will produce a horizontal rule:
    528 
    529     * * *
    530 
    531     ***
    532 
    533     *****
    534 	
    535     - - -
    536 
    537     ---------------------------------------
    538 
    539 	_ _ _
    540 
    541 
    542 * * *
    543 
    544 <h2 id="span">Span Elements</h2>
    545 
    546 <h3 id="link">Links</h3>
    547 
    548 Markdown supports two style of links: *inline* and *reference*.
    549 
    550 In both styles, the link text is delimited by [square brackets].
    551 
    552 To create an inline link, use a set of regular parentheses immediately
    553 after the link text's closing square bracket. Inside the parentheses,
    554 put the URL where you want the link to point, along with an *optional*
    555 title for the link, surrounded in quotes. For example:
    556 
    557     This is [an example](http://example.com/ "Title") inline link.
    558 
    559     [This link](http://example.net/) has no title attribute.
    560 
    561 Will produce:
    562 
    563     <p>This is <a href="http://example.com/" title="Title">
    564     an example</a> inline link.</p>
    565 
    566     <p><a href="http://example.net/">This link</a> has no
    567     title attribute.</p>
    568 
    569 If you're referring to a local resource on the same server, you can
    570 use relative paths:
    571 
    572     See my [About](/about/) page for details.   
    573 
    574 Reference-style links use a second set of square brackets, inside
    575 which you place a label of your choosing to identify the link:
    576 
    577     This is [an example][id] reference-style link.
    578 
    579 You can optionally use a space to separate the sets of brackets:
    580 
    581     This is [an example] [id] reference-style link.
    582 
    583 Then, anywhere in the document, you define your link label like this,
    584 on a line by itself:
    585 
    586     [id]: http://example.com/  "Optional Title Here"
    587 
    588 That is:
    589 
    590 *   Square brackets containing the link identifier (optionally
    591     indented from the left margin using up to three spaces);
    592 *   followed by a colon;
    593 *   followed by one or more spaces (or tabs);
    594 *   followed by the URL for the link;
    595 *   optionally followed by a title attribute for the link, enclosed
    596     in double or single quotes.
    597 
    598 The link URL may, optionally, be surrounded by angle brackets:
    599 
    600     [id]: <http://example.com/>  "Optional Title Here"
    601 
    602 You can put the title attribute on the next line and use extra spaces
    603 or tabs for padding, which tends to look better with longer URLs:
    604 
    605     [id]: http://example.com/longish/path/to/resource/here
    606         "Optional Title Here"
    607 
    608 Link definitions are only used for creating links during Markdown
    609 processing, and are stripped from your document in the HTML output.
    610 
    611 Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:
    612 
    613 	[link text][a]
    614 	[link text][A]
    615 
    616 are equivalent.
    617 
    618 The *implicit link name* shortcut allows you to omit the name of the
    619 link, in which case the link text itself is used as the name.
    620 Just use an empty set of square brackets -- e.g., to link the word
    621 "Google" to the google.com web site, you could simply write:
    622 
    623 	[Google][]
    624 
    625 And then define the link:
    626 
    627 	[Google]: http://google.com/
    628 
    629 Because link names may contain spaces, this shortcut even works for
    630 multiple words in the link text:
    631 
    632 	Visit [Daring Fireball][] for more information.
    633 
    634 And then define the link:
    635 	
    636 	[Daring Fireball]: http://daringfireball.net/
    637 
    638 Link definitions can be placed anywhere in your Markdown document. I
    639 tend to put them immediately after each paragraph in which they're
    640 used, but if you want, you can put them all at the end of your
    641 document, sort of like footnotes.
    642 
    643 Here's an example of reference links in action:
    644 
    645     I get 10 times more traffic from [Google] [1] than from
    646     [Yahoo] [2] or [MSN] [3].
    647 
    648       [1]: http://google.com/        "Google"
    649       [2]: http://search.yahoo.com/  "Yahoo Search"
    650       [3]: http://search.msn.com/    "MSN Search"
    651 
    652 Using the implicit link name shortcut, you could instead write:
    653 
    654     I get 10 times more traffic from [Google][] than from
    655     [Yahoo][] or [MSN][].
    656 
    657       [google]: http://google.com/        "Google"
    658       [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
    659       [msn]:    http://search.msn.com/    "MSN Search"
    660 
    661 Both of the above examples will produce the following HTML output:
    662 
    663     <p>I get 10 times more traffic from <a href="http://google.com/"
    664     title="Google">Google</a> than from
    665     <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
    666     or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
    667 
    668 For comparison, here is the same paragraph written using
    669 Markdown's inline link style:
    670 
    671     I get 10 times more traffic from [Google](http://google.com/ "Google")
    672     than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
    673     [MSN](http://search.msn.com/ "MSN Search").
    674 
    675 The point of reference-style links is not that they're easier to
    676 write. The point is that with reference-style links, your document
    677 source is vastly more readable. Compare the above examples: using
    678 reference-style links, the paragraph itself is only 81 characters
    679 long; with inline-style links, it's 176 characters; and as raw HTML,
    680 it's 234 characters. In the raw HTML, there's more markup than there
    681 is text.
    682 
    683 With Markdown's reference-style links, a source document much more
    684 closely resembles the final output, as rendered in a browser. By
    685 allowing you to move the markup-related metadata out of the paragraph,
    686 you can add links without interrupting the narrative flow of your
    687 prose.
    688 
    689 
    690 <h3 id="em">Emphasis</h3>
    691 
    692 Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
    693 emphasis. Text wrapped with one `*` or `_` will be wrapped with an
    694 HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
    695 `<strong>` tag. E.g., this input:
    696 
    697     *single asterisks*
    698 
    699     _single underscores_
    700 
    701     **double asterisks**
    702 
    703     __double underscores__
    704 
    705 will produce:
    706 
    707     <em>single asterisks</em>
    708 
    709     <em>single underscores</em>
    710 
    711     <strong>double asterisks</strong>
    712 
    713     <strong>double underscores</strong>
    714 
    715 You can use whichever style you prefer; the lone restriction is that
    716 the same character must be used to open and close an emphasis span.
    717 
    718 Emphasis can be used in the middle of a word:
    719 
    720     un*fucking*believable
    721 
    722 But if you surround an `*` or `_` with spaces, it'll be treated as a
    723 literal asterisk or underscore.
    724 
    725 To produce a literal asterisk or underscore at a position where it
    726 would otherwise be used as an emphasis delimiter, you can backslash
    727 escape it:
    728 
    729     \*this text is surrounded by literal asterisks\*
    730 
    731 
    732 
    733 <h3 id="code">Code</h3>
    734 
    735 To indicate a span of code, wrap it with backtick quotes (`` ` ``).
    736 Unlike a pre-formatted code block, a code span indicates code within a
    737 normal paragraph. For example:
    738 
    739     Use the `printf()` function.
    740 
    741 will produce:
    742 
    743     <p>Use the <code>printf()</code> function.</p>
    744 
    745 To include a literal backtick character within a code span, you can use
    746 multiple backticks as the opening and closing delimiters:
    747 
    748     ``There is a literal backtick (`) here.``
    749 
    750 which will produce this:
    751 
    752     <p><code>There is a literal backtick (`) here.</code></p>
    753 
    754 The backtick delimiters surrounding a code span may include spaces --
    755 one after the opening, one before the closing. This allows you to place
    756 literal backtick characters at the beginning or end of a code span:
    757 
    758 	A single backtick in a code span: `` ` ``
    759 	
    760 	A backtick-delimited string in a code span: `` `foo` ``
    761 
    762 will produce:
    763 
    764 	<p>A single backtick in a code span: <code>`</code></p>
    765 	
    766 	<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
    767 
    768 With a code span, ampersands and angle brackets are encoded as HTML
    769 entities automatically, which makes it easy to include example HTML
    770 tags. Markdown will turn this:
    771 
    772     Please don't use any `<blink>` tags.
    773 
    774 into:
    775 
    776     <p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
    777 
    778 You can write this:
    779 
    780     `&#8212;` is the decimal-encoded equivalent of `&mdash;`.
    781 
    782 to produce:
    783 
    784     <p><code>&amp;#8212;</code> is the decimal-encoded
    785     equivalent of <code>&amp;mdash;</code>.</p>
    786 
    787 
    788 
    789 <h3 id="img">Images</h3>
    790 
    791 Admittedly, it's fairly difficult to devise a "natural" syntax for
    792 placing images into a plain text document format.
    793 
    794 Markdown uses an image syntax that is intended to resemble the syntax
    795 for links, allowing for two styles: *inline* and *reference*.
    796 
    797 Inline image syntax looks like this:
    798 
    799     ![Alt text](/path/to/img.jpg)
    800 
    801     ![Alt text](/path/to/img.jpg "Optional title")
    802 
    803 That is:
    804 
    805 *   An exclamation mark: `!`;
    806 *   followed by a set of square brackets, containing the `alt`
    807     attribute text for the image;
    808 *   followed by a set of parentheses, containing the URL or path to
    809     the image, and an optional `title` attribute enclosed in double
    810     or single quotes.
    811 
    812 Reference-style image syntax looks like this:
    813 
    814     ![Alt text][id]
    815 
    816 Where "id" is the name of a defined image reference. Image references
    817 are defined using syntax identical to link references:
    818 
    819     [id]: url/to/image  "Optional title attribute"
    820 
    821 As of this writing, Markdown has no syntax for specifying the
    822 dimensions of an image; if this is important to you, you can simply
    823 use regular HTML `<img>` tags.
    824 
    825 
    826 * * *
    827 
    828 
    829 <h2 id="misc">Miscellaneous</h2>
    830 
    831 <h3 id="autolink">Automatic Links</h3>
    832 
    833 Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:
    834 
    835     <http://example.com/>
    836     
    837 Markdown will turn this into:
    838 
    839     <a href="http://example.com/">http://example.com/</a>
    840 
    841 Automatic links for email addresses work similarly, except that
    842 Markdown will also perform a bit of randomized decimal and hex
    843 entity-encoding to help obscure your address from address-harvesting
    844 spambots. For example, Markdown will turn this:
    845 
    846     <address (a] example.com>
    847 
    848 into something like this:
    849 
    850     <a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
    851     &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
    852     &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
    853     &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
    854 
    855 which will render in a browser as a clickable link to "address (a] example.com".
    856 
    857 (This sort of entity-encoding trick will indeed fool many, if not
    858 most, address-harvesting bots, but it definitely won't fool all of
    859 them. It's better than nothing, but an address published in this way
    860 will probably eventually start receiving spam.)
    861 
    862 
    863 
    864 <h3 id="backslash">Backslash Escapes</h3>
    865 
    866 Markdown allows you to use backslash escapes to generate literal
    867 characters which would otherwise have special meaning in Markdown's
    868 formatting syntax. For example, if you wanted to surround a word with
    869 literal asterisks (instead of an HTML `<em>` tag), you can backslashes
    870 before the asterisks, like this:
    871 
    872     \*literal asterisks\*
    873 
    874 Markdown provides backslash escapes for the following characters:
    875 
    876     \   backslash
    877     `   backtick
    878     *   asterisk
    879     _   underscore
    880     {}  curly braces
    881     []  square brackets
    882     ()  parentheses
    883     #   hash mark
    884 	+	plus sign
    885 	-	minus sign (hyphen)
    886     .   dot
    887     !   exclamation mark
    888 
    889