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 42can <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 53document should be publishable as-is, as plain text, without looking 54like it's been marked up with tags or formatting instructions. While 55Markdown's syntax has been influenced by several existing text-to-HTML 56filters -- 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 58inspiration 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 61characters, which punctuation characters have been carefully chosen so 62as to look like what they mean. E.g., asterisks around a word actually 63look like *emphasis*. Markdown lists look like, well, lists. Even 64blockquotes look like quoted passages of text, assuming you've ever 65used 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 70format for <em>writing</em> for the web.</p> 71 72<p>Markdown is not a replacement for HTML, or even close to it. Its 73syntax is very small, corresponding only to a very small subset of 74HTML tags. The idea is <em>not</em> to create a syntax that makes it easier 75to insert HTML tags. In my opinion, HTML tags are already easy to 76insert. The idea for Markdown is to make it easy to read, write, and 77edit prose. HTML is a <em>publishing</em> format; Markdown is a <em>writing</em> 78format. Thus, Markdown's formatting syntax only addresses issues that 79can be conveyed in plain text.</p> 80 81<p>For any markup that is not covered by Markdown's syntax, you simply 82use HTML itself. There's no need to preface it or delimit it to 83indicate that you're switching from Markdown to HTML; you just use 84the 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 88content by blank lines, and the start and end tags of the block should 89not be indented with tabs or spaces. Markdown is smart enough not 90to 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 102This is another regular paragraph. 103</code></pre> 104 105<p>Note that Markdown formatting syntax is not processed within block-level 106HTML tags. E.g., you can't use Markdown-style <code>*emphasis*</code> inside an 107HTML block.</p> 108 109<p>Span-level HTML tags -- e.g. <code><span></code>, <code><cite></code>, or <code><del></code> -- can be 110used anywhere in a Markdown paragraph, list item, or header. If you 111want, you can even use HTML tags instead of Markdown formatting; e.g. if 112you'd prefer to use HTML <code><a></code> or <code><img></code> tags instead of Markdown's 113link or image syntax, go right ahead.</p> 114 115<p>Unlike block-level HTML tags, Markdown syntax <em>is</em> processed within 116span-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> 121and <code>&</code>. Left angle brackets are used to start tags; ampersands are 122used to denote HTML entities. If you want to use them as literal 123characters, 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 127write about 'AT&T', you need to write '<code>AT&amp;T</code>'. You even need to 128escape 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 139forget, and is probably the single most common source of HTML validation 140errors in otherwise well-marked-up web sites.</p> 141 142<p>Markdown allows you to use these characters naturally, taking care of 143all the necessary escaping for you. If you use an ampersand as part of 144an HTML entity, it remains unchanged; otherwise it will be translated 145into <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 163angle brackets as delimiters for HTML tags, Markdown will treat them as 164such. 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 175ampersands are <em>always</em> encoded automatically. This makes it easy to use 176Markdown to write about HTML code. (As opposed to raw HTML, which is a 177terrible format for writing about HTML syntax, because every single <code><</code> 178and <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 187by one or more blank lines. (A blank line is any line that looks like a 188blank line -- a line containing nothing but spaces or tabs is considered 189blank.) 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 192that Markdown supports "hard-wrapped" text paragraphs. This differs 193significantly from most other text-to-HTML formatters (including Movable 194Type's "Convert Line Breaks" option) which translate every line break 195character 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 198end 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. 202Markdown's email-style <a href="#blockquote">blockquoting</a> and multi-paragraph <a href="#list">list items</a> 203work 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 210headers) and dashes (for second-level headers). For example:</p> 211 212<pre><code>This is an H1 213============= 214 215This 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, 222corresponding 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 232cosmetic -- you can use this if you think it looks better. The 233closing hashes don't even need to match the number of hashes 234used to open the header. (The number of opening hashes 235determines 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 247familiar with quoting passages of text in an email message, then you 248know how to create a blockquote in Markdown. It looks best if you hard 249wrap 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 260line of a hard-wrapped paragraph:</p> 261 262<pre><code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, 263consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 264Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 265 266> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse 267id sem consectetuer libero luctus adipiscing. 268</code></pre> 269 270<p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by 271adding 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, 281and 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 294example, with BBEdit, you can make a selection and choose Increase 295Quote 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 3262. McHale 3273. Parish 328</code></pre> 329 330<p>It's important to note that the actual numbers you use to mark the 331list have no effect on the HTML output Markdown produces. The HTML 332Markdown 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 3441. McHale 3451. Parish 346</code></pre> 347 348<p>or even:</p> 349 350<pre><code>3. Bird 3511. McHale 3528. Parish 353</code></pre> 354 355<p>you'd get the exact same HTML output. The point is, if you want to, 356you can use ordinal numbers in your ordered Markdown lists, so that 357the numbers in your source match the numbers in your published HTML. 358But 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 361list with the number 1. At some point in the future, Markdown may support 362starting ordered lists at an arbitrary number.</p> 363 364<p>List markers typically start at the left margin, but may be indented by 365up to three spaces. List markers must be followed by one or more spaces 366or 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. 380Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, 381viverra nec, fringilla in, laoreet vitae, risus. 382* Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 383Suspendisse id sem consectetuer libero luctus adipiscing. 384</code></pre> 385 386<p>If list items are separated by blank lines, Markdown will wrap the 387items 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 417paragraph in a list item must be intended by either 4 spaces 418or 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 4282. Suspendisse id sem consectetuer libero luctus adipiscing. 429</code></pre> 430 431<p>It looks nice if you indent every line of the subsequent 432paragraphs, but here again, Markdown will allow you to be 433lazy:</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 438only required to indent the first line. Lorem ipsum dolor 439sit 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> 445delimiters 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 454to 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 462accident, 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 468line. 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 476markup source code. Rather than forming normal paragraphs, the lines 477of a code block are interpreted literally. Markdown wraps a code block 478in 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 481block 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 497line 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 512end 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>) 520are automatically converted into HTML entities. This makes it very 521easy to include example HTML source code using Markdown -- just paste 522it and indent it, and Markdown will handle the hassle of encoding the 523ampersands 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., 539asterisks are just literal asterisks within a code block. This means 540it'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 545more hyphens, asterisks, or underscores on a line by themselves. If you 546wish, you may use spaces between the hyphens or asterisks. Each of the 547following 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 573after the link text's closing square bracket. Inside the parentheses, 574put the URL where you want the link to point, along with an <em>optional</em> 575title 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"> 585an example</a> inline link.</p> 586 587<p><a href="http://example.net/">This link</a> has no 588title attribute.</p> 589</code></pre> 590 591<p>If you're referring to a local resource on the same server, you can 592use 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 598which 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, 609on 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 618indented 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 623in 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 632or 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 639processing, 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 650link, in which case the link text itself is used as the name. 651Just 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 663multiple 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 674tend to put them immediately after each paragraph in which they're 675used, but if you want, you can put them all at the end of your 676document, 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/" 701title="Google">Google</a> than from 702<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a> 703or <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 707Markdown's inline link style:</p> 708 709<pre><code>I get 10 times more traffic from [Google](http://google.com/ "Google") 710than 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 715write. The point is that with reference-style links, your document 716source is vastly more readable. Compare the above examples: using 717reference-style links, the paragraph itself is only 81 characters 718long; with inline-style links, it's 176 characters; and as raw HTML, 719it's 234 characters. In the raw HTML, there's more markup than there 720is text.</p> 721 722<p>With Markdown's reference-style links, a source document much more 723closely resembles the final output, as rendered in a browser. By 724allowing you to move the markup-related metadata out of the paragraph, 725you can add links without interrupting the narrative flow of your 726prose.</p> 727 728<h3 id="em">Emphasis</h3> 729 730<p>Markdown treats asterisks (<code>*</code>) and underscores (<code>_</code>) as indicators of 731emphasis. Text wrapped with one <code>*</code> or <code>_</code> will be wrapped with an 732HTML <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 756the 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 764literal asterisk or underscore.</p> 765 766<p>To produce a literal asterisk or underscore at a position where it 767would otherwise be used as an emphasis delimiter, you can backslash 768escape 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>). 776Unlike a pre-formatted code block, a code span indicates code within a 777normal 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 788multiple 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 -- 799one after the opening, one before the closing. This allows you to place 800literal backtick characters at the beginning or end of a code span:</p> 801 802<pre><code>A single backtick in a code span: `` ` `` 803 804A 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 815entities automatically, which makes it easy to include example HTML 816tags. 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 834equivalent 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 840placing images into a plain text document format.</p> 841 842<p>Markdown uses an image syntax that is intended to resemble the syntax 843for 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> 857attribute text for the image;</li> 858<li>followed by a set of parentheses, containing the URL or path to 859the image, and an optional <code>title</code> attribute enclosed in double 860or 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 869are 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 875dimensions of an image; if this is important to you, you can simply 876use 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 895Markdown will also perform a bit of randomized decimal and hex 896entity-encoding to help obscure your address from address-harvesting 897spambots. For example, Markdown will turn this:</p> 898 899<pre><code><address@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@example.com".</p> 911 912<p>(This sort of entity-encoding trick will indeed fool many, if not 913most, address-harvesting bots, but it definitely won't fool all of 914them. It's better than nothing, but an address published in this way 915will 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 920characters which would otherwise have special meaning in Markdown's 921formatting syntax. For example, if you wanted to surround a word with 922literal asterisks (instead of an HTML <code><em></code> tag), you can backslashes 923before 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
