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