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><div></code>, 87 <code><table></code>, <code><pre></code>, <code><p></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><p></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 <table> 97 <tr> 98 <td>Foo</td> 99 </tr> 100 </table> 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><span></code>, <code><cite></code>, or <code><del></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><a></code> or <code><img></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><</code> 121 and <code>&</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>&lt;</code>, and 124 <code>&amp;</code>.</p> 125 126 <p>Ampersands in particular are bedeviling for web writers. If you want to 127 write about 'AT&T', you need to write '<code>AT&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&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;</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>&copy; 150 </code></pre> 151 152 <p>and Markdown will leave it alone. But if you write:</p> 153 154 <pre><code>AT&T 155 </code></pre> 156 157 <p>Markdown will translate it to:</p> 158 159 <pre><code>AT&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 < 5 167 </code></pre> 168 169 <p>Markdown will translate it to:</p> 170 171 <pre><code>4 &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><</code> 178 and <code>&</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><br /></code> tag.</p> 196 197 <p>When you <em>do</em> want to insert a <code><br /></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><br /></code>, but a simplistic 201 "every line break is a <code><br /></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>></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>></code> before every line:</p> 250 251 <pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, 252 > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 253 > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 254 > 255 > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse 256 > id sem consectetuer libero luctus adipiscing. 257 </code></pre> 258 259 <p>Markdown allows you to be lazy and only put the <code>></code> before the first 260 line of a hard-wrapped paragraph:</p> 261 262 <pre><code>> 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 > 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>></code>:</p> 272 273 <pre><code>> This is the first level of quoting. 274 > 275 > > This is nested blockquote. 276 > 277 > 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>> ## 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 </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><ol> 335 <li>Bird</li> 336 <li>McHale</li> 337 <li>Parish</li> 338 </ol> 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><p></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><ul> 396 <li>Bird</li> 397 <li>Magic</li> 398 </ul> 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><ul> 411 <li><p>Bird</p></li> 412 <li><p>Magic</p></li> 413 </ul> 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>></code> 445 delimiters need to be indented:</p> 446 447 <pre><code>* A list item with a blockquote: 448 449 > This is a blockquote 450 > 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 <code goes here> 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><pre></code> and <code><code></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><p>This is a normal paragraph:</p> 491 492 <pre><code>This is a code block. 493 </code></pre> 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><p>Here is an example of AppleScript:</p> 509 510 <pre><code>tell application "Foo" 511 beep 512 end tell 513 </code></pre> 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>&</code>) and angle brackets (<code><</code> and <code>></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> <div class="footer"> 526 &copy; 2004 Foo Corporation 527 </div> 528 </code></pre> 529 530 <p>will turn into:</p> 531 532 <pre><code><pre><code>&lt;div class="footer"&gt; 533 &amp;copy; 2004 Foo Corporation 534 &lt;/div&gt; 535 </code></pre> 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><hr /></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><p>This is <a href="http://example.com/" title="Title"> 585 an example</a> inline link.</p> 586 587 <p><a href="http://example.net/">This link</a> has no 588 title attribute.</p> 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]: <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><p>I get 10 times more traffic from <a href="http://google.com/" 701 title="Google">Google</a> than from 702 <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a> 703 or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p> 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><em></code> tag; double <code>*</code>'s or <code>_</code>'s will be wrapped with an HTML 733 <code><strong></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><em>single asterisks</em> 747 748 <em>single underscores</em> 749 750 <strong>double asterisks</strong> 751 752 <strong>double underscores</strong> 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><p>Use the <code>printf()</code> function.</p> 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><p><code>There is a literal backtick (`) here.</code></p> 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><p>A single backtick in a code span: <code>`</code></p> 810 811 <p>A backtick-delimited string in a code span: <code>`foo`</code></p> 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 `<blink>` tags. 819 </code></pre> 820 821 <p>into:</p> 822 823 <pre><code><p>Please don't use any <code>&lt;blink&gt;</code> tags.</p> 824 </code></pre> 825 826 <p>You can write this:</p> 827 828 <pre><code>`&#8212;` is the decimal-encoded equivalent of `&mdash;`. 829 </code></pre> 830 831 <p>to produce:</p> 832 833 <pre><code><p><code>&amp;#8212;</code> is the decimal-encoded 834 equivalent of <code>&amp;mdash;</code>.</p> 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> 848 849  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><img></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><http://example.com/>; 887 </code></pre> 888 889 <p>Markdown will turn this into:</p> 890 891 <pre><code><a href="http://example.com/">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><address (a] example.com> 900 </code></pre> 901 902 <p>into something like this:</p> 903 904 <pre><code><a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65; 905 &#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111; 906 &#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61; 907 &#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a> 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><em></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
