Changesets can be listed by changeset number.
The Git repository is here.
- Revision:
- 373
- Log:
Initial import of Radiant 0.9.1, which is now packaged as a gem. This is an
import of the tagged 0.9.1 source checked out from GitHub, which isn't quite
the same as the gem distribution - but it doesn't seem to be available in an
archived form and the installed gem already has modifications, so this is
the closest I can get.
- Author:
- rool
- Date:
- Mon Mar 21 13:40:05 +0000 2011
- Size:
- 27428 Bytes
1 | Markdown: 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 |
35 | can [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 | |
45 | Markdown is intended to be as easy-to-read and easy-to-write as is feasible. |
46 | |
47 | Readability, however, is emphasized above all else. A Markdown-formatted |
48 | document should be publishable as-is, as plain text, without looking |
49 | like it's been marked up with tags or formatting instructions. While |
50 | Markdown's syntax has been influenced by several existing text-to-HTML |
51 | filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4], |
52 | [Grutatext] [5], and [EtText] [6] -- the single biggest source of |
53 | inspiration 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 | |
62 | To this end, Markdown's syntax is comprised entirely of punctuation |
63 | characters, which punctuation characters have been carefully chosen so |
64 | as to look like what they mean. E.g., asterisks around a word actually |
65 | look like \*emphasis\*. Markdown lists look like, well, lists. Even |
66 | blockquotes look like quoted passages of text, assuming you've ever |
67 | used email. |
68 | |
69 | |
70 | |
71 | <h3 id="html">Inline HTML</h3> |
72 | |
73 | Markdown's syntax is intended for one purpose: to be used as a |
74 | format for *writing* for the web. |
75 | |
76 | Markdown is not a replacement for HTML, or even close to it. Its |
77 | syntax is very small, corresponding only to a very small subset of |
78 | HTML tags. The idea is *not* to create a syntax that makes it easier |
79 | to insert HTML tags. In my opinion, HTML tags are already easy to |
80 | insert. The idea for Markdown is to make it easy to read, write, and |
81 | edit prose. HTML is a *publishing* format; Markdown is a *writing* |
82 | format. Thus, Markdown's formatting syntax only addresses issues that |
83 | can be conveyed in plain text. |
84 | |
85 | For any markup that is not covered by Markdown's syntax, you simply |
86 | use HTML itself. There's no need to preface it or delimit it to |
87 | indicate that you're switching from Markdown to HTML; you just use |
88 | the tags. |
89 | |
90 | The only restrictions are that block-level HTML elements -- e.g. `<div>`, |
91 | `<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding |
92 | content by blank lines, and the start and end tags of the block should |
93 | not be indented with tabs or spaces. Markdown is smart enough not |
94 | to add extra (unwanted) `<p>` tags around HTML block-level tags. |
95 | |
96 | For 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 | |
108 | Note that Markdown formatting syntax is not processed within block-level |
109 | HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an |
110 | HTML block. |
111 | |
112 | Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be |
113 | used anywhere in a Markdown paragraph, list item, or header. If you |
114 | want, you can even use HTML tags instead of Markdown formatting; e.g. if |
115 | you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's |
116 | link or image syntax, go right ahead. |
117 | |
118 | Unlike block-level HTML tags, Markdown syntax *is* processed within |
119 | span-level tags. |
120 | |
121 | |
122 | <h3 id="autoescape">Automatic Escaping for Special Characters</h3> |
123 | |
124 | In HTML, there are two characters that demand special treatment: `<` |
125 | and `&`. Left angle brackets are used to start tags; ampersands are |
126 | used to denote HTML entities. If you want to use them as literal |
127 | characters, you must escape them as entities, e.g. `<`, and |
128 | `&`. |
129 | |
130 | Ampersands in particular are bedeviling for web writers. If you want to |
131 | write about 'AT&T', you need to write '`AT&T`'. You even need to |
132 | escape ampersands within URLs. Thus, if you want to link to: |
133 | |
134 | http://images.google.com/images?num=30&q=larry+bird |
135 | |
136 | you need to encode the URL as: |
137 | |
138 | http://images.google.com/images?num=30&q=larry+bird |
139 | |
140 | in your anchor tag `href` attribute. Needless to say, this is easy to |
141 | forget, and is probably the single most common source of HTML validation |
142 | errors in otherwise well-marked-up web sites. |
143 | |
144 | Markdown allows you to use these characters naturally, taking care of |
145 | all the necessary escaping for you. If you use an ampersand as part of |
146 | an HTML entity, it remains unchanged; otherwise it will be translated |
147 | into `&`. |
148 | |
149 | So, if you want to include a copyright symbol in your article, you can write: |
150 | |
151 | © |
152 | |
153 | and Markdown will leave it alone. But if you write: |
154 | |
155 | AT&T |
156 | |
157 | Markdown will translate it to: |
158 | |
159 | AT&T |
160 | |
161 | Similarly, because Markdown supports [inline HTML](#html), if you use |
162 | angle brackets as delimiters for HTML tags, Markdown will treat them as |
163 | such. But if you write: |
164 | |
165 | 4 < 5 |
166 | |
167 | Markdown will translate it to: |
168 | |
169 | 4 < 5 |
170 | |
171 | However, inside Markdown code spans and blocks, angle brackets and |
172 | ampersands are *always* encoded automatically. This makes it easy to use |
173 | Markdown to write about HTML code. (As opposed to raw HTML, which is a |
174 | terrible format for writing about HTML syntax, because every single `<` |
175 | and `&` 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 | |
186 | A paragraph is simply one or more consecutive lines of text, separated |
187 | by one or more blank lines. (A blank line is any line that looks like a |
188 | blank line -- a line containing nothing but spaces or tabs is considered |
189 | blank.) Normal paragraphs should not be intended with spaces or tabs. |
190 | |
191 | The implication of the "one or more consecutive lines of text" rule is |
192 | that Markdown supports "hard-wrapped" text paragraphs. This differs |
193 | significantly from most other text-to-HTML formatters (including Movable |
194 | Type's "Convert Line Breaks" option) which translate every line break |
195 | character in a paragraph into a `<br />` tag. |
196 | |
197 | When you *do* want to insert a `<br />` break tag using Markdown, you |
198 | end a line with two or more spaces, then type return. |
199 | |
200 | Yes, 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. |
202 | Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l] |
203 | work 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 | |
212 | Markdown supports two styles of headers, [Setext] [1] and [atx] [2]. |
213 | |
214 | Setext-style headers are "underlined" using equal signs (for first-level |
215 | headers) and dashes (for second-level headers). For example: |
216 | |
217 | This is an H1 |
218 | ============= |
219 | |
220 | This is an H2 |
221 | ------------- |
222 | |
223 | Any number of underlining `=`'s or `-`'s will work. |
224 | |
225 | Atx-style headers use 1-6 hash characters at the start of the line, |
226 | corresponding 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 | |
234 | Optionally, you may "close" atx-style headers. This is purely |
235 | cosmetic -- you can use this if you think it looks better. The |
236 | closing hashes don't even need to match the number of hashes |
237 | used to open the header. (The number of opening hashes |
238 | determines 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 | |
249 | Markdown uses email-style `>` characters for blockquoting. If you're |
250 | familiar with quoting passages of text in an email message, then you |
251 | know how to create a blockquote in Markdown. It looks best if you hard |
252 | wrap 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 | |
261 | Markdown allows you to be lazy and only put the `>` before the first |
262 | line 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 | |
271 | Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by |
272 | adding 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 | |
280 | Blockquotes can contain other Markdown elements, including headers, lists, |
281 | and 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 | |
292 | Any decent text editor should make email-style quoting easy. For |
293 | example, with BBEdit, you can make a selection and choose Increase |
294 | Quote Level from the Text menu. |
295 | |
296 | |
297 | <h3 id="list">Lists</h3> |
298 | |
299 | Markdown supports ordered (numbered) and unordered (bulleted) lists. |
300 | |
301 | Unordered lists use asterisks, pluses, and hyphens -- interchangably |
302 | -- as list markers: |
303 | |
304 | * Red |
305 | * Green |
306 | * Blue |
307 | |
308 | is equivalent to: |
309 | |
310 | + Red |
311 | + Green |
312 | + Blue |
313 | |
314 | and: |
315 | |
316 | - Red |
317 | - Green |
318 | - Blue |
319 | |
320 | Ordered lists use numbers followed by periods: |
321 | |
322 | 1. Bird |
323 | 2. McHale |
324 | 3. Parish |
325 | |
326 | It's important to note that the actual numbers you use to mark the |
327 | list have no effect on the HTML output Markdown produces. The HTML |
328 | Markdown produces from the above list is: |
329 | |
330 | <ol> |
331 | <li>Bird</li> |
332 | <li>McHale</li> |
333 | <li>Parish</li> |
334 | </ol> |
335 | |
336 | If you instead wrote the list in Markdown like this: |
337 | |
338 | 1. Bird |
339 | 1. McHale |
340 | 1. Parish |
341 | |
342 | or even: |
343 | |
344 | 3. Bird |
345 | 1. McHale |
346 | 8. Parish |
347 | |
348 | you'd get the exact same HTML output. The point is, if you want to, |
349 | you can use ordinal numbers in your ordered Markdown lists, so that |
350 | the numbers in your source match the numbers in your published HTML. |
351 | But if you want to be lazy, you don't have to. |
352 | |
353 | If you do use lazy list numbering, however, you should still start the |
354 | list with the number 1. At some point in the future, Markdown may support |
355 | starting ordered lists at an arbitrary number. |
356 | |
357 | List markers typically start at the left margin, but may be indented by |
358 | up to three spaces. List markers must be followed by one or more spaces |
359 | or a tab. |
360 | |
361 | To 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 | |
369 | But 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 | |
377 | If list items are separated by blank lines, Markdown will wrap the |
378 | items in `<p>` tags in the HTML output. For example, this input: |
379 | |
380 | * Bird |
381 | * Magic |
382 | |
383 | will turn into: |
384 | |
385 | <ul> |
386 | <li>Bird</li> |
387 | <li>Magic</li> |
388 | </ul> |
389 | |
390 | But this: |
391 | |
392 | * Bird |
393 | |
394 | * Magic |
395 | |
396 | will turn into: |
397 | |
398 | <ul> |
399 | <li><p>Bird</p></li> |
400 | <li><p>Magic</p></li> |
401 | </ul> |
402 | |
403 | List items may consist of multiple paragraphs. Each subsequent |
404 | paragraph in a list item must be intended by either 4 spaces |
405 | or 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 | |
417 | It looks nice if you indent every line of the subsequent |
418 | paragraphs, but here again, Markdown will allow you to be |
419 | lazy: |
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 | |
429 | To put a blockquote within a list item, the blockquote's `>` |
430 | delimiters need to be indented: |
431 | |
432 | * A list item with a blockquote: |
433 | |
434 | > This is a blockquote |
435 | > inside a list item. |
436 | |
437 | To put a code block within a list item, the code block needs |
438 | to be indented *twice* -- 8 spaces or two tabs: |
439 | |
440 | * A list item with a code block: |
441 | |
442 | <code goes here> |
443 | |
444 | |
445 | It's worth noting that it's possible to trigger an ordered list by |
446 | accident, by writing something like this: |
447 | |
448 | 1986. What a great season. |
449 | |
450 | In other words, a *number-period-space* sequence at the beginning of a |
451 | line. 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 | |
459 | Pre-formatted code blocks are used for writing about programming or |
460 | markup source code. Rather than forming normal paragraphs, the lines |
461 | of a code block are interpreted literally. Markdown wraps a code block |
462 | in both `<pre>` and `<code>` tags. |
463 | |
464 | To produce a code block in Markdown, simply indent every line of the |
465 | block 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 | |
471 | Markdown will generate: |
472 | |
473 | <p>This is a normal paragraph:</p> |
474 | |
475 | <pre><code>This is a code block. |
476 | </code></pre> |
477 | |
478 | One level of indentation -- 4 spaces or 1 tab -- is removed from each |
479 | line 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 | |
487 | will 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 | |
496 | A code block continues until it reaches a line that is not indented |
497 | (or the end of the article). |
498 | |
499 | Within a code block, ampersands (`&`) and angle brackets (`<` and `>`) |
500 | are automatically converted into HTML entities. This makes it very |
501 | easy to include example HTML source code using Markdown -- just paste |
502 | it and indent it, and Markdown will handle the hassle of encoding the |
503 | ampersands and angle brackets. For example, this: |
504 | |
505 | <div class="footer"> |
506 | © 2004 Foo Corporation |
507 | </div> |
508 | |
509 | will turn into: |
510 | |
511 | <pre><code><div class="footer"> |
512 | &copy; 2004 Foo Corporation |
513 | </div> |
514 | </code></pre> |
515 | |
516 | Regular Markdown syntax is not processed within code blocks. E.g., |
517 | asterisks are just literal asterisks within a code block. This means |
518 | it's also easy to use Markdown to write about Markdown's own syntax. |
519 | |
520 | |
521 | |
522 | <h3 id="hr">Horizontal Rules</h3> |
523 | |
524 | You can produce a horizontal rule tag (`<hr />`) by placing three or |
525 | more hyphens, asterisks, or underscores on a line by themselves. If you |
526 | wish, you may use spaces between the hyphens or asterisks. Each of the |
527 | following 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 | |
548 | Markdown supports two style of links: *inline* and *reference*. |
549 | |
550 | In both styles, the link text is delimited by [square brackets]. |
551 | |
552 | To create an inline link, use a set of regular parentheses immediately |
553 | after the link text's closing square bracket. Inside the parentheses, |
554 | put the URL where you want the link to point, along with an *optional* |
555 | title 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 | |
561 | Will 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 | |
569 | If you're referring to a local resource on the same server, you can |
570 | use relative paths: |
571 | |
572 | See my [About](/about/) page for details. |
573 | |
574 | Reference-style links use a second set of square brackets, inside |
575 | which you place a label of your choosing to identify the link: |
576 | |
577 | This is [an example][id] reference-style link. |
578 | |
579 | You can optionally use a space to separate the sets of brackets: |
580 | |
581 | This is [an example] [id] reference-style link. |
582 | |
583 | Then, anywhere in the document, you define your link label like this, |
584 | on a line by itself: |
585 | |
586 | [id]: http://example.com/ "Optional Title Here" |
587 | |
588 | That 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 | |
598 | The link URL may, optionally, be surrounded by angle brackets: |
599 | |
600 | [id]: <http://example.com/> "Optional Title Here" |
601 | |
602 | You can put the title attribute on the next line and use extra spaces |
603 | or 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 | |
608 | Link definitions are only used for creating links during Markdown |
609 | processing, and are stripped from your document in the HTML output. |
610 | |
611 | Link 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 | |
616 | are equivalent. |
617 | |
618 | The *implicit link name* shortcut allows you to omit the name of the |
619 | link, in which case the link text itself is used as the name. |
620 | Just 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 | |
625 | And then define the link: |
626 | |
627 | [Google]: http://google.com/ |
628 | |
629 | Because link names may contain spaces, this shortcut even works for |
630 | multiple words in the link text: |
631 | |
632 | Visit [Daring Fireball][] for more information. |
633 | |
634 | And then define the link: |
635 | |
636 | [Daring Fireball]: http://daringfireball.net/ |
637 | |
638 | Link definitions can be placed anywhere in your Markdown document. I |
639 | tend to put them immediately after each paragraph in which they're |
640 | used, but if you want, you can put them all at the end of your |
641 | document, sort of like footnotes. |
642 | |
643 | Here'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 | |
652 | Using 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 | |
661 | Both 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 | |
668 | For comparison, here is the same paragraph written using |
669 | Markdown'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 | |
675 | The point of reference-style links is not that they're easier to |
676 | write. The point is that with reference-style links, your document |
677 | source is vastly more readable. Compare the above examples: using |
678 | reference-style links, the paragraph itself is only 81 characters |
679 | long; with inline-style links, it's 176 characters; and as raw HTML, |
680 | it's 234 characters. In the raw HTML, there's more markup than there |
681 | is text. |
682 | |
683 | With Markdown's reference-style links, a source document much more |
684 | closely resembles the final output, as rendered in a browser. By |
685 | allowing you to move the markup-related metadata out of the paragraph, |
686 | you can add links without interrupting the narrative flow of your |
687 | prose. |
688 | |
689 | |
690 | <h3 id="em">Emphasis</h3> |
691 | |
692 | Markdown treats asterisks (`*`) and underscores (`_`) as indicators of |
693 | emphasis. Text wrapped with one `*` or `_` will be wrapped with an |
694 | HTML `<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 | |
705 | will 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 | |
715 | You can use whichever style you prefer; the lone restriction is that |
716 | the same character must be used to open and close an emphasis span. |
717 | |
718 | Emphasis can be used in the middle of a word: |
719 | |
720 | un*fucking*believable |
721 | |
722 | But if you surround an `*` or `_` with spaces, it'll be treated as a |
723 | literal asterisk or underscore. |
724 | |
725 | To produce a literal asterisk or underscore at a position where it |
726 | would otherwise be used as an emphasis delimiter, you can backslash |
727 | escape it: |
728 | |
729 | \*this text is surrounded by literal asterisks\* |
730 | |
731 | |
732 | |
733 | <h3 id="code">Code</h3> |
734 | |
735 | To indicate a span of code, wrap it with backtick quotes (`` ` ``). |
736 | Unlike a pre-formatted code block, a code span indicates code within a |
737 | normal paragraph. For example: |
738 | |
739 | Use the `printf()` function. |
740 | |
741 | will produce: |
742 | |
743 | <p>Use the <code>printf()</code> function.</p> |
744 | |
745 | To include a literal backtick character within a code span, you can use |
746 | multiple backticks as the opening and closing delimiters: |
747 | |
748 | ``There is a literal backtick (`) here.`` |
749 | |
750 | which will produce this: |
751 | |
752 | <p><code>There is a literal backtick (`) here.</code></p> |
753 | |
754 | The backtick delimiters surrounding a code span may include spaces -- |
755 | one after the opening, one before the closing. This allows you to place |
756 | literal 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 | |
762 | will 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 | |
768 | With a code span, ampersands and angle brackets are encoded as HTML |
769 | entities automatically, which makes it easy to include example HTML |
770 | tags. Markdown will turn this: |
771 | |
772 | Please don't use any `<blink>` tags. |
773 | |
774 | into: |
775 | |
776 | <p>Please don't use any <code><blink></code> tags.</p> |
777 | |
778 | You can write this: |
779 | |
780 | `—` is the decimal-encoded equivalent of `—`. |
781 | |
782 | to 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 | |
791 | Admittedly, it's fairly difficult to devise a "natural" syntax for |
792 | placing images into a plain text document format. |
793 | |
794 | Markdown uses an image syntax that is intended to resemble the syntax |
795 | for links, allowing for two styles: *inline* and *reference*. |
796 | |
797 | Inline image syntax looks like this: |
798 | |
799 | ![Alt text](/path/to/img.jpg) |
800 | |
801 | ![Alt text](/path/to/img.jpg "Optional title") |
802 | |
803 | That 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 | |
812 | Reference-style image syntax looks like this: |
813 | |
814 | ![Alt text][id] |
815 | |
816 | Where "id" is the name of a defined image reference. Image references |
817 | are defined using syntax identical to link references: |
818 | |
819 | [id]: url/to/image "Optional title attribute" |
820 | |
821 | As of this writing, Markdown has no syntax for specifying the |
822 | dimensions of an image; if this is important to you, you can simply |
823 | use regular HTML `<img>` tags. |
824 | |
825 | |
826 | * * * |
827 | |
828 | |
829 | <h2 id="misc">Miscellaneous</h2> |
830 | |
831 | <h3 id="autolink">Automatic Links</h3> |
832 | |
833 | 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: |
834 | |
835 | <http://example.com/> |
836 | |
837 | Markdown will turn this into: |
838 | |
839 | <a href="http://example.com/">http://example.com/</a> |
840 | |
841 | Automatic links for email addresses work similarly, except that |
842 | Markdown will also perform a bit of randomized decimal and hex |
843 | entity-encoding to help obscure your address from address-harvesting |
844 | spambots. For example, Markdown will turn this: |
845 | |
846 | <address@example.com> |
847 | |
848 | into something like this: |
849 | |
850 | <a href="mailto:addre |
851 | ss@example.co |
852 | m">address@exa |
853 | mple.com</a> |
854 | |
855 | which 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 |
858 | most, address-harvesting bots, but it definitely won't fool all of |
859 | them. It's better than nothing, but an address published in this way |
860 | will probably eventually start receiving spam.) |
861 | |
862 | |
863 | |
864 | <h3 id="backslash">Backslash Escapes</h3> |
865 | |
866 | Markdown allows you to use backslash escapes to generate literal |
867 | characters which would otherwise have special meaning in Markdown's |
868 | formatting syntax. For example, if you wanted to surround a word with |
869 | literal asterisks (instead of an HTML `<em>` tag), you can backslashes |
870 | before the asterisks, like this: |
871 | |
872 | \*literal asterisks\* |
873 | |
874 | Markdown 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 |