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