ronn-ng 0.7.4

Sign up to get free protection for your applications and to get access to all the features.
Files changed (68) hide show
  1. checksums.yaml +7 -0
  2. data/AUTHORS +8 -0
  3. data/CHANGES +184 -0
  4. data/INSTALLING +20 -0
  5. data/LICENSE.txt +11 -0
  6. data/README.md +113 -0
  7. data/Rakefile +163 -0
  8. data/bin/ronn +223 -0
  9. data/config.ru +15 -0
  10. data/lib/ronn.rb +50 -0
  11. data/lib/ronn/document.rb +495 -0
  12. data/lib/ronn/index.rb +183 -0
  13. data/lib/ronn/roff.rb +302 -0
  14. data/lib/ronn/server.rb +70 -0
  15. data/lib/ronn/template.rb +171 -0
  16. data/lib/ronn/template/80c.css +6 -0
  17. data/lib/ronn/template/dark.css +18 -0
  18. data/lib/ronn/template/darktoc.css +17 -0
  19. data/lib/ronn/template/default.html +41 -0
  20. data/lib/ronn/template/man.css +100 -0
  21. data/lib/ronn/template/print.css +5 -0
  22. data/lib/ronn/template/screen.css +105 -0
  23. data/lib/ronn/template/toc.css +27 -0
  24. data/lib/ronn/utils.rb +55 -0
  25. data/man/index.html +78 -0
  26. data/man/index.txt +15 -0
  27. data/man/ronn-format.7 +201 -0
  28. data/man/ronn-format.7.ronn +157 -0
  29. data/man/ronn.1 +325 -0
  30. data/man/ronn.1.ronn +306 -0
  31. data/ronn-ng.gemspec +97 -0
  32. data/test/angle_bracket_syntax.html +18 -0
  33. data/test/angle_bracket_syntax.ronn +12 -0
  34. data/test/basic_document.html +9 -0
  35. data/test/basic_document.ronn +4 -0
  36. data/test/contest.rb +68 -0
  37. data/test/custom_title_document.html +6 -0
  38. data/test/custom_title_document.ronn +5 -0
  39. data/test/definition_list_syntax.html +21 -0
  40. data/test/definition_list_syntax.roff +26 -0
  41. data/test/definition_list_syntax.ronn +18 -0
  42. data/test/dots_at_line_start_test.roff +10 -0
  43. data/test/dots_at_line_start_test.ronn +4 -0
  44. data/test/entity_encoding_test.html +35 -0
  45. data/test/entity_encoding_test.roff +61 -0
  46. data/test/entity_encoding_test.ronn +25 -0
  47. data/test/index.txt +8 -0
  48. data/test/markdown_syntax.html +957 -0
  49. data/test/markdown_syntax.roff +1467 -0
  50. data/test/markdown_syntax.ronn +881 -0
  51. data/test/middle_paragraph.html +15 -0
  52. data/test/middle_paragraph.roff +13 -0
  53. data/test/middle_paragraph.ronn +10 -0
  54. data/test/missing_spaces.roff +9 -0
  55. data/test/missing_spaces.ronn +2 -0
  56. data/test/pre_block_with_quotes.roff +13 -0
  57. data/test/pre_block_with_quotes.ronn +6 -0
  58. data/test/section_reference_links.html +17 -0
  59. data/test/section_reference_links.roff +10 -0
  60. data/test/section_reference_links.ronn +12 -0
  61. data/test/test_ronn.rb +110 -0
  62. data/test/test_ronn_document.rb +186 -0
  63. data/test/test_ronn_index.rb +73 -0
  64. data/test/titleless_document.html +10 -0
  65. data/test/titleless_document.ronn +3 -0
  66. data/test/underline_spacing_test.roff +21 -0
  67. data/test/underline_spacing_test.ronn +11 -0
  68. metadata +176 -0
@@ -0,0 +1,881 @@
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/>