Warning, /education/cantor/thirdparty/discount-2.2.6-patched/tests/syntax.text is written in an unsupported language. File is not indexed.
0001 Markdown: Syntax 0002 ================ 0003 0004 <ul id="ProjectSubmenu"> 0005 <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li> 0006 <li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li> 0007 <li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li> 0008 <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li> 0009 <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li> 0010 </ul> 0011 0012 0013 * [Overview](#overview) 0014 * [Philosophy](#philosophy) 0015 * [Inline HTML](#html) 0016 * [Automatic Escaping for Special Characters](#autoescape) 0017 * [Block Elements](#block) 0018 * [Paragraphs and Line Breaks](#p) 0019 * [Headers](#header) 0020 * [Blockquotes](#blockquote) 0021 * [Lists](#list) 0022 * [Code Blocks](#precode) 0023 * [Horizontal Rules](#hr) 0024 * [Span Elements](#span) 0025 * [Links](#link) 0026 * [Emphasis](#em) 0027 * [Code](#code) 0028 * [Images](#img) 0029 * [Miscellaneous](#misc) 0030 * [Backslash Escapes](#backslash) 0031 * [Automatic Links](#autolink) 0032 0033 0034 **Note:** This document is itself written using Markdown; you 0035 can [see the source for it by adding '.text' to the URL][src]. 0036 0037 [src]: /projects/markdown/syntax.text 0038 0039 * * * 0040 0041 <h2 id="overview">Overview</h2> 0042 0043 <h3 id="philosophy">Philosophy</h3> 0044 0045 Markdown is intended to be as easy-to-read and easy-to-write as is feasible. 0046 0047 Readability, however, is emphasized above all else. A Markdown-formatted 0048 document should be publishable as-is, as plain text, without looking 0049 like it's been marked up with tags or formatting instructions. While 0050 Markdown's syntax has been influenced by several existing text-to-HTML 0051 filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4], 0052 [Grutatext] [5], and [EtText] [6] -- the single biggest source of 0053 inspiration for Markdown's syntax is the format of plain text email. 0054 0055 [1]: http://docutils.sourceforge.net/mirror/setext.html 0056 [2]: http://www.aaronsw.com/2002/atx/ 0057 [3]: http://textism.com/tools/textile/ 0058 [4]: http://docutils.sourceforge.net/rst.html 0059 [5]: http://www.triptico.com/software/grutatxt.html 0060 [6]: http://ettext.taint.org/doc/ 0061 0062 To this end, Markdown's syntax is comprised entirely of punctuation 0063 characters, which punctuation characters have been carefully chosen so 0064 as to look like what they mean. E.g., asterisks around a word actually 0065 look like \*emphasis\*. Markdown lists look like, well, lists. Even 0066 blockquotes look like quoted passages of text, assuming you've ever 0067 used email. 0068 0069 0070 0071 <h3 id="html">Inline HTML</h3> 0072 0073 Markdown's syntax is intended for one purpose: to be used as a 0074 format for *writing* for the web. 0075 0076 Markdown is not a replacement for HTML, or even close to it. Its 0077 syntax is very small, corresponding only to a very small subset of 0078 HTML tags. The idea is *not* to create a syntax that makes it easier 0079 to insert HTML tags. In my opinion, HTML tags are already easy to 0080 insert. The idea for Markdown is to make it easy to read, write, and 0081 edit prose. HTML is a *publishing* format; Markdown is a *writing* 0082 format. Thus, Markdown's formatting syntax only addresses issues that 0083 can be conveyed in plain text. 0084 0085 For any markup that is not covered by Markdown's syntax, you simply 0086 use HTML itself. There's no need to preface it or delimit it to 0087 indicate that you're switching from Markdown to HTML; you just use 0088 the tags. 0089 0090 The only restrictions are that block-level HTML elements -- e.g. `<div>`, 0091 `<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding 0092 content by blank lines, and the start and end tags of the block should 0093 not be indented with tabs or spaces. Markdown is smart enough not 0094 to add extra (unwanted) `<p>` tags around HTML block-level tags. 0095 0096 For example, to add an HTML table to a Markdown article: 0097 0098 This is a regular paragraph. 0099 0100 <table> 0101 <tr> 0102 <td>Foo</td> 0103 </tr> 0104 </table> 0105 0106 This is another regular paragraph. 0107 0108 Note that Markdown formatting syntax is not processed within block-level 0109 HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an 0110 HTML block. 0111 0112 Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be 0113 used anywhere in a Markdown paragraph, list item, or header. If you 0114 want, you can even use HTML tags instead of Markdown formatting; e.g. if 0115 you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's 0116 link or image syntax, go right ahead. 0117 0118 Unlike block-level HTML tags, Markdown syntax *is* processed within 0119 span-level tags. 0120 0121 0122 <h3 id="autoescape">Automatic Escaping for Special Characters</h3> 0123 0124 In HTML, there are two characters that demand special treatment: `<` 0125 and `&`. Left angle brackets are used to start tags; ampersands are 0126 used to denote HTML entities. If you want to use them as literal 0127 characters, you must escape them as entities, e.g. `<`, and 0128 `&`. 0129 0130 Ampersands in particular are bedeviling for web writers. If you want to 0131 write about 'AT&T', you need to write '`AT&T`'. You even need to 0132 escape ampersands within URLs. Thus, if you want to link to: 0133 0134 http://images.google.com/images?num=30&q=larry+bird 0135 0136 you need to encode the URL as: 0137 0138 http://images.google.com/images?num=30&q=larry+bird 0139 0140 in your anchor tag `href` attribute. Needless to say, this is easy to 0141 forget, and is probably the single most common source of HTML validation 0142 errors in otherwise well-marked-up web sites. 0143 0144 Markdown allows you to use these characters naturally, taking care of 0145 all the necessary escaping for you. If you use an ampersand as part of 0146 an HTML entity, it remains unchanged; otherwise it will be translated 0147 into `&`. 0148 0149 So, if you want to include a copyright symbol in your article, you can write: 0150 0151 © 0152 0153 and Markdown will leave it alone. But if you write: 0154 0155 AT&T 0156 0157 Markdown will translate it to: 0158 0159 AT&T 0160 0161 Similarly, because Markdown supports [inline HTML](#html), if you use 0162 angle brackets as delimiters for HTML tags, Markdown will treat them as 0163 such. But if you write: 0164 0165 4 < 5 0166 0167 Markdown will translate it to: 0168 0169 4 < 5 0170 0171 However, inside Markdown code spans and blocks, angle brackets and 0172 ampersands are *always* encoded automatically. This makes it easy to use 0173 Markdown to write about HTML code. (As opposed to raw HTML, which is a 0174 terrible format for writing about HTML syntax, because every single `<` 0175 and `&` in your example code needs to be escaped.) 0176 0177 0178 * * * 0179 0180 0181 <h2 id="block">Block Elements</h2> 0182 0183 0184 <h3 id="p">Paragraphs and Line Breaks</h3> 0185 0186 A paragraph is simply one or more consecutive lines of text, separated 0187 by one or more blank lines. (A blank line is any line that looks like a 0188 blank line -- a line containing nothing but spaces or tabs is considered 0189 blank.) Normal paragraphs should not be indented with spaces or tabs. 0190 0191 The implication of the "one or more consecutive lines of text" rule is 0192 that Markdown supports "hard-wrapped" text paragraphs. This differs 0193 significantly from most other text-to-HTML formatters (including Movable 0194 Type's "Convert Line Breaks" option) which translate every line break 0195 character in a paragraph into a `<br />` tag. 0196 0197 When you *do* want to insert a `<br />` break tag using Markdown, you 0198 end a line with two or more spaces, then type return. 0199 0200 Yes, this takes a tad more effort to create a `<br />`, but a simplistic 0201 "every line break is a `<br />`" rule wouldn't work for Markdown. 0202 Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l] 0203 work best -- and look better -- when you format them with hard breaks. 0204 0205 [bq]: #blockquote 0206 [l]: #list 0207 0208 0209 0210 <h3 id="header">Headers</h3> 0211 0212 Markdown supports two styles of headers, [Setext] [1] and [atx] [2]. 0213 0214 Setext-style headers are "underlined" using equal signs (for first-level 0215 headers) and dashes (for second-level headers). For example: 0216 0217 This is an H1 0218 ============= 0219 0220 This is an H2 0221 ------------- 0222 0223 Any number of underlining `=`'s or `-`'s will work. 0224 0225 Atx-style headers use 1-6 hash characters at the start of the line, 0226 corresponding to header levels 1-6. For example: 0227 0228 # This is an H1 0229 0230 ## This is an H2 0231 0232 ###### This is an H6 0233 0234 Optionally, you may "close" atx-style headers. This is purely 0235 cosmetic -- you can use this if you think it looks better. The 0236 closing hashes don't even need to match the number of hashes 0237 used to open the header. (The number of opening hashes 0238 determines the header level.) : 0239 0240 # This is an H1 # 0241 0242 ## This is an H2 ## 0243 0244 ### This is an H3 ###### 0245 0246 0247 <h3 id="blockquote">Blockquotes</h3> 0248 0249 Markdown uses email-style `>` characters for blockquoting. If you're 0250 familiar with quoting passages of text in an email message, then you 0251 know how to create a blockquote in Markdown. It looks best if you hard 0252 wrap the text and put a `>` before every line: 0253 0254 > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, 0255 > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 0256 > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 0257 > 0258 > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse 0259 > id sem consectetuer libero luctus adipiscing. 0260 0261 Markdown allows you to be lazy and only put the `>` before the first 0262 line of a hard-wrapped paragraph: 0263 0264 > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, 0265 consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. 0266 Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. 0267 0268 > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse 0269 id sem consectetuer libero luctus adipiscing. 0270 0271 Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by 0272 adding additional levels of `>`: 0273 0274 > This is the first level of quoting. 0275 > 0276 > > This is nested blockquote. 0277 > 0278 > Back to the first level. 0279 0280 Blockquotes can contain other Markdown elements, including headers, lists, 0281 and code blocks: 0282 0283 > ## This is a header. 0284 > 0285 > 1. This is the first list item. 0286 > 2. This is the second list item. 0287 > 0288 > Here's some example code: 0289 > 0290 > return shell_exec("echo $input | $markdown_script"); 0291 0292 Any decent text editor should make email-style quoting easy. For 0293 example, with BBEdit, you can make a selection and choose Increase 0294 Quote Level from the Text menu. 0295 0296 0297 <h3 id="list">Lists</h3> 0298 0299 Markdown supports ordered (numbered) and unordered (bulleted) lists. 0300 0301 Unordered lists use asterisks, pluses, and hyphens -- interchangably 0302 -- as list markers: 0303 0304 * Red 0305 * Green 0306 * Blue 0307 0308 is equivalent to: 0309 0310 + Red 0311 + Green 0312 + Blue 0313 0314 and: 0315 0316 - Red 0317 - Green 0318 - Blue 0319 0320 Ordered lists use numbers followed by periods: 0321 0322 1. Bird 0323 2. McHale 0324 3. Parish 0325 0326 It's important to note that the actual numbers you use to mark the 0327 list have no effect on the HTML output Markdown produces. The HTML 0328 Markdown produces from the above list is: 0329 0330 <ol> 0331 <li>Bird</li> 0332 <li>McHale</li> 0333 <li>Parish</li> 0334 </ol> 0335 0336 If you instead wrote the list in Markdown like this: 0337 0338 1. Bird 0339 1. McHale 0340 1. Parish 0341 0342 or even: 0343 0344 3. Bird 0345 1. McHale 0346 8. Parish 0347 0348 you'd get the exact same HTML output. The point is, if you want to, 0349 you can use ordinal numbers in your ordered Markdown lists, so that 0350 the numbers in your source match the numbers in your published HTML. 0351 But if you want to be lazy, you don't have to. 0352 0353 If you do use lazy list numbering, however, you should still start the 0354 list with the number 1. At some point in the future, Markdown may support 0355 starting ordered lists at an arbitrary number. 0356 0357 List markers typically start at the left margin, but may be indented by 0358 up to three spaces. List markers must be followed by one or more spaces 0359 or a tab. 0360 0361 To make lists look nice, you can wrap items with hanging indents: 0362 0363 * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 0364 Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, 0365 viverra nec, fringilla in, laoreet vitae, risus. 0366 * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 0367 Suspendisse id sem consectetuer libero luctus adipiscing. 0368 0369 But if you want to be lazy, you don't have to: 0370 0371 * Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 0372 Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, 0373 viverra nec, fringilla in, laoreet vitae, risus. 0374 * Donec sit amet nisl. Aliquam semper ipsum sit amet velit. 0375 Suspendisse id sem consectetuer libero luctus adipiscing. 0376 0377 If list items are separated by blank lines, Markdown will wrap the 0378 items in `<p>` tags in the HTML output. For example, this input: 0379 0380 * Bird 0381 * Magic 0382 0383 will turn into: 0384 0385 <ul> 0386 <li>Bird</li> 0387 <li>Magic</li> 0388 </ul> 0389 0390 But this: 0391 0392 * Bird 0393 0394 * Magic 0395 0396 will turn into: 0397 0398 <ul> 0399 <li><p>Bird</p></li> 0400 <li><p>Magic</p></li> 0401 </ul> 0402 0403 List items may consist of multiple paragraphs. Each subsequent 0404 paragraph in a list item must be intended by either 4 spaces 0405 or one tab: 0406 0407 1. This is a list item with two paragraphs. Lorem ipsum dolor 0408 sit amet, consectetuer adipiscing elit. Aliquam hendrerit 0409 mi posuere lectus. 0410 0411 Vestibulum enim wisi, viverra nec, fringilla in, laoreet 0412 vitae, risus. Donec sit amet nisl. Aliquam semper ipsum 0413 sit amet velit. 0414 0415 2. Suspendisse id sem consectetuer libero luctus adipiscing. 0416 0417 It looks nice if you indent every line of the subsequent 0418 paragraphs, but here again, Markdown will allow you to be 0419 lazy: 0420 0421 * This is a list item with two paragraphs. 0422 0423 This is the second paragraph in the list item. You're 0424 only required to indent the first line. Lorem ipsum dolor 0425 sit amet, consectetuer adipiscing elit. 0426 0427 * Another item in the same list. 0428 0429 To put a blockquote within a list item, the blockquote's `>` 0430 delimiters need to be indented: 0431 0432 * A list item with a blockquote: 0433 0434 > This is a blockquote 0435 > inside a list item. 0436 0437 To put a code block within a list item, the code block needs 0438 to be indented *twice* -- 8 spaces or two tabs: 0439 0440 * A list item with a code block: 0441 0442 <code goes here> 0443 0444 0445 It's worth noting that it's possible to trigger an ordered list by 0446 accident, by writing something like this: 0447 0448 1986. What a great season. 0449 0450 In other words, a *number-period-space* sequence at the beginning of a 0451 line. To avoid this, you can backslash-escape the period: 0452 0453 1986\. What a great season. 0454 0455 0456 0457 <h3 id="precode">Code Blocks</h3> 0458 0459 Pre-formatted code blocks are used for writing about programming or 0460 markup source code. Rather than forming normal paragraphs, the lines 0461 of a code block are interpreted literally. Markdown wraps a code block 0462 in both `<pre>` and `<code>` tags. 0463 0464 To produce a code block in Markdown, simply indent every line of the 0465 block by at least 4 spaces or 1 tab. For example, given this input: 0466 0467 This is a normal paragraph: 0468 0469 This is a code block. 0470 0471 Markdown will generate: 0472 0473 <p>This is a normal paragraph:</p> 0474 0475 <pre><code>This is a code block. 0476 </code></pre> 0477 0478 One level of indentation -- 4 spaces or 1 tab -- is removed from each 0479 line of the code block. For example, this: 0480 0481 Here is an example of AppleScript: 0482 0483 tell application "Foo" 0484 beep 0485 end tell 0486 0487 will turn into: 0488 0489 <p>Here is an example of AppleScript:</p> 0490 0491 <pre><code>tell application "Foo" 0492 beep 0493 end tell 0494 </code></pre> 0495 0496 A code block continues until it reaches a line that is not indented 0497 (or the end of the article). 0498 0499 Within a code block, ampersands (`&`) and angle brackets (`<` and `>`) 0500 are automatically converted into HTML entities. This makes it very 0501 easy to include example HTML source code using Markdown -- just paste 0502 it and indent it, and Markdown will handle the hassle of encoding the 0503 ampersands and angle brackets. For example, this: 0504 0505 <div class="footer"> 0506 © 2004 Foo Corporation 0507 </div> 0508 0509 will turn into: 0510 0511 <pre><code><div class="footer"> 0512 &copy; 2004 Foo Corporation 0513 </div> 0514 </code></pre> 0515 0516 Regular Markdown syntax is not processed within code blocks. E.g., 0517 asterisks are just literal asterisks within a code block. This means 0518 it's also easy to use Markdown to write about Markdown's own syntax. 0519 0520 0521 0522 <h3 id="hr">Horizontal Rules</h3> 0523 0524 You can produce a horizontal rule tag (`<hr />`) by placing three or 0525 more hyphens, asterisks, or underscores on a line by themselves. If you 0526 wish, you may use spaces between the hyphens or asterisks. Each of the 0527 following lines will produce a horizontal rule: 0528 0529 * * * 0530 0531 *** 0532 0533 ***** 0534 0535 - - - 0536 0537 --------------------------------------- 0538 0539 0540 * * * 0541 0542 <h2 id="span">Span Elements</h2> 0543 0544 <h3 id="link">Links</h3> 0545 0546 Markdown supports two style of links: *inline* and *reference*. 0547 0548 In both styles, the link text is delimited by [square brackets]. 0549 0550 To create an inline link, use a set of regular parentheses immediately 0551 after the link text's closing square bracket. Inside the parentheses, 0552 put the URL where you want the link to point, along with an *optional* 0553 title for the link, surrounded in quotes. For example: 0554 0555 This is [an example](http://example.com/ "Title") inline link. 0556 0557 [This link](http://example.net/) has no title attribute. 0558 0559 Will produce: 0560 0561 <p>This is <a href="http://example.com/" title="Title"> 0562 an example</a> inline link.</p> 0563 0564 <p><a href="http://example.net/">This link</a> has no 0565 title attribute.</p> 0566 0567 If you're referring to a local resource on the same server, you can 0568 use relative paths: 0569 0570 See my [About](/about/) page for details. 0571 0572 Reference-style links use a second set of square brackets, inside 0573 which you place a label of your choosing to identify the link: 0574 0575 This is [an example][id] reference-style link. 0576 0577 You can optionally use a space to separate the sets of brackets: 0578 0579 This is [an example] [id] reference-style link. 0580 0581 Then, anywhere in the document, you define your link label like this, 0582 on a line by itself: 0583 0584 [id]: http://example.com/ "Optional Title Here" 0585 0586 That is: 0587 0588 * Square brackets containing the link identifier (optionally 0589 indented from the left margin using up to three spaces); 0590 * followed by a colon; 0591 * followed by one or more spaces (or tabs); 0592 * followed by the URL for the link; 0593 * optionally followed by a title attribute for the link, enclosed 0594 in double or single quotes, or enclosed in parentheses. 0595 0596 The following three link definitions are equivalent: 0597 0598 [foo]: http://example.com/ "Optional Title Here" 0599 [foo]: http://example.com/ 'Optional Title Here' 0600 [foo]: http://example.com/ (Optional Title Here) 0601 0602 **Note:** There is a known bug in Markdown.pl 1.0.1 which prevents 0603 single quotes from being used to delimit link titles. 0604 0605 The link URL may, optionally, be surrounded by angle brackets: 0606 0607 [id]: <http://example.com/> "Optional Title Here" 0608 0609 You can put the title attribute on the next line and use extra spaces 0610 or tabs for padding, which tends to look better with longer URLs: 0611 0612 [id]: http://example.com/longish/path/to/resource/here 0613 "Optional Title Here" 0614 0615 Link definitions are only used for creating links during Markdown 0616 processing, and are stripped from your document in the HTML output. 0617 0618 Link definition names may constist of letters, numbers, spaces, and 0619 punctuation -- but they are *not* case sensitive. E.g. these two 0620 links: 0621 0622 [link text][a] 0623 [link text][A] 0624 0625 are equivalent. 0626 0627 The *implicit link name* shortcut allows you to omit the name of the 0628 link, in which case the link text itself is used as the name. 0629 Just use an empty set of square brackets -- e.g., to link the word 0630 "Google" to the google.com web site, you could simply write: 0631 0632 [Google][] 0633 0634 And then define the link: 0635 0636 [Google]: http://google.com/ 0637 0638 Because link names may contain spaces, this shortcut even works for 0639 multiple words in the link text: 0640 0641 Visit [Daring Fireball][] for more information. 0642 0643 And then define the link: 0644 0645 [Daring Fireball]: http://daringfireball.net/ 0646 0647 Link definitions can be placed anywhere in your Markdown document. I 0648 tend to put them immediately after each paragraph in which they're 0649 used, but if you want, you can put them all at the end of your 0650 document, sort of like footnotes. 0651 0652 Here's an example of reference links in action: 0653 0654 I get 10 times more traffic from [Google] [1] than from 0655 [Yahoo] [2] or [MSN] [3]. 0656 0657 [1]: http://google.com/ "Google" 0658 [2]: http://search.yahoo.com/ "Yahoo Search" 0659 [3]: http://search.msn.com/ "MSN Search" 0660 0661 Using the implicit link name shortcut, you could instead write: 0662 0663 I get 10 times more traffic from [Google][] than from 0664 [Yahoo][] or [MSN][]. 0665 0666 [google]: http://google.com/ "Google" 0667 [yahoo]: http://search.yahoo.com/ "Yahoo Search" 0668 [msn]: http://search.msn.com/ "MSN Search" 0669 0670 Both of the above examples will produce the following HTML output: 0671 0672 <p>I get 10 times more traffic from <a href="http://google.com/" 0673 title="Google">Google</a> than from 0674 <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a> 0675 or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p> 0676 0677 For comparison, here is the same paragraph written using 0678 Markdown's inline link style: 0679 0680 I get 10 times more traffic from [Google](http://google.com/ "Google") 0681 than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or 0682 [MSN](http://search.msn.com/ "MSN Search"). 0683 0684 The point of reference-style links is not that they're easier to 0685 write. The point is that with reference-style links, your document 0686 source is vastly more readable. Compare the above examples: using 0687 reference-style links, the paragraph itself is only 81 characters 0688 long; with inline-style links, it's 176 characters; and as raw HTML, 0689 it's 234 characters. In the raw HTML, there's more markup than there 0690 is text. 0691 0692 With Markdown's reference-style links, a source document much more 0693 closely resembles the final output, as rendered in a browser. By 0694 allowing you to move the markup-related metadata out of the paragraph, 0695 you can add links without interrupting the narrative flow of your 0696 prose. 0697 0698 0699 <h3 id="em">Emphasis</h3> 0700 0701 Markdown treats asterisks (`*`) and underscores (`_`) as indicators of 0702 emphasis. Text wrapped with one `*` or `_` will be wrapped with an 0703 HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML 0704 `<strong>` tag. E.g., this input: 0705 0706 *single asterisks* 0707 0708 _single underscores_ 0709 0710 **double asterisks** 0711 0712 __double underscores__ 0713 0714 will produce: 0715 0716 <em>single asterisks</em> 0717 0718 <em>single underscores</em> 0719 0720 <strong>double asterisks</strong> 0721 0722 <strong>double underscores</strong> 0723 0724 You can use whichever style you prefer; the lone restriction is that 0725 the same character must be used to open and close an emphasis span. 0726 0727 Emphasis can be used in the middle of a word: 0728 0729 un*fucking*believable 0730 0731 But if you surround an `*` or `_` with spaces, it'll be treated as a 0732 literal asterisk or underscore. 0733 0734 To produce a literal asterisk or underscore at a position where it 0735 would otherwise be used as an emphasis delimiter, you can backslash 0736 escape it: 0737 0738 \*this text is surrounded by literal asterisks\* 0739 0740 0741 0742 <h3 id="code">Code</h3> 0743 0744 To indicate a span of code, wrap it with backtick quotes (`` ` ``). 0745 Unlike a pre-formatted code block, a code span indicates code within a 0746 normal paragraph. For example: 0747 0748 Use the `printf()` function. 0749 0750 will produce: 0751 0752 <p>Use the <code>printf()</code> function.</p> 0753 0754 To include a literal backtick character within a code span, you can use 0755 multiple backticks as the opening and closing delimiters: 0756 0757 ``There is a literal backtick (`) here.`` 0758 0759 which will produce this: 0760 0761 <p><code>There is a literal backtick (`) here.</code></p> 0762 0763 The backtick delimiters surrounding a code span may include spaces -- 0764 one after the opening, one before the closing. This allows you to place 0765 literal backtick characters at the beginning or end of a code span: 0766 0767 A single backtick in a code span: `` ` `` 0768 0769 A backtick-delimited string in a code span: `` `foo` `` 0770 0771 will produce: 0772 0773 <p>A single backtick in a code span: <code>`</code></p> 0774 0775 <p>A backtick-delimited string in a code span: <code>`foo`</code></p> 0776 0777 With a code span, ampersands and angle brackets are encoded as HTML 0778 entities automatically, which makes it easy to include example HTML 0779 tags. Markdown will turn this: 0780 0781 Please don't use any `<blink>` tags. 0782 0783 into: 0784 0785 <p>Please don't use any <code><blink></code> tags.</p> 0786 0787 You can write this: 0788 0789 `—` is the decimal-encoded equivalent of `—`. 0790 0791 to produce: 0792 0793 <p><code>&#8212;</code> is the decimal-encoded 0794 equivalent of <code>&mdash;</code>.</p> 0795 0796 0797 0798 <h3 id="img">Images</h3> 0799 0800 Admittedly, it's fairly difficult to devise a "natural" syntax for 0801 placing images into a plain text document format. 0802 0803 Markdown uses an image syntax that is intended to resemble the syntax 0804 for links, allowing for two styles: *inline* and *reference*. 0805 0806 Inline image syntax looks like this: 0807 0808 ![Alt text](/path/to/img.jpg) 0809 0810 ![Alt text](/path/to/img.jpg "Optional title") 0811 0812 That is: 0813 0814 * An exclamation mark: `!`; 0815 * followed by a set of square brackets, containing the `alt` 0816 attribute text for the image; 0817 * followed by a set of parentheses, containing the URL or path to 0818 the image, and an optional `title` attribute enclosed in double 0819 or single quotes. 0820 0821 Reference-style image syntax looks like this: 0822 0823 ![Alt text][id] 0824 0825 Where "id" is the name of a defined image reference. Image references 0826 are defined using syntax identical to link references: 0827 0828 [id]: url/to/image "Optional title attribute" 0829 0830 As of this writing, Markdown has no syntax for specifying the 0831 dimensions of an image; if this is important to you, you can simply 0832 use regular HTML `<img>` tags. 0833 0834 0835 * * * 0836 0837 0838 <h2 id="misc">Miscellaneous</h2> 0839 0840 <h3 id="autolink">Automatic Links</h3> 0841 0842 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: 0843 0844 <http://example.com/> 0845 0846 Markdown will turn this into: 0847 0848 <a href="http://example.com/">http://example.com/</a> 0849 0850 Automatic links for email addresses work similarly, except that 0851 Markdown will also perform a bit of randomized decimal and hex 0852 entity-encoding to help obscure your address from address-harvesting 0853 spambots. For example, Markdown will turn this: 0854 0855 <address@example.com> 0856 0857 into something like this: 0858 0859 <a href="mailto:addre 0860 ss@example.co 0861 m">address@exa 0862 mple.com</a> 0863 0864 which will render in a browser as a clickable link to "address@example.com". 0865 0866 (This sort of entity-encoding trick will indeed fool many, if not 0867 most, address-harvesting bots, but it definitely won't fool all of 0868 them. It's better than nothing, but an address published in this way 0869 will probably eventually start receiving spam.) 0870 0871 0872 0873 <h3 id="backslash">Backslash Escapes</h3> 0874 0875 Markdown allows you to use backslash escapes to generate literal 0876 characters which would otherwise have special meaning in Markdown's 0877 formatting syntax. For example, if you wanted to surround a word with 0878 literal asterisks (instead of an HTML `<em>` tag), you can backslashes 0879 before the asterisks, like this: 0880 0881 \*literal asterisks\* 0882 0883 Markdown provides backslash escapes for the following characters: 0884 0885 \ backslash 0886 ` backtick 0887 * asterisk 0888 _ underscore 0889 {} curly braces 0890 [] square brackets 0891 () parentheses 0892 # hash mark 0893 + plus sign 0894 - minus sign (hyphen) 0895 . dot 0896 ! exclamation mark 0897