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