maruku 0.5.3 → 0.5.4
Sign up to get free protection for your applications and to get access to all the features.
- data/bin/maruku +14 -6
- data/bin/marutest +19 -10
- data/docs/changelog.html +49 -8
- data/docs/changelog.md +26 -1
- data/docs/entity_test.html +1 -1
- data/docs/exd.html +43 -24
- data/docs/index.html +4 -6
- data/docs/markdown_syntax.html +81 -170
- data/docs/maruku.html +4 -6
- data/docs/maruku.md +1 -1
- data/docs/proposal.html +21 -41
- data/lib/maruku.rb +5 -0
- data/lib/maruku/attributes.rb +3 -2
- data/lib/maruku/defaults.rb +3 -1
- data/lib/maruku/ext/math.rb +30 -0
- data/lib/maruku/ext/math/elements.rb +3 -2
- data/lib/maruku/ext/math/parsing.rb +81 -58
- data/lib/maruku/ext/math/to_html.rb +5 -5
- data/lib/maruku/helpers.rb +2 -0
- data/lib/maruku/input/charsource.rb +1 -1
- data/lib/maruku/input/extensions.rb +6 -5
- data/lib/maruku/input/parse_block.rb +7 -8
- data/lib/maruku/input/parse_doc.rb +1 -1
- data/lib/maruku/input/parse_span_better.rb +4 -4
- data/lib/maruku/input_textile2/t2_parser.rb +163 -0
- data/lib/maruku/maruku.rb +1 -1
- data/lib/maruku/output/s5/fancy.rb +756 -0
- data/lib/maruku/output/s5/to_s5.rb +104 -0
- data/lib/maruku/output/to_html.rb +103 -49
- data/lib/maruku/string_utils.rb +1 -1
- data/lib/maruku/textile2.rb +1 -0
- data/lib/maruku/version.rb +3 -1
- data/maruku_gem.rb +33 -0
- data/tests/s5/s5profiling.md +48 -0
- data/tests/unittest/blanks_in_code.md +6 -12
- data/tests/unittest/code3.md +3 -5
- data/tests/unittest/data_loss.md +53 -0
- data/tests/unittest/email.md +2 -2
- data/tests/unittest/entities.md +3 -5
- data/tests/unittest/footnotes.md +5 -5
- data/tests/unittest/ie.md +1 -1
- data/tests/unittest/images.md +2 -2
- data/tests/unittest/inline_html.md +6 -10
- data/tests/unittest/links.md +1 -1
- data/tests/unittest/list2.md +5 -5
- data/tests/unittest/lists.md +13 -13
- data/tests/unittest/lists_ol.md +13 -13
- data/tests/unittest/math/math2.md +84 -0
- data/tests/unittest/math/notmath.md +48 -0
- data/tests/unittest/syntax_hl.md +3 -5
- metadata +11 -2
data/docs/markdown_syntax.html
CHANGED
@@ -96,8 +96,7 @@
|
|
96
96
|
</tr>
|
97
97
|
</table>
|
98
98
|
|
99
|
-
This is another regular paragraph
|
100
|
-
</code></pre>
|
99
|
+
This is another regular paragraph.</code></pre>
|
101
100
|
|
102
101
|
<p>Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style <code>*emphasis*</code> inside an HTML block.</p>
|
103
102
|
|
@@ -109,13 +108,11 @@ This is another regular paragraph.
|
|
109
108
|
|
110
109
|
<p>Ampersands in particular are bedeviling for web writers. If you want to write about ‘AT&T’, you need to write ’<code>AT&amp;T</code>’. You even need to escape ampersands within URLs. Thus, if you want to link to:</p>
|
111
110
|
|
112
|
-
<pre><code>http://images.google.com/images?num=30&q=larry+bird
|
113
|
-
</code></pre>
|
111
|
+
<pre><code>http://images.google.com/images?num=30&q=larry+bird</code></pre>
|
114
112
|
|
115
113
|
<p>you need to encode the URL as:</p>
|
116
114
|
|
117
|
-
<pre><code>http://images.google.com/images?num=30&amp;q=larry+bird
|
118
|
-
</code></pre>
|
115
|
+
<pre><code>http://images.google.com/images?num=30&amp;q=larry+bird</code></pre>
|
119
116
|
|
120
117
|
<p>in your anchor tag <code>href</code> attribute. Needless to say, this is easy to forget, and is probably the single most common source of HTML validation errors in otherwise well-marked-up web sites.</p>
|
121
118
|
|
@@ -123,28 +120,23 @@ This is another regular paragraph.
|
|
123
120
|
|
124
121
|
<p>So, if you want to include a copyright symbol in your article, you can write:</p>
|
125
122
|
|
126
|
-
<pre><code>&copy
|
127
|
-
</code></pre>
|
123
|
+
<pre><code>&copy;</code></pre>
|
128
124
|
|
129
125
|
<p>and Markdown will leave it alone. But if you write:</p>
|
130
126
|
|
131
|
-
<pre><code>AT&T
|
132
|
-
</code></pre>
|
127
|
+
<pre><code>AT&T</code></pre>
|
133
128
|
|
134
129
|
<p>Markdown will translate it to:</p>
|
135
130
|
|
136
|
-
<pre><code>AT&amp;T
|
137
|
-
</code></pre>
|
131
|
+
<pre><code>AT&amp;T</code></pre>
|
138
132
|
|
139
133
|
<p>Similarly, because Markdown supports <a href='#html'>inline HTML</a>, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:</p>
|
140
134
|
|
141
|
-
<pre><code>4 < 5
|
142
|
-
</code></pre>
|
135
|
+
<pre><code>4 < 5</code></pre>
|
143
136
|
|
144
137
|
<p>Markdown will translate it to:</p>
|
145
138
|
|
146
|
-
<pre><code>4 &lt; 5
|
147
|
-
</code></pre>
|
139
|
+
<pre><code>4 &lt; 5</code></pre>
|
148
140
|
|
149
141
|
<p>However, inside Markdown code spans and blocks, angle brackets and ampersands are <em>always</em> encoded automatically. This makes it easy to use Markdown to write about HTML code. (As opposed to raw HTML, which is a terrible format for writing about HTML syntax, because every single <code><</code> and <code>&</code> in your example code needs to be escaped.)</p>
|
150
142
|
<hr /><h2 id='block'>Block Elements</h2><h3 id='p'>Paragraphs and Line Breaks</h3>
|
@@ -164,8 +156,7 @@ This is another regular paragraph.
|
|
164
156
|
=============
|
165
157
|
|
166
158
|
This is an H2
|
167
|
-
|
168
|
-
</code></pre>
|
159
|
+
-------------</code></pre>
|
169
160
|
|
170
161
|
<p>Any number of underlining <code>=</code>’s or <code>-</code>’s will work.</p>
|
171
162
|
|
@@ -175,8 +166,7 @@ This is an H2
|
|
175
166
|
|
176
167
|
## This is an H2
|
177
168
|
|
178
|
-
###### This is an H6
|
179
|
-
</code></pre>
|
169
|
+
###### This is an H6</code></pre>
|
180
170
|
|
181
171
|
<p>Optionally, you may “close” atx-style headers. This is purely cosmetic – you can use this if you think it looks better. The closing hashes don’t even need to match the number of hashes used to open the header. (The number of opening hashes determines the header level.) :</p>
|
182
172
|
|
@@ -184,9 +174,7 @@ This is an H2
|
|
184
174
|
|
185
175
|
## This is an H2 ##
|
186
176
|
|
187
|
-
### This is an H3
|
188
|
-
|
189
|
-
</code></pre>
|
177
|
+
### This is an H3 ######</code></pre>
|
190
178
|
<h3 id='blockquote'>Blockquotes</h3>
|
191
179
|
<p>Markdown uses email-style <code>></code> characters for blockquoting. If you’re familiar with quoting passages of text in an email message, then you know how to create a blockquote in Markdown. It looks best if you hard wrap the text and put a <code>></code> before every line:</p>
|
192
180
|
|
@@ -195,8 +183,7 @@ This is an H2
|
|
195
183
|
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
196
184
|
>
|
197
185
|
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
198
|
-
> id sem consectetuer libero luctus adipiscing
|
199
|
-
</code></pre>
|
186
|
+
> id sem consectetuer libero luctus adipiscing.</code></pre>
|
200
187
|
|
201
188
|
<p>Markdown allows you to be lazy and only put the <code>></code> before the first line of a hard-wrapped paragraph:</p>
|
202
189
|
|
@@ -205,8 +192,7 @@ consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
|
|
205
192
|
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
|
206
193
|
|
207
194
|
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
|
208
|
-
id sem consectetuer libero luctus adipiscing
|
209
|
-
</code></pre>
|
195
|
+
id sem consectetuer libero luctus adipiscing.</code></pre>
|
210
196
|
|
211
197
|
<p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by adding additional levels of <code>></code>:</p>
|
212
198
|
|
@@ -214,8 +200,7 @@ id sem consectetuer libero luctus adipiscing.
|
|
214
200
|
>
|
215
201
|
> > This is nested blockquote.
|
216
202
|
>
|
217
|
-
> Back to the first level
|
218
|
-
</code></pre>
|
203
|
+
> Back to the first level.</code></pre>
|
219
204
|
|
220
205
|
<p>Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:</p>
|
221
206
|
|
@@ -226,8 +211,7 @@ id sem consectetuer libero luctus adipiscing.
|
|
226
211
|
>
|
227
212
|
> Here's some example code:
|
228
213
|
>
|
229
|
-
> return shell_exec("echo $input | $markdown_script")
|
230
|
-
</code></pre>
|
214
|
+
> return shell_exec("echo $input | $markdown_script");</code></pre>
|
231
215
|
|
232
216
|
<p>Any decent text editor should make email-style quoting easy. For example, with BBEdit, you can make a selection and choose Increase Quote Level from the Text menu.</p>
|
233
217
|
<h3 id='list'>Lists</h3>
|
@@ -237,29 +221,25 @@ id sem consectetuer libero luctus adipiscing.
|
|
237
221
|
|
238
222
|
<pre><code>* Red
|
239
223
|
* Green
|
240
|
-
* Blue
|
241
|
-
</code></pre>
|
224
|
+
* Blue</code></pre>
|
242
225
|
|
243
226
|
<p>is equivalent to:</p>
|
244
227
|
|
245
228
|
<pre><code>+ Red
|
246
229
|
+ Green
|
247
|
-
+ Blue
|
248
|
-
</code></pre>
|
230
|
+
+ Blue</code></pre>
|
249
231
|
|
250
232
|
<p>and:</p>
|
251
233
|
|
252
234
|
<pre><code>- Red
|
253
235
|
- Green
|
254
|
-
- Blue
|
255
|
-
</code></pre>
|
236
|
+
- Blue</code></pre>
|
256
237
|
|
257
238
|
<p>Ordered lists use numbers followed by periods:</p>
|
258
239
|
|
259
240
|
<pre><code>1. Bird
|
260
241
|
2. McHale
|
261
|
-
3. Parish
|
262
|
-
</code></pre>
|
242
|
+
3. Parish</code></pre>
|
263
243
|
|
264
244
|
<p>It’s important to note that the actual numbers you use to mark the list have no effect on the HTML output Markdown produces. The HTML Markdown produces from the above list is:</p>
|
265
245
|
|
@@ -267,22 +247,19 @@ id sem consectetuer libero luctus adipiscing.
|
|
267
247
|
<li>Bird</li>
|
268
248
|
<li>McHale</li>
|
269
249
|
<li>Parish</li>
|
270
|
-
</ol>
|
271
|
-
</code></pre>
|
250
|
+
</ol></code></pre>
|
272
251
|
|
273
252
|
<p>If you instead wrote the list in Markdown like this:</p>
|
274
253
|
|
275
254
|
<pre><code>1. Bird
|
276
255
|
1. McHale
|
277
|
-
1. Parish
|
278
|
-
</code></pre>
|
256
|
+
1. Parish</code></pre>
|
279
257
|
|
280
258
|
<p>or even:</p>
|
281
259
|
|
282
260
|
<pre><code>3. Bird
|
283
261
|
1. McHale
|
284
|
-
8. Parish
|
285
|
-
</code></pre>
|
262
|
+
8. Parish</code></pre>
|
286
263
|
|
287
264
|
<p>you’d get the exact same HTML output. The point is, if you want to, you can use ordinal numbers in your ordered Markdown lists, so that the numbers in your source match the numbers in your published HTML. But if you want to be lazy, you don’t have to.</p>
|
288
265
|
|
@@ -296,8 +273,7 @@ id sem consectetuer libero luctus adipiscing.
|
|
296
273
|
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
297
274
|
viverra nec, fringilla in, laoreet vitae, risus.
|
298
275
|
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
299
|
-
Suspendisse id sem consectetuer libero luctus adipiscing
|
300
|
-
</code></pre>
|
276
|
+
Suspendisse id sem consectetuer libero luctus adipiscing.</code></pre>
|
301
277
|
|
302
278
|
<p>But if you want to be lazy, you don’t have to:</p>
|
303
279
|
|
@@ -305,37 +281,32 @@ id sem consectetuer libero luctus adipiscing.
|
|
305
281
|
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
|
306
282
|
viverra nec, fringilla in, laoreet vitae, risus.
|
307
283
|
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
|
308
|
-
Suspendisse id sem consectetuer libero luctus adipiscing
|
309
|
-
</code></pre>
|
284
|
+
Suspendisse id sem consectetuer libero luctus adipiscing.</code></pre>
|
310
285
|
|
311
286
|
<p>If list items are separated by blank lines, Markdown will wrap the items in <code><p></code> tags in the HTML output. For example, this input:</p>
|
312
287
|
|
313
288
|
<pre><code>* Bird
|
314
|
-
* Magic
|
315
|
-
</code></pre>
|
289
|
+
* Magic</code></pre>
|
316
290
|
|
317
291
|
<p>will turn into:</p>
|
318
292
|
|
319
293
|
<pre><code><ul>
|
320
294
|
<li>Bird</li>
|
321
295
|
<li>Magic</li>
|
322
|
-
</ul>
|
323
|
-
</code></pre>
|
296
|
+
</ul></code></pre>
|
324
297
|
|
325
298
|
<p>But this:</p>
|
326
299
|
|
327
300
|
<pre><code>* Bird
|
328
301
|
|
329
|
-
* Magic
|
330
|
-
</code></pre>
|
302
|
+
* Magic</code></pre>
|
331
303
|
|
332
304
|
<p>will turn into:</p>
|
333
305
|
|
334
306
|
<pre><code><ul>
|
335
307
|
<li><p>Bird</p></li>
|
336
308
|
<li><p>Magic</p></li>
|
337
|
-
</ul>
|
338
|
-
</code></pre>
|
309
|
+
</ul></code></pre>
|
339
310
|
|
340
311
|
<p>List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be intended by either 4 spaces or one tab:</p>
|
341
312
|
|
@@ -347,8 +318,7 @@ Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
347
318
|
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
|
348
319
|
sit amet velit.
|
349
320
|
|
350
|
-
2. Suspendisse id sem consectetuer libero luctus adipiscing
|
351
|
-
</code></pre>
|
321
|
+
2. Suspendisse id sem consectetuer libero luctus adipiscing.</code></pre>
|
352
322
|
|
353
323
|
<p>It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:</p>
|
354
324
|
|
@@ -358,36 +328,28 @@ Suspendisse id sem consectetuer libero luctus adipiscing.
|
|
358
328
|
only required to indent the first line. Lorem ipsum dolor
|
359
329
|
sit amet, consectetuer adipiscing elit.
|
360
330
|
|
361
|
-
* Another item in the same list
|
362
|
-
</code></pre>
|
331
|
+
* Another item in the same list.</code></pre>
|
363
332
|
|
364
333
|
<p>To put a blockquote within a list item, the blockquote’s <code>></code> delimiters need to be indented:</p>
|
365
334
|
|
366
335
|
<pre><code>* A list item with a blockquote:
|
367
336
|
|
368
337
|
> This is a blockquote
|
369
|
-
> inside a list item
|
370
|
-
</code></pre>
|
338
|
+
> inside a list item.</code></pre>
|
371
339
|
|
372
340
|
<p>To put a code block within a list item, the code block needs to be indented <em>twice</em> – 8 spaces or two tabs:</p>
|
373
341
|
|
374
342
|
<pre><code>* A list item with a code block:
|
375
343
|
|
376
|
-
<code goes here>
|
377
|
-
|
378
|
-
</code></pre>
|
344
|
+
<code goes here></code></pre>
|
379
345
|
|
380
346
|
<p>It’s worth noting that it’s possible to trigger an ordered list by accident, by writing something like this:</p>
|
381
347
|
|
382
|
-
<pre><code>1986. What a great season
|
383
|
-
</code></pre>
|
348
|
+
<pre><code>1986. What a great season.</code></pre>
|
384
349
|
|
385
350
|
<p>In other words, a <em>number-period-space</em> sequence at the beginning of a line. To avoid this, you can backslash-escape the period:</p>
|
386
351
|
|
387
|
-
<pre><code>1986\. What a great season
|
388
|
-
|
389
|
-
|
390
|
-
</code></pre>
|
352
|
+
<pre><code>1986\. What a great season.</code></pre>
|
391
353
|
<h3 id='precode'>Code Blocks</h3>
|
392
354
|
<p>Pre-formatted code blocks are used for writing about programming or markup source code. Rather than forming normal paragraphs, the lines of a code block are interpreted literally. Markdown wraps a code block in both <code><pre></code> and <code><code></code> tags.</p>
|
393
355
|
|
@@ -395,16 +357,14 @@ sit amet, consectetuer adipiscing elit.
|
|
395
357
|
|
396
358
|
<pre><code>This is a normal paragraph:
|
397
359
|
|
398
|
-
This is a code block
|
399
|
-
</code></pre>
|
360
|
+
This is a code block.</code></pre>
|
400
361
|
|
401
362
|
<p>Markdown will generate:</p>
|
402
363
|
|
403
364
|
<pre><code><p>This is a normal paragraph:</p>
|
404
365
|
|
405
366
|
<pre><code>This is a code block.
|
406
|
-
</code></pre>
|
407
|
-
</code></pre>
|
367
|
+
</code></pre></code></pre>
|
408
368
|
|
409
369
|
<p>One level of indentation – 4 spaces or 1 tab – is removed from each line of the code block. For example, this:</p>
|
410
370
|
|
@@ -412,8 +372,7 @@ sit amet, consectetuer adipiscing elit.
|
|
412
372
|
|
413
373
|
tell application "Foo"
|
414
374
|
beep
|
415
|
-
end tell
|
416
|
-
</code></pre>
|
375
|
+
end tell</code></pre>
|
417
376
|
|
418
377
|
<p>will turn into:</p>
|
419
378
|
|
@@ -422,8 +381,7 @@ sit amet, consectetuer adipiscing elit.
|
|
422
381
|
<pre><code>tell application "Foo"
|
423
382
|
beep
|
424
383
|
end tell
|
425
|
-
</code></pre>
|
426
|
-
</code></pre>
|
384
|
+
</code></pre></code></pre>
|
427
385
|
|
428
386
|
<p>A code block continues until it reaches a line that is not indented (or the end of the article).</p>
|
429
387
|
|
@@ -431,16 +389,14 @@ end tell
|
|
431
389
|
|
432
390
|
<pre><code> <div class="footer">
|
433
391
|
&copy; 2004 Foo Corporation
|
434
|
-
</div>
|
435
|
-
</code></pre>
|
392
|
+
</div></code></pre>
|
436
393
|
|
437
394
|
<p>will turn into:</p>
|
438
395
|
|
439
396
|
<pre><code><pre><code>&lt;div class="footer"&gt;
|
440
397
|
&amp;copy; 2004 Foo Corporation
|
441
398
|
&lt;/div&gt;
|
442
|
-
</code></pre>
|
443
|
-
</code></pre>
|
399
|
+
</code></pre></code></pre>
|
444
400
|
|
445
401
|
<p>Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it’s also easy to use Markdown to write about Markdown’s own syntax.</p>
|
446
402
|
<h3 id='hr'>Horizontal Rules</h3>
|
@@ -454,9 +410,7 @@ end tell
|
|
454
410
|
|
455
411
|
- - -
|
456
412
|
|
457
|
-
|
458
|
-
|
459
|
-
</code></pre>
|
413
|
+
---------------------------------------</code></pre>
|
460
414
|
<hr /><h2 id='span'>Span Elements</h2><h3 id='link'>Links</h3>
|
461
415
|
<p>Markdown supports two style of links: <em>inline</em> and <em>reference</em>.</p>
|
462
416
|
|
@@ -466,8 +420,7 @@ end tell
|
|
466
420
|
|
467
421
|
<pre><code>This is [an example](http://example.com/ "Title") inline link.
|
468
422
|
|
469
|
-
[This link](http://example.net/) has no title attribute
|
470
|
-
</code></pre>
|
423
|
+
[This link](http://example.net/) has no title attribute.</code></pre>
|
471
424
|
|
472
425
|
<p>Will produce:</p>
|
473
426
|
|
@@ -475,28 +428,23 @@ end tell
|
|
475
428
|
an example</a> inline link.</p>
|
476
429
|
|
477
430
|
<p><a href="http://example.net/">This link</a> has no
|
478
|
-
title attribute.</p>
|
479
|
-
</code></pre>
|
431
|
+
title attribute.</p></code></pre>
|
480
432
|
|
481
433
|
<p>If you’re referring to a local resource on the same server, you can use relative paths:</p>
|
482
434
|
|
483
|
-
<pre><code>See my [About](/about/) page for details.
|
484
|
-
</code></pre>
|
435
|
+
<pre><code>See my [About](/about/) page for details. </code></pre>
|
485
436
|
|
486
437
|
<p>Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:</p>
|
487
438
|
|
488
|
-
<pre><code>This is [an example][id] reference-style link
|
489
|
-
</code></pre>
|
439
|
+
<pre><code>This is [an example][id] reference-style link.</code></pre>
|
490
440
|
|
491
441
|
<p>You can optionally use a space to separate the sets of brackets:</p>
|
492
442
|
|
493
|
-
<pre><code>This is [an example] [id] reference-style link
|
494
|
-
</code></pre>
|
443
|
+
<pre><code>This is [an example] [id] reference-style link.</code></pre>
|
495
444
|
|
496
445
|
<p>Then, anywhere in the document, you define your link label like this, on a line by itself:</p>
|
497
446
|
|
498
|
-
<pre><code>[id]: http://example.com/ "Optional Title Here"
|
499
|
-
</code></pre>
|
447
|
+
<pre><code>[id]: http://example.com/ "Optional Title Here"</code></pre>
|
500
448
|
|
501
449
|
<p>That is:</p>
|
502
450
|
|
@@ -516,51 +464,43 @@ title attribute.</p>
|
|
516
464
|
|
517
465
|
<pre><code>[foo]: http://example.com/ "Optional Title Here"
|
518
466
|
[foo]: http://example.com/ 'Optional Title Here'
|
519
|
-
[foo]: http://example.com/ (Optional Title Here)
|
520
|
-
</code></pre>
|
467
|
+
[foo]: http://example.com/ (Optional Title Here)</code></pre>
|
521
468
|
|
522
469
|
<p><strong>Note:</strong> There is a known bug in Markdown.pl 1.0.1 which prevents single quotes from being used to delimit link titles.</p>
|
523
470
|
|
524
471
|
<p>The link URL may, optionally, be surrounded by angle brackets:</p>
|
525
472
|
|
526
|
-
<pre><code>[id]: <http://example.com/> "Optional Title Here"
|
527
|
-
</code></pre>
|
473
|
+
<pre><code>[id]: <http://example.com/> "Optional Title Here"</code></pre>
|
528
474
|
|
529
475
|
<p>You can put the title attribute on the next line and use extra spaces or tabs for padding, which tends to look better with longer URLs:</p>
|
530
476
|
|
531
477
|
<pre><code>[id]: http://example.com/longish/path/to/resource/here
|
532
|
-
"Optional Title Here"
|
533
|
-
</code></pre>
|
478
|
+
"Optional Title Here"</code></pre>
|
534
479
|
|
535
480
|
<p>Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output.</p>
|
536
481
|
|
537
482
|
<p>Link definition names may constist of letters, numbers, spaces, and punctuation – but they are <em>not</em> case sensitive. E.g. these two links:</p>
|
538
483
|
|
539
484
|
<pre><code>[link text][a]
|
540
|
-
[link text][A]
|
541
|
-
</code></pre>
|
485
|
+
[link text][A]</code></pre>
|
542
486
|
|
543
487
|
<p>are equivalent.</p>
|
544
488
|
|
545
489
|
<p>The <em>implicit link name</em> shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets – e.g., to link the word “Google” to the google.com web site, you could simply write:</p>
|
546
490
|
|
547
|
-
<pre><code>[Google][]
|
548
|
-
</code></pre>
|
491
|
+
<pre><code>[Google][]</code></pre>
|
549
492
|
|
550
493
|
<p>And then define the link:</p>
|
551
494
|
|
552
|
-
<pre><code>[Google]: http://google.com
|
553
|
-
</code></pre>
|
495
|
+
<pre><code>[Google]: http://google.com/</code></pre>
|
554
496
|
|
555
497
|
<p>Because link names may contain spaces, this shortcut even works for multiple words in the link text:</p>
|
556
498
|
|
557
|
-
<pre><code>Visit [Daring Fireball][] for more information
|
558
|
-
</code></pre>
|
499
|
+
<pre><code>Visit [Daring Fireball][] for more information.</code></pre>
|
559
500
|
|
560
501
|
<p>And then define the link:</p>
|
561
502
|
|
562
|
-
<pre><code>[Daring Fireball]: http://daringfireball.net
|
563
|
-
</code></pre>
|
503
|
+
<pre><code>[Daring Fireball]: http://daringfireball.net/</code></pre>
|
564
504
|
|
565
505
|
<p>Link definitions can be placed anywhere in your Markdown document. I tend to put them immediately after each paragraph in which they’re used, but if you want, you can put them all at the end of your document, sort of like footnotes.</p>
|
566
506
|
|
@@ -571,8 +511,7 @@ title attribute.</p>
|
|
571
511
|
|
572
512
|
[1]: http://google.com/ "Google"
|
573
513
|
[2]: http://search.yahoo.com/ "Yahoo Search"
|
574
|
-
[3]: http://search.msn.com/ "MSN Search"
|
575
|
-
</code></pre>
|
514
|
+
[3]: http://search.msn.com/ "MSN Search"</code></pre>
|
576
515
|
|
577
516
|
<p>Using the implicit link name shortcut, you could instead write:</p>
|
578
517
|
|
@@ -581,23 +520,20 @@ title attribute.</p>
|
|
581
520
|
|
582
521
|
[google]: http://google.com/ "Google"
|
583
522
|
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
|
584
|
-
[msn]: http://search.msn.com/ "MSN Search"
|
585
|
-
</code></pre>
|
523
|
+
[msn]: http://search.msn.com/ "MSN Search"</code></pre>
|
586
524
|
|
587
525
|
<p>Both of the above examples will produce the following HTML output:</p>
|
588
526
|
|
589
527
|
<pre><code><p>I get 10 times more traffic from <a href="http://google.com/"
|
590
528
|
title="Google">Google</a> than from
|
591
529
|
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
|
592
|
-
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
|
593
|
-
</code></pre>
|
530
|
+
or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p></code></pre>
|
594
531
|
|
595
532
|
<p>For comparison, here is the same paragraph written using Markdown’s inline link style:</p>
|
596
533
|
|
597
534
|
<pre><code>I get 10 times more traffic from [Google](http://google.com/ "Google")
|
598
535
|
than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
|
599
|
-
[MSN](http://search.msn.com/ "MSN Search")
|
600
|
-
</code></pre>
|
536
|
+
[MSN](http://search.msn.com/ "MSN Search").</code></pre>
|
601
537
|
|
602
538
|
<p>The point of reference-style links is not that they’re easier to write. The point is that with reference-style links, your document source is vastly more readable. Compare the above examples: using reference-style links, the paragraph itself is only 81 characters long; with inline-style links, it’s 176 characters; and as raw HTML, it’s 234 characters. In the raw HTML, there’s more markup than there is text.</p>
|
603
539
|
|
@@ -611,8 +547,7 @@ _single underscores_
|
|
611
547
|
|
612
548
|
**double asterisks**
|
613
549
|
|
614
|
-
__double underscores__
|
615
|
-
</code></pre>
|
550
|
+
__double underscores__</code></pre>
|
616
551
|
|
617
552
|
<p>will produce:</p>
|
618
553
|
|
@@ -622,81 +557,64 @@ __double underscores__
|
|
622
557
|
|
623
558
|
<strong>double asterisks</strong>
|
624
559
|
|
625
|
-
<strong>double underscores</strong>
|
626
|
-
</code></pre>
|
560
|
+
<strong>double underscores</strong></code></pre>
|
627
561
|
|
628
562
|
<p>You can use whichever style you prefer; the lone restriction is that the same character must be used to open and close an emphasis span.</p>
|
629
563
|
|
630
564
|
<p>Emphasis can be used in the middle of a word:</p>
|
631
565
|
|
632
|
-
<pre><code>un*fucking*believable
|
633
|
-
</code></pre>
|
566
|
+
<pre><code>un*fucking*believable</code></pre>
|
634
567
|
|
635
568
|
<p>But if you surround an <code>*</code> or <code>_</code> with spaces, it’ll be treated as a literal asterisk or underscore.</p>
|
636
569
|
|
637
570
|
<p>To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it:</p>
|
638
571
|
|
639
|
-
<pre><code>\*this text is surrounded by literal asterisks
|
640
|
-
|
641
|
-
|
642
|
-
</code></pre>
|
572
|
+
<pre><code>\*this text is surrounded by literal asterisks\*</code></pre>
|
643
573
|
<h3 id='code'>Code</h3>
|
644
574
|
<p>To indicate a span of code, wrap it with backtick quotes (<code>`</code>). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:</p>
|
645
575
|
|
646
|
-
<pre><code>Use the `printf()` function
|
647
|
-
</code></pre>
|
576
|
+
<pre><code>Use the `printf()` function.</code></pre>
|
648
577
|
|
649
578
|
<p>will produce:</p>
|
650
579
|
|
651
|
-
<pre><code><p>Use the <code>printf()</code> function.</p>
|
652
|
-
</code></pre>
|
580
|
+
<pre><code><p>Use the <code>printf()</code> function.</p></code></pre>
|
653
581
|
|
654
582
|
<p>To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:</p>
|
655
583
|
|
656
|
-
<pre><code>``There is a literal backtick (`) here
|
657
|
-
</code></pre>
|
584
|
+
<pre><code>``There is a literal backtick (`) here.``</code></pre>
|
658
585
|
|
659
586
|
<p>which will produce this:</p>
|
660
587
|
|
661
|
-
<pre><code><p><code>There is a literal backtick (`) here.</code></p>
|
662
|
-
</code></pre>
|
588
|
+
<pre><code><p><code>There is a literal backtick (`) here.</code></p></code></pre>
|
663
589
|
|
664
590
|
<p>The backtick delimiters surrounding a code span may include spaces – one after the opening, one before the closing. This allows you to place literal backtick characters at the beginning or end of a code span:</p>
|
665
591
|
|
666
592
|
<pre><code>A single backtick in a code span: `` ` ``
|
667
593
|
|
668
|
-
A backtick-delimited string in a code span: `` `foo`
|
669
|
-
</code></pre>
|
594
|
+
A backtick-delimited string in a code span: `` `foo` ``</code></pre>
|
670
595
|
|
671
596
|
<p>will produce:</p>
|
672
597
|
|
673
598
|
<pre><code><p>A single backtick in a code span: <code>`</code></p>
|
674
599
|
|
675
|
-
<p>A backtick-delimited string in a code span: <code>`foo`</code></p>
|
676
|
-
</code></pre>
|
600
|
+
<p>A backtick-delimited string in a code span: <code>`foo`</code></p></code></pre>
|
677
601
|
|
678
602
|
<p>With a code span, ampersands and angle brackets are encoded as HTML entities automatically, which makes it easy to include example HTML tags. Markdown will turn this:</p>
|
679
603
|
|
680
|
-
<pre><code>Please don't use any `<blink>` tags
|
681
|
-
</code></pre>
|
604
|
+
<pre><code>Please don't use any `<blink>` tags.</code></pre>
|
682
605
|
|
683
606
|
<p>into:</p>
|
684
607
|
|
685
|
-
<pre><code><p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>
|
686
|
-
</code></pre>
|
608
|
+
<pre><code><p>Please don't use any <code>&lt;blink&gt;</code> tags.</p></code></pre>
|
687
609
|
|
688
610
|
<p>You can write this:</p>
|
689
611
|
|
690
|
-
<pre><code>`&#8212;` is the decimal-encoded equivalent of `&mdash
|
691
|
-
</code></pre>
|
612
|
+
<pre><code>`&#8212;` is the decimal-encoded equivalent of `&mdash;`.</code></pre>
|
692
613
|
|
693
614
|
<p>to produce:</p>
|
694
615
|
|
695
616
|
<pre><code><p><code>&amp;#8212;</code> is the decimal-encoded
|
696
|
-
equivalent of <code>&amp;mdash;</code>.</p>
|
697
|
-
|
698
|
-
|
699
|
-
</code></pre>
|
617
|
+
equivalent of <code>&amp;mdash;</code>.</p></code></pre>
|
700
618
|
<h3 id='img'>Images</h3>
|
701
619
|
<p>Admittedly, it’s fairly difficult to devise a “natural” syntax for placing images into a plain text document format.</p>
|
702
620
|
|
@@ -706,8 +624,7 @@ equivalent of <code>&amp;mdash;</code>.</p>
|
|
706
624
|
|
707
625
|
<pre><code>![Alt text](/path/to/img.jpg)
|
708
626
|
|
709
|
-
![Alt text](/path/to/img.jpg "Optional title")
|
710
|
-
</code></pre>
|
627
|
+
![Alt text](/path/to/img.jpg "Optional title")</code></pre>
|
711
628
|
|
712
629
|
<p>That is:</p>
|
713
630
|
|
@@ -721,13 +638,11 @@ equivalent of <code>&amp;mdash;</code>.</p>
|
|
721
638
|
|
722
639
|
<p>Reference-style image syntax looks like this:</p>
|
723
640
|
|
724
|
-
<pre><code>![Alt text][id]
|
725
|
-
</code></pre>
|
641
|
+
<pre><code>![Alt text][id]</code></pre>
|
726
642
|
|
727
643
|
<p>Where “id” is the name of a defined image reference. Image references are defined using syntax identical to link references:</p>
|
728
644
|
|
729
|
-
<pre><code>[id]: url/to/image "Optional title attribute"
|
730
|
-
</code></pre>
|
645
|
+
<pre><code>[id]: url/to/image "Optional title attribute"</code></pre>
|
731
646
|
|
732
647
|
<p>As of this writing, Markdown has no syntax for specifying the dimensions of an image; if this is important to you, you can simply use regular HTML <code><img></code> tags.</p>
|
733
648
|
<hr /><h2 id='misc'>Miscellaneous</h2><h3 id='autolink'>Automatic Links</h3>
|
@@ -737,21 +652,18 @@ equivalent of <code>&amp;mdash;</code>.</p>
|
|
737
652
|
|
738
653
|
<p>Markdown will turn this into:</p>
|
739
654
|
|
740
|
-
<pre><code><a href="http://example.com/">http://example.com/</a>
|
741
|
-
</code></pre>
|
655
|
+
<pre><code><a href="http://example.com/">http://example.com/</a></code></pre>
|
742
656
|
|
743
657
|
<p>Automatic links for email addresses work similarly, except that Markdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots. For example, Markdown will turn this:</p>
|
744
658
|
|
745
|
-
<pre><code><address@example.com>
|
746
|
-
</code></pre>
|
659
|
+
<pre><code><address@example.com></code></pre>
|
747
660
|
|
748
661
|
<p>into something like this:</p>
|
749
662
|
|
750
663
|
<pre><code><a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
|
751
664
|
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
|
752
665
|
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
|
753
|
-
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
|
754
|
-
</code></pre>
|
666
|
+
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a></code></pre>
|
755
667
|
|
756
668
|
<p>which will render in a browser as a clickable link to “address@example.com”.</p>
|
757
669
|
|
@@ -759,8 +671,7 @@ equivalent of <code>&amp;mdash;</code>.</p>
|
|
759
671
|
<h3 id='backslash'>Backslash Escapes</h3>
|
760
672
|
<p>Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax. For example, if you wanted to surround a word with literal asterisks (instead of an HTML <code><em></code> tag), you can backslashes before the asterisks, like this:</p>
|
761
673
|
|
762
|
-
<pre><code>\*literal asterisks
|
763
|
-
</code></pre>
|
674
|
+
<pre><code>\*literal asterisks\*</code></pre>
|
764
675
|
|
765
676
|
<p>Markdown provides backslash escapes for the following characters:</p>
|
766
677
|
|
@@ -776,4 +687,4 @@ _ underscore
|
|
776
687
|
- minus sign (hyphen)
|
777
688
|
. dot
|
778
689
|
! exclamation mark</code></pre>
|
779
|
-
<div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown-superset interpreter for Ruby'>Maruku</a> at
|
690
|
+
<div class='maruku_signature'><hr /><span style='font-size: small; font-style: italic'>Created by <a href='http://maruku.rubyforge.org' title='Maruku: a Markdown-superset interpreter for Ruby'>Maruku</a> at 13:32 on Sunday, February 18th, 2007.</span></div></body></html>
|