ronn-ng 0.10.1.pre1 → 0.10.1.pre2

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