Debian Codegraph @

tests/extensions/toc.txt

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