• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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>&lt;div&gt;</code>, <code>&lt;table&gt;</code>,
103<code>&lt;pre&gt;</code>, <code>&lt;p&gt;</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>&lt;p&gt;</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&lt;table&gt;
113    &lt;tr&gt;
114        &lt;td&gt;Foo&lt;/td&gt;
115    &lt;/tr&gt;
116&lt;/table&gt;
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>&lt;span&gt;</code>,
125<code>&lt;cite&gt;</code>, or <code>&lt;del&gt;</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>&lt;a&gt;</code> or
129<code>&lt;img&gt;</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>&lt;</code> and <code>&amp;</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>&amp;lt;</code>, and
139<code>&amp;amp;</code>.</p>
140<p>Ampersands in particular are bedeviling for web writers. If you
141want to write about 'AT&amp;T', you need to write
142'<code>AT&amp;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&amp;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&amp;amp;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;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>&amp;copy;
165</code>
166</pre>
167<p>and Markdown will leave it alone. But if you write:</p>
168<pre>
169<code>AT&amp;T
170</code>
171</pre>
172<p>Markdown will translate it to:</p>
173<pre>
174<code>AT&amp;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 &lt; 5
182</code>
183</pre>
184<p>Markdown will translate it to:</p>
185<pre>
186<code>4 &amp;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>&lt;</code> and
194<code>&amp;</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>&lt;br /&gt;</code> tag.</p>
209<p>When you <em>do</em> want to insert a <code>&lt;br /&gt;</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>&lt;br
213/&gt;</code>, but a simplistic "every line break is a <code>&lt;br
214/&gt;</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>&gt;</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>&gt;</code> before every line:</p>
264<pre>
265<code>&gt; This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
266&gt; consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
267&gt; Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
268&gt;
269&gt; Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
270&gt; id sem consectetuer libero luctus adipiscing.
271</code>
272</pre>
273<p>Markdown allows you to be lazy and only put the
274<code>&gt;</code> before the first line of a hard-wrapped
275paragraph:</p>
276<pre>
277<code>&gt; 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&gt; 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>&gt;</code>:</p>
287<pre>
288<code>&gt; This is the first level of quoting.
289&gt;
290&gt; &gt; This is nested blockquote.
291&gt;
292&gt; 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>&gt; ## This is a header.
299&gt;
300&gt; 1.   This is the first list item.
301&gt; 2.   This is the second list item.
302&gt;
303&gt; Here's some example code:
304&gt;
305&gt;     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>&lt;ol&gt;
348&lt;li&gt;Bird&lt;/li&gt;
349&lt;li&gt;McHale&lt;/li&gt;
350&lt;li&gt;Parish&lt;/li&gt;
351&lt;/ol&gt;
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>&lt;p&gt;</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>&lt;ul&gt;
409&lt;li&gt;Bird&lt;/li&gt;
410&lt;li&gt;Magic&lt;/li&gt;
411&lt;/ul&gt;
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>&lt;ul&gt;
424&lt;li&gt;&lt;p&gt;Bird&lt;/p&gt;&lt;/li&gt;
425&lt;li&gt;&lt;p&gt;Magic&lt;/p&gt;&lt;/li&gt;
426&lt;/ul&gt;
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>&gt;</code> delimiters need to be indented:</p>
458<pre>
459<code>*   A list item with a blockquote:
460
461    &gt; This is a blockquote
462    &gt; 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        &lt;code goes here&gt;
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>&lt;pre&gt;</code> and
491<code>&lt;code&gt;</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>&lt;p&gt;This is a normal paragraph:&lt;/p&gt;
504
505&lt;pre&gt;&lt;code&gt;This is a code block.
506&lt;/code&gt;&lt;/pre&gt;
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>&lt;p&gt;Here is an example of AppleScript:&lt;/p&gt;
522
523&lt;pre&gt;&lt;code&gt;tell application "Foo"
524    beep
525end tell
526&lt;/code&gt;&lt;/pre&gt;
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>&amp;</code>) and angle
532brackets (<code>&lt;</code> and <code>&gt;</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>    &lt;div class="footer"&gt;
539        &amp;copy; 2004 Foo Corporation
540    &lt;/div&gt;
541</code>
542</pre>
543<p>will turn into:</p>
544<pre>
545<code>&lt;pre&gt;&lt;code&gt;&amp;lt;div class="footer"&amp;gt;
546    &amp;amp;copy; 2004 Foo Corporation
547&amp;lt;/div&amp;gt;
548&lt;/code&gt;&lt;/pre&gt;
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>&lt;hr
557/&gt;</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>&lt;p&gt;This is &lt;a href="http://example.com/" title="Title"&gt;
596an example&lt;/a&gt; inline link.&lt;/p&gt;
597
598&lt;p&gt;&lt;a href="http://example.net/"&gt;This link&lt;/a&gt; has no
599title attribute.&lt;/p&gt;
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]: &lt;http://example.com/&gt;  "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>&lt;p&gt;I get 10 times more traffic from &lt;a href="http://google.com/"
717title="Google"&gt;Google&lt;/a&gt; than from
718&lt;a href="http://search.yahoo.com/" title="Yahoo Search"&gt;Yahoo&lt;/a&gt;
719or &lt;a href="http://search.msn.com/" title="MSN Search"&gt;MSN&lt;/a&gt;.&lt;/p&gt;
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>&lt;em&gt;</code> tag; double <code>*</code>'s or
747<code>_</code>'s will be wrapped with an HTML
748<code>&lt;strong&gt;</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>&lt;em&gt;single asterisks&lt;/em&gt;
762
763&lt;em&gt;single underscores&lt;/em&gt;
764
765&lt;strong&gt;double asterisks&lt;/strong&gt;
766
767&lt;strong&gt;double underscores&lt;/strong&gt;
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>&lt;p&gt;Use the &lt;code&gt;printf()&lt;/code&gt; function.&lt;/p&gt;
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>&lt;p&gt;&lt;code&gt;There is a literal backtick (`) here.&lt;/code&gt;&lt;/p&gt;
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>&lt;p&gt;A single backtick in a code span: &lt;code&gt;`&lt;/code&gt;&lt;/p&gt;
825
826&lt;p&gt;A backtick-delimited string in a code span: &lt;code&gt;`foo`&lt;/code&gt;&lt;/p&gt;
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 `&lt;blink&gt;` tags.
834</code>
835</pre>
836<p>into:</p>
837<pre>
838<code>&lt;p&gt;Please don't use any &lt;code&gt;&amp;lt;blink&amp;gt;&lt;/code&gt; tags.&lt;/p&gt;
839</code>
840</pre>
841<p>You can write this:</p>
842<pre>
843<code>`&amp;#8212;` is the decimal-encoded equivalent of `&amp;mdash;`.
844</code>
845</pre>
846<p>to produce:</p>
847<pre>
848<code>&lt;p&gt;&lt;code&gt;&amp;amp;#8212;&lt;/code&gt; is the decimal-encoded
849equivalent of &lt;code&gt;&amp;amp;mdash;&lt;/code&gt;.&lt;/p&gt;
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>![Alt text](/path/to/img.jpg)
861
862![Alt text](/path/to/img.jpg "Optional title")
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>&lt;img&gt;</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>&lt;http://example.com/&gt;
899</code>
900</pre>
901<p>Markdown will turn this into:</p>
902<pre>
903<code>&lt;a href="http://example.com/"&gt;http://example.com/&lt;/a&gt;
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>&lt;address@example.com&gt;
913</code>
914</pre>
915<p>into something like this:</p>
916<pre>
917<code>&lt;a href="&amp;#x6D;&amp;#x61;i&amp;#x6C;&amp;#x74;&amp;#x6F;:&amp;#x61;&amp;#x64;&amp;#x64;&amp;#x72;&amp;#x65;
918&amp;#115;&amp;#115;&amp;#64;&amp;#101;&amp;#120;&amp;#x61;&amp;#109;&amp;#x70;&amp;#x6C;e&amp;#x2E;&amp;#99;&amp;#111;
919&amp;#109;"&gt;&amp;#x61;&amp;#x64;&amp;#x64;&amp;#x72;&amp;#x65;&amp;#115;&amp;#115;&amp;#64;&amp;#101;&amp;#120;&amp;#x61;
920&amp;#109;&amp;#x70;&amp;#x6C;e&amp;#x2E;&amp;#99;&amp;#111;&amp;#109;&lt;/a&gt;
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>&lt;em&gt;</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