nronn 0.10.1.pre2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (96) hide show
  1. checksums.yaml +7 -0
  2. data/AUTHORS +8 -0
  3. data/CHANGES +230 -0
  4. data/Gemfile +2 -0
  5. data/Gemfile.lock +72 -0
  6. data/INSTALLING.md +92 -0
  7. data/LICENSE.txt +12 -0
  8. data/README.md +131 -0
  9. data/Rakefile +153 -0
  10. data/bin/ronn +253 -0
  11. data/completion/bash/ronn +32 -0
  12. data/completion/zsh/_ronn +24 -0
  13. data/config.ru +15 -0
  14. data/lib/ronn/document.rb +530 -0
  15. data/lib/ronn/index.rb +180 -0
  16. data/lib/ronn/roff.rb +393 -0
  17. data/lib/ronn/server.rb +67 -0
  18. data/lib/ronn/template/80c.css +6 -0
  19. data/lib/ronn/template/dark.css +18 -0
  20. data/lib/ronn/template/darktoc.css +17 -0
  21. data/lib/ronn/template/default.html +41 -0
  22. data/lib/ronn/template/man.css +100 -0
  23. data/lib/ronn/template/print.css +5 -0
  24. data/lib/ronn/template/screen.css +105 -0
  25. data/lib/ronn/template/toc.css +27 -0
  26. data/lib/ronn/template.rb +173 -0
  27. data/lib/ronn/utils.rb +57 -0
  28. data/lib/ronn.rb +47 -0
  29. data/man/index.html +78 -0
  30. data/man/index.txt +15 -0
  31. data/man/ronn-format.7 +145 -0
  32. data/man/ronn-format.7.ronn +157 -0
  33. data/man/ronn.1 +227 -0
  34. data/man/ronn.1.ronn +316 -0
  35. data/nronn.gemspec +136 -0
  36. data/test/angle_bracket_syntax.html +27 -0
  37. data/test/angle_bracket_syntax.roff +24 -0
  38. data/test/angle_bracket_syntax.ronn +22 -0
  39. data/test/backticks.html +14 -0
  40. data/test/backticks.ronn +10 -0
  41. data/test/basic_document.html +8 -0
  42. data/test/basic_document.ronn +4 -0
  43. data/test/circumflexes.ronn +1 -0
  44. data/test/code_blocks.html +38 -0
  45. data/test/code_blocks.roff +38 -0
  46. data/test/code_blocks.ronn +41 -0
  47. data/test/code_blocks_regression +19 -0
  48. data/test/code_blocks_regression.html +38 -0
  49. data/test/code_blocks_regression.ronn +40 -0
  50. data/test/contest.rb +70 -0
  51. data/test/custom_title_document.html +6 -0
  52. data/test/custom_title_document.ronn +5 -0
  53. data/test/definition_list_syntax.html +25 -0
  54. data/test/definition_list_syntax.roff +19 -0
  55. data/test/definition_list_syntax.ronn +18 -0
  56. data/test/dots_at_line_start_test.roff +19 -0
  57. data/test/dots_at_line_start_test.ronn +12 -0
  58. data/test/ellipses.roff +7 -0
  59. data/test/ellipses.ronn +7 -0
  60. data/test/entity_encoding_test.html +42 -0
  61. data/test/entity_encoding_test.roff +51 -0
  62. data/test/entity_encoding_test.ronn +34 -0
  63. data/test/index.txt +8 -0
  64. data/test/markdown_syntax.html +954 -0
  65. data/test/markdown_syntax.roff +907 -0
  66. data/test/markdown_syntax.ronn +881 -0
  67. data/test/middle_paragraph.html +14 -0
  68. data/test/middle_paragraph.roff +9 -0
  69. data/test/middle_paragraph.ronn +10 -0
  70. data/test/missing_spaces.roff +7 -0
  71. data/test/missing_spaces.ronn +2 -0
  72. data/test/nested_list.ronn +19 -0
  73. data/test/nested_list_with_code.html +14 -0
  74. data/test/nested_list_with_code.roff +11 -0
  75. data/test/nested_list_with_code.ronn +6 -0
  76. data/test/ordered_list.html +28 -0
  77. data/test/ordered_list.roff +25 -0
  78. data/test/ordered_list.ronn +21 -0
  79. data/test/page.with.periods.in.name.5.ronn +4 -0
  80. data/test/pre_block_with_quotes.roff +8 -0
  81. data/test/pre_block_with_quotes.ronn +6 -0
  82. data/test/section_reference_links.html +16 -0
  83. data/test/section_reference_links.roff +7 -0
  84. data/test/section_reference_links.ronn +12 -0
  85. data/test/single_quotes.html +11 -0
  86. data/test/single_quotes.roff +5 -0
  87. data/test/single_quotes.ronn +9 -0
  88. data/test/tables.ronn +24 -0
  89. data/test/test_ronn.rb +124 -0
  90. data/test/test_ronn_document.rb +186 -0
  91. data/test/test_ronn_index.rb +73 -0
  92. data/test/titleless_document.html +9 -0
  93. data/test/titleless_document.ronn +3 -0
  94. data/test/underline_spacing_test.roff +13 -0
  95. data/test/underline_spacing_test.ronn +11 -0
  96. metadata +309 -0
@@ -0,0 +1,954 @@
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>