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