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