ronn-ng 0.10.0.pre.SNAPSHOT → 0.10.1.pre2

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