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 28Characters</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 57Markdown; you can <a href="/projects/markdown/syntax.text">see the 58source 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 63is feasible.</p> 64<p>Readability, however, is emphasized above all else. A 65Markdown-formatted document should be publishable as-is, as plain 66text, without looking like it's been marked up with tags or 67formatting instructions. While Markdown's syntax has been 68influenced 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 77biggest source of inspiration for Markdown's syntax is the format 78of plain text email.</p> 79<p>To this end, Markdown's syntax is comprised entirely of 80punctuation characters, which punctuation characters have been 81carefully chosen so as to look like what they mean. E.g., asterisks 82around a word actually look like *emphasis*. Markdown lists look 83like, well, lists. Even blockquotes look like quoted passages of 84text, 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 87format for <em>writing</em> for the web.</p> 88<p>Markdown is not a replacement for HTML, or even close to it. Its 89syntax is very small, corresponding only to a very small subset of 90HTML tags. The idea is <em>not</em> to create a syntax that makes 91it easier to insert HTML tags. In my opinion, HTML tags are already 92easy to insert. The idea for Markdown is to make it easy to read, 93write, and edit prose. HTML is a <em>publishing</em> format; 94Markdown is a <em>writing</em> format. Thus, Markdown's formatting 95syntax only addresses issues that can be conveyed in plain 96text.</p> 97<p>For any markup that is not covered by Markdown's syntax, you 98simply use HTML itself. There's no need to preface it or delimit it 99to indicate that you're switching from Markdown to HTML; you just 100use 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 104separated from surrounding content by blank lines, and the start 105and end tags of the block should not be indented with tabs or 106spaces. 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 118This is another regular paragraph. 119</code> 120</pre> 121<p>Note that Markdown formatting syntax is not processed within 122block-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 126used anywhere in a Markdown paragraph, list item, or header. If you 127want, you can even use HTML tags instead of Markdown formatting; 128e.g. if you'd prefer to use HTML <code><a></code> or 129<code><img></code> tags instead of Markdown's link or image 130syntax, go right ahead.</p> 131<p>Unlike block-level HTML tags, Markdown syntax <em>is</em> 132processed 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 136used to start tags; ampersands are used to denote HTML entities. If 137you want to use them as literal characters, you must escape them as 138entities, e.g. <code>&lt;</code>, and 139<code>&amp;</code>.</p> 140<p>Ampersands in particular are bedeviling for web writers. If you 141want to write about 'AT&T', you need to write 142'<code>AT&amp;T</code>'. You even need to escape ampersands 143within 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, 154this is easy to forget, and is probably the single most common 155source of HTML validation errors in otherwise well-marked-up web 156sites.</p> 157<p>Markdown allows you to use these characters naturally, taking 158care of all the necessary escaping for you. If you use an ampersand 159as part of an HTML entity, it remains unchanged; otherwise it will 160be translated into <code>&amp;</code>.</p> 161<p>So, if you want to include a copyright symbol in your article, 162you 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 178HTML</a>, if you use angle brackets as delimiters for HTML tags, 179Markdown 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 190and ampersands are <em>always</em> encoded automatically. This 191makes it easy to use Markdown to write about HTML code. (As opposed 192to raw HTML, which is a terrible format for writing about HTML 193syntax, 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, 199separated by one or more blank lines. (A blank line is any line 200that looks like a blank line -- a line containing nothing but 201spaces or tabs is considered blank.) Normal paragraphs should not 202be intended with spaces or tabs.</p> 203<p>The implication of the "one or more consecutive lines of text" 204rule is that Markdown supports "hard-wrapped" text paragraphs. This 205differs significantly from most other text-to-HTML formatters 206(including Movable Type's "Convert Line Breaks" option) which 207translate 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> 210break tag using Markdown, you end a line with two or more spaces, 211then 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 215email-style <a href="#blockquote">blockquoting</a> and 216multi-paragraph <a href="#list">list items</a> work best -- and 217look 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 223first-level headers) and dashes (for second-level headers). For 224example:</p> 225<pre> 226<code>This is an H1 227============= 228 229This is an H2 230------------- 231</code> 232</pre> 233<p>Any number of underlining <code>=</code>'s or <code>-</code>'s 234will work.</p> 235<p>Atx-style headers use 1-6 hash characters at the start of the 236line, 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 246cosmetic -- you can use this if you think it looks better. The 247closing hashes don't even need to match the number of hashes used 248to open the header. (The number of opening hashes determines the 249header 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 260blockquoting. If you're familiar with quoting passages of text in 261an email message, then you know how to create a blockquote in 262Markdown. 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 275paragraph:</p> 276<pre> 277<code>> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, 278consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 279Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 280 281> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse 282id sem consectetuer libero luctus adipiscing. 283</code> 284</pre> 285<p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by 286adding 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 296headers, 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 309example, with BBEdit, you can make a selection and choose Increase 310Quote Level from the Text menu.</p> 311<h3 id="list">Lists</h3> 312<p>Markdown supports ordered (numbered) and unordered (bulleted) 313lists.</p> 314<p>Unordered lists use asterisks, pluses, and hyphens -- 315interchangably -- 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 3392. McHale 3403. Parish 341</code> 342</pre> 343<p>It's important to note that the actual numbers you use to mark 344the list have no effect on the HTML output Markdown produces. The 345HTML 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 3571. McHale 3581. Parish 359</code> 360</pre> 361<p>or even:</p> 362<pre> 363<code>3. Bird 3641. McHale 3658. Parish 366</code> 367</pre> 368<p>you'd get the exact same HTML output. The point is, if you want 369to, you can use ordinal numbers in your ordered Markdown lists, so 370that the numbers in your source match the numbers in your published 371HTML. 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 373start the list with the number 1. At some point in the future, 374Markdown may support starting ordered lists at an arbitrary 375number.</p> 376<p>List markers typically start at the left margin, but may be 377indented by up to three spaces. List markers must be followed by 378one or more spaces or a tab.</p> 379<p>To make lists look nice, you can wrap items with hanging 380indents:</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. 392Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, 393viverra nec, fringilla in, laoreet vitae, risus. 394* Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 395Suspendisse id sem consectetuer libero luctus adipiscing. 396</code> 397</pre> 398<p>If list items are separated by blank lines, Markdown will wrap 399the items in <code><p></code> tags in the HTML output. For 400example, 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 430paragraph in a list item must be intended by either 4 spaces or one 431tab:</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 4412. Suspendisse id sem consectetuer libero luctus adipiscing. 442</code> 443</pre> 444<p>It looks nice if you indent every line of the subsequent 445paragraphs, 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 450only required to indent the first line. Lorem ipsum dolor 451sit 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 466be 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 474by 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 480beginning of a line. To avoid this, you can backslash-escape the 481period:</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 488or markup source code. Rather than forming normal paragraphs, the 489lines of a code block are interpreted literally. Markdown wraps a 490code 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 493the block by at least 4 spaces or 1 tab. For example, given this 494input:</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 510each 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 525end tell 526</code></pre> 527</code> 528</pre> 529<p>A code block continues until it reaches a line that is not 530indented (or the end of the article).</p> 531<p>Within a code block, ampersands (<code>&</code>) and angle 532brackets (<code><</code> and <code>></code>) are 533automatically converted into HTML entities. This makes it very easy 534to include example HTML source code using Markdown -- just paste it 535and indent it, and Markdown will handle the hassle of encoding the 536ampersands 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. 552E.g., asterisks are just literal asterisks within a code block. 553This means it's also easy to use Markdown to write about Markdown's 554own 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 558underscores on a line by themselves. If you wish, you may use 559spaces between the hyphens or asterisks. Each of the following 560lines 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 581brackets].</p> 582<p>To create an inline link, use a set of regular parentheses 583immediately after the link text's closing square bracket. Inside 584the parentheses, put the URL where you want the link to point, 585along with an <em>optional</em> title for the link, surrounded in 586quotes. 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"> 596an example</a> inline link.</p> 597 598<p><a href="http://example.net/">This link</a> has no 599title attribute.</p> 600</code> 601</pre> 602<p>If you're referring to a local resource on the same server, you 603can 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, 609inside which you place a label of your choosing to identify the 610link:</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 616brackets:</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 622this, 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 630indented 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 635in double or single quotes.</li> 636</ul> 637<p>The link URL may, optionally, be surrounded by angle 638brackets:</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 644spaces or tabs for padding, which tends to look better with longer 645URLs:</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 652Markdown processing, and are stripped from your document in the 653HTML output.</p> 654<p>Link definition names may constist of letters, numbers, spaces, 655and punctuation -- but they are <em>not</em> case sensitive. E.g. 656these 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 664name of the link, in which case the link text itself is used as the 665name. Just use an empty set of square brackets -- e.g., to link the 666word "Google" to the google.com web site, you could simply 667write:</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 678for 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 689document. I tend to put them immediately after each paragraph in 690which they're used, but if you want, you can put them all at the 691end 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 703write:</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 714output:</p> 715<pre> 716<code><p>I get 10 times more traffic from <a href="http://google.com/" 717title="Google">Google</a> than from 718<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a> 719or <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 723Markdown's inline link style:</p> 724<pre> 725<code>I get 10 times more traffic from [Google](http://google.com/ "Google") 726than 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 731write. The point is that with reference-style links, your document 732source is vastly more readable. Compare the above examples: using 733reference-style links, the paragraph itself is only 81 characters 734long; with inline-style links, it's 176 characters; and as raw 735HTML, it's 234 characters. In the raw HTML, there's more markup 736than there is text.</p> 737<p>With Markdown's reference-style links, a source document much 738more closely resembles the final output, as rendered in a browser. 739By allowing you to move the markup-related metadata out of the 740paragraph, you can add links without interrupting the narrative 741flow 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 771that the same character must be used to open and close an emphasis 772span.</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 779spaces, it'll be treated as a literal asterisk or underscore.</p> 780<p>To produce a literal asterisk or underscore at a position where 781it would otherwise be used as an emphasis delimiter, you can 782backslash 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 790indicates 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 801can use multiple backticks as the opening and closing 802delimiters:</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 813spaces -- one after the opening, one before the closing. This 814allows you to place literal backtick characters at the beginning or 815end of a code span:</p> 816<pre> 817<code>A single backtick in a code span: `` ` `` 818 819A 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 830HTML entities automatically, which makes it easy to include example 831HTML 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 849equivalent 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 854for placing images into a plain text document format.</p> 855<p>Markdown uses an image syntax that is intended to resemble the 856syntax 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 871the image, and an optional <code>title</code> attribute enclosed in 872double 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 880references are defined using syntax identical to link 881references:</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 887dimensions of an image; if this is important to you, you can simply 888use 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" 893links for URLs and email addresses: simply surround the URL or 894email address with angle brackets. What this means is that if you 895want to show the actual text of a URL or email address, and also 896have 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 907Markdown will also perform a bit of randomized decimal and hex 908entity-encoding to help obscure your address from 909address-harvesting spambots. For example, Markdown will turn 910this:</p> 911<pre> 912<code><address@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@example.com".</p> 925<p>(This sort of entity-encoding trick will indeed fool many, if 926not most, address-harvesting bots, but it definitely won't fool all 927of them. It's better than nothing, but an address published in this 928way 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 931characters which would otherwise have special meaning in Markdown's 932formatting syntax. For example, if you wanted to surround a word 933with literal asterisks (instead of an HTML <code><em></code> 934tag), 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 940characters:</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
