ronn-ng 0.7.4 → 0.8.0.SNAPSHOT
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGES +12 -3
- data/Gemfile +2 -0
- data/INSTALLING.md +100 -0
- data/README.md +19 -1
- data/Rakefile +39 -49
- data/bin/ronn +93 -75
- data/completion/bash/ronn +32 -0
- data/completion/zsh/_ronn +24 -0
- data/config.ru +3 -3
- data/lib/ronn/document.rb +127 -106
- data/lib/ronn/index.rb +8 -9
- data/lib/ronn/roff.rb +153 -76
- data/lib/ronn/server.rb +19 -22
- data/lib/ronn/template.rb +27 -26
- data/lib/ronn/utils.rb +9 -7
- data/lib/ronn.rb +5 -3
- data/man/ronn-format.7 +6 -62
- data/man/ronn.1 +21 -123
- data/man/ronn.1.ronn +8 -0
- data/ronn-ng.gemspec +38 -13
- data/test/angle_bracket_syntax.html +4 -5
- data/test/backticks.html +14 -0
- data/test/backticks.ronn +10 -0
- data/test/basic_document.html +3 -4
- data/test/basic_document.ronn +2 -2
- data/test/circumflexes.ronn +1 -0
- data/test/code_blocks.7.ronn +41 -0
- data/test/contest.rb +56 -54
- data/test/custom_title_document.html +2 -2
- data/test/definition_list_syntax.html +13 -9
- data/test/definition_list_syntax.roff +2 -9
- data/test/definition_list_syntax.ronn +2 -2
- data/test/dots_at_line_start_test.roff +12 -3
- data/test/dots_at_line_start_test.ronn +8 -0
- data/test/ellipses.roff +7 -0
- data/test/ellipses.ronn +7 -0
- data/test/entity_encoding_test.html +13 -14
- data/test/entity_encoding_test.roff +1 -22
- data/test/entity_encoding_test.ronn +1 -1
- data/test/markdown_syntax.html +4 -5
- data/test/markdown_syntax.roff +1 -561
- data/test/middle_paragraph.html +2 -3
- data/test/middle_paragraph.roff +1 -5
- data/test/middle_paragraph.ronn +1 -1
- data/test/missing_spaces.roff +0 -2
- data/test/nested_list.ronn +19 -0
- data/test/nested_list_with_code.html +15 -0
- data/test/nested_list_with_code.roff +11 -0
- data/test/nested_list_with_code.ronn +6 -0
- data/test/page.with.periods.in.name.5.ronn +4 -0
- data/test/pre_block_with_quotes.roff +0 -5
- data/test/section_reference_links.html +2 -3
- data/test/section_reference_links.roff +1 -4
- data/test/section_reference_links.ronn +1 -1
- data/test/tables.ronn +24 -0
- data/test/test_ronn.rb +49 -35
- data/test/test_ronn_document.rb +81 -81
- data/test/test_ronn_index.rb +11 -11
- data/test/titleless_document.html +0 -1
- data/test/underline_spacing_test.roff +0 -8
- metadata +140 -22
- data/INSTALLING +0 -20
data/test/markdown_syntax.roff
CHANGED
@@ -1,12 +1,8 @@
|
|
1
1
|
.TH "MARKDOWN" "5" "January 1979" "" ""
|
2
|
-
.
|
3
2
|
.SH "NAME"
|
4
3
|
\fBmarkdown\fR \- humane markup syntax
|
5
|
-
.
|
6
4
|
.SH "SYNOPSIS"
|
7
|
-
.
|
8
5
|
.nf
|
9
|
-
|
10
6
|
# Header 1 #
|
11
7
|
## Header 2 ##
|
12
8
|
### Header 3 ### (Hashes on right are optional)
|
@@ -36,39 +32,26 @@ Inline markup like _italics_, **bold**, and `code()`\.
|
|
36
32
|
* nest them
|
37
33
|
\- Another one
|
38
34
|
+ Another one
|
39
|
-
.
|
40
35
|
.fi
|
41
|
-
.
|
42
36
|
.SH "DESCRIPTION"
|
43
|
-
.
|
44
37
|
.SS "Philosophy"
|
45
38
|
Markdown is intended to be as easy\-to\-read and easy\-to\-write as is feasible\.
|
46
|
-
.
|
47
39
|
.P
|
48
40
|
Readability, however, is emphasized above all else\. A Markdown\-formatted document should be publishable as\-is, as plain text, without looking like it\'s been marked up with tags or formatting instructions\. While Markdown\'s syntax has been influenced by several existing text\-to\-HTML filters \-\- including Setext \fIhttp://docutils\.sourceforge\.net/mirror/setext\.html\fR, atx \fIhttp://www\.aaronsw\.com/2002/atx/\fR, Textile \fIhttp://textism\.com/tools/textile/\fR, reStructuredText \fIhttp://docutils\.sourceforge\.net/rst\.html\fR, Grutatext \fIhttp://www\.triptico\.com/software/grutatxt\.html\fR, and EtText \fIhttp://ettext\.taint\.org/doc/\fR \-\- the single biggest source of inspiration for Markdown\'s syntax is the format of plain text email\.
|
49
|
-
.
|
50
41
|
.P
|
51
42
|
To this end, Markdown\'s syntax is comprised entirely of punctuation characters, which punctuation characters have been carefully chosen so as to look like what they mean\. E\.g\., asterisks around a word actually look like *emphasis*\. Markdown lists look like, well, lists\. Even blockquotes look like quoted passages of text, assuming you\'ve ever used email\.
|
52
|
-
.
|
53
43
|
.SS "Inline HTML"
|
54
44
|
Markdown\'s syntax is intended for one purpose: to be used as a format for \fIwriting\fR for the web\.
|
55
|
-
.
|
56
45
|
.P
|
57
46
|
Markdown is not a replacement for HTML, or even close to it\. Its syntax is very small, corresponding only to a very small subset of HTML tags\. The idea is \fInot\fR to create a syntax that makes it easier to insert HTML tags\. In my opinion, HTML tags are already easy to insert\. The idea for Markdown is to make it easy to read, write, and edit prose\. HTML is a \fIpublishing\fR format; Markdown is a \fIwriting\fR format\. Thus, Markdown\'s formatting syntax only addresses issues that can be conveyed in plain text\.
|
58
|
-
.
|
59
47
|
.P
|
60
48
|
For any markup that is not covered by Markdown\'s syntax, you simply use HTML itself\. There\'s no need to preface it or delimit it to indicate that you\'re switching from Markdown to HTML; you just use the tags\.
|
61
|
-
.
|
62
49
|
.P
|
63
50
|
The only restrictions are that block\-level HTML elements \-\- e\.g\. \fB<div>\fR, \fB<table>\fR, \fB<pre>\fR, \fB<p>\fR, etc\. \-\- must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces\. Markdown is smart enough not to add extra (unwanted) \fB<p>\fR tags around HTML block\-level tags\.
|
64
|
-
.
|
65
51
|
.P
|
66
52
|
For example, to add an HTML table to a Markdown article:
|
67
|
-
.
|
68
53
|
.IP "" 4
|
69
|
-
.
|
70
54
|
.nf
|
71
|
-
|
72
55
|
This is a regular paragraph\.
|
73
56
|
|
74
57
|
<table>
|
@@ -78,254 +61,156 @@ This is a regular paragraph\.
|
|
78
61
|
</table>
|
79
62
|
|
80
63
|
This is another regular paragraph\.
|
81
|
-
.
|
82
64
|
.fi
|
83
|
-
.
|
84
65
|
.IP "" 0
|
85
|
-
.
|
86
66
|
.P
|
87
67
|
Note that Markdown formatting syntax is not processed within block\-level HTML tags\. E\.g\., you can\'t use Markdown\-style \fB*emphasis*\fR inside an HTML block\.
|
88
|
-
.
|
89
68
|
.P
|
90
69
|
Span\-level HTML tags \-\- e\.g\. \fB<span>\fR, \fB<cite>\fR, or \fB<del>\fR \-\- can be used anywhere in a Markdown paragraph, list item, or header\. If you want, you can even use HTML tags instead of Markdown formatting; e\.g\. if you\'d prefer to use HTML \fB<a>\fR or \fB<img>\fR tags instead of Markdown\'s link or image syntax, go right ahead\.
|
91
|
-
.
|
92
70
|
.P
|
93
71
|
Unlike block\-level HTML tags, Markdown syntax \fIis\fR processed within span\-level tags\.
|
94
|
-
.
|
95
72
|
.SS "Automatic Escaping for Special Characters"
|
96
73
|
In HTML, there are two characters that demand special treatment: \fB<\fR and \fB&\fR\. Left angle brackets are used to start tags; ampersands are used to denote HTML entities\. If you want to use them as literal characters, you must escape them as entities, e\.g\. \fB<\fR, and \fB&\fR\.
|
97
|
-
.
|
98
74
|
.P
|
99
75
|
Ampersands in particular are bedeviling for web writers\. If you want to write about \'AT&T\', you need to write \'\fBAT&T\fR\'\. You even need to escape ampersands within URLs\. Thus, if you want to link to:
|
100
|
-
.
|
101
76
|
.IP "" 4
|
102
|
-
.
|
103
77
|
.nf
|
104
|
-
|
105
78
|
http://images\.google\.com/images?num=30&q=larry+bird
|
106
|
-
.
|
107
79
|
.fi
|
108
|
-
.
|
109
80
|
.IP "" 0
|
110
|
-
.
|
111
81
|
.P
|
112
82
|
you need to encode the URL as:
|
113
|
-
.
|
114
83
|
.IP "" 4
|
115
|
-
.
|
116
84
|
.nf
|
117
|
-
|
118
85
|
http://images\.google\.com/images?num=30&q=larry+bird
|
119
|
-
.
|
120
86
|
.fi
|
121
|
-
.
|
122
87
|
.IP "" 0
|
123
|
-
.
|
124
88
|
.P
|
125
89
|
in your anchor tag \fBhref\fR 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\.
|
126
|
-
.
|
127
90
|
.P
|
128
91
|
Markdown allows you to use these characters naturally, taking care of all the necessary escaping for you\. If you use an ampersand as part of an HTML entity, it remains unchanged; otherwise it will be translated into \fB&\fR\.
|
129
|
-
.
|
130
92
|
.P
|
131
93
|
So, if you want to include a copyright symbol in your article, you can write:
|
132
|
-
.
|
133
94
|
.IP "" 4
|
134
|
-
.
|
135
95
|
.nf
|
136
|
-
|
137
96
|
©
|
138
|
-
.
|
139
97
|
.fi
|
140
|
-
.
|
141
98
|
.IP "" 0
|
142
|
-
.
|
143
99
|
.P
|
144
100
|
and Markdown will leave it alone\. But if you write:
|
145
|
-
.
|
146
101
|
.IP "" 4
|
147
|
-
.
|
148
102
|
.nf
|
149
|
-
|
150
103
|
AT&T
|
151
|
-
.
|
152
104
|
.fi
|
153
|
-
.
|
154
105
|
.IP "" 0
|
155
|
-
.
|
156
106
|
.P
|
157
107
|
Markdown will translate it to:
|
158
|
-
.
|
159
108
|
.IP "" 4
|
160
|
-
.
|
161
109
|
.nf
|
162
|
-
|
163
110
|
AT&T
|
164
|
-
.
|
165
111
|
.fi
|
166
|
-
.
|
167
112
|
.IP "" 0
|
168
|
-
.
|
169
113
|
.P
|
170
114
|
Similarly, because Markdown supports \fIinline HTML\fR, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such\. But if you write:
|
171
|
-
.
|
172
115
|
.IP "" 4
|
173
|
-
.
|
174
116
|
.nf
|
175
|
-
|
176
117
|
4 < 5
|
177
|
-
.
|
178
118
|
.fi
|
179
|
-
.
|
180
119
|
.IP "" 0
|
181
|
-
.
|
182
120
|
.P
|
183
121
|
Markdown will translate it to:
|
184
|
-
.
|
185
122
|
.IP "" 4
|
186
|
-
.
|
187
123
|
.nf
|
188
|
-
|
189
124
|
4 < 5
|
190
|
-
.
|
191
125
|
.fi
|
192
|
-
.
|
193
126
|
.IP "" 0
|
194
|
-
.
|
195
127
|
.P
|
196
128
|
However, inside Markdown code spans and blocks, angle brackets and ampersands are \fIalways\fR 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 \fB<\fR and \fB&\fR in your example code needs to be escaped\.)
|
197
|
-
.
|
198
129
|
.SH "BLOCK ELEMENTS"
|
199
|
-
.
|
200
130
|
.SS "Paragraphs and Line Breaks"
|
201
131
|
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines\. (A blank line is any line that looks like a blank line \-\- a line containing nothing but spaces or tabs is considered blank\.) Normal paragraphs should not be indented with spaces or tabs\.
|
202
|
-
.
|
203
132
|
.P
|
204
133
|
The implication of the "one or more consecutive lines of text" rule is that Markdown supports "hard\-wrapped" text paragraphs\. This differs significantly from most other text\-to\-HTML formatters (including Movable Type\'s "Convert Line Breaks" option) which translate every line break character in a paragraph into a \fB<br />\fR tag\.
|
205
|
-
.
|
206
134
|
.P
|
207
135
|
When you \fIdo\fR want to insert a \fB<br />\fR break tag using Markdown, you end a line with two or more spaces, then type return\.
|
208
|
-
.
|
209
136
|
.P
|
210
137
|
Yes, this takes a tad more effort to create a \fB<br />\fR, but a simplistic "every line break is a \fB<br />\fR" rule wouldn\'t work for Markdown\. Markdown\'s email\-style \fIblockquoting\fR and multi\-paragraph \fIlist items\fR work best \-\- and look better \-\- when you format them with hard breaks\.
|
211
|
-
.
|
212
138
|
.SS "Headers"
|
213
139
|
Markdown supports two styles of headers, Setext \fIhttp://docutils\.sourceforge\.net/mirror/setext\.html\fR and atx \fIhttp://www\.aaronsw\.com/2002/atx/\fR\.
|
214
|
-
.
|
215
140
|
.P
|
216
141
|
Setext\-style headers are "underlined" using equal signs (for first\-level headers) and dashes (for second\-level headers)\. For example:
|
217
|
-
.
|
218
142
|
.IP "" 4
|
219
|
-
.
|
220
143
|
.nf
|
221
|
-
|
222
144
|
This is an H1
|
223
145
|
=============
|
224
146
|
|
225
147
|
This is an H2
|
226
148
|
\-\-\-\-\-\-\-\-\-\-\-\-\-
|
227
|
-
.
|
228
149
|
.fi
|
229
|
-
.
|
230
150
|
.IP "" 0
|
231
|
-
.
|
232
151
|
.P
|
233
152
|
Any number of underlining \fB=\fR\'s or \fB\-\fR\'s will work\.
|
234
|
-
.
|
235
153
|
.P
|
236
154
|
Atx\-style headers use 1\-6 hash characters at the start of the line, corresponding to header levels 1\-6\. For example:
|
237
|
-
.
|
238
155
|
.IP "" 4
|
239
|
-
.
|
240
156
|
.nf
|
241
|
-
|
242
157
|
# This is an H1
|
243
158
|
|
244
159
|
## This is an H2
|
245
160
|
|
246
161
|
###### This is an H6
|
247
|
-
.
|
248
162
|
.fi
|
249
|
-
.
|
250
163
|
.IP "" 0
|
251
|
-
.
|
252
164
|
.P
|
253
165
|
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\.) :
|
254
|
-
.
|
255
166
|
.IP "" 4
|
256
|
-
.
|
257
167
|
.nf
|
258
|
-
|
259
168
|
# This is an H1 #
|
260
169
|
|
261
170
|
## This is an H2 ##
|
262
171
|
|
263
172
|
### This is an H3 ######
|
264
|
-
.
|
265
173
|
.fi
|
266
|
-
.
|
267
174
|
.IP "" 0
|
268
|
-
.
|
269
175
|
.SS "Blockquotes"
|
270
176
|
Markdown uses email\-style \fB>\fR 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 \fB>\fR before every line:
|
271
|
-
.
|
272
177
|
.IP "" 4
|
273
|
-
.
|
274
178
|
.nf
|
275
|
-
|
276
179
|
> This is a blockquote with two paragraphs\. Lorem ipsum dolor sit amet,
|
277
180
|
> consectetuer adipiscing elit\. Aliquam hendrerit mi posuere lectus\.
|
278
181
|
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus\.
|
279
182
|
>
|
280
183
|
> Donec sit amet nisl\. Aliquam semper ipsum sit amet velit\. Suspendisse
|
281
184
|
> id sem consectetuer libero luctus adipiscing\.
|
282
|
-
.
|
283
185
|
.fi
|
284
|
-
.
|
285
186
|
.IP "" 0
|
286
|
-
.
|
287
187
|
.P
|
288
188
|
Markdown allows you to be lazy and only put the \fB>\fR before the first line of a hard\-wrapped paragraph:
|
289
|
-
.
|
290
189
|
.IP "" 4
|
291
|
-
.
|
292
190
|
.nf
|
293
|
-
|
294
191
|
> This is a blockquote with two paragraphs\. Lorem ipsum dolor sit amet,
|
295
192
|
consectetuer adipiscing elit\. Aliquam hendrerit mi posuere lectus\.
|
296
193
|
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus\.
|
297
194
|
|
298
195
|
> Donec sit amet nisl\. Aliquam semper ipsum sit amet velit\. Suspendisse
|
299
196
|
id sem consectetuer libero luctus adipiscing\.
|
300
|
-
.
|
301
197
|
.fi
|
302
|
-
.
|
303
198
|
.IP "" 0
|
304
|
-
.
|
305
199
|
.P
|
306
200
|
Blockquotes can be nested (i\.e\. a blockquote\-in\-a\-blockquote) by adding additional levels of \fB>\fR:
|
307
|
-
.
|
308
201
|
.IP "" 4
|
309
|
-
.
|
310
202
|
.nf
|
311
|
-
|
312
203
|
> This is the first level of quoting\.
|
313
204
|
>
|
314
205
|
> > This is nested blockquote\.
|
315
206
|
>
|
316
207
|
> Back to the first level\.
|
317
|
-
.
|
318
208
|
.fi
|
319
|
-
.
|
320
209
|
.IP "" 0
|
321
|
-
.
|
322
210
|
.P
|
323
211
|
Blockquotes can contain other Markdown elements, including headers, lists, and code blocks:
|
324
|
-
.
|
325
212
|
.IP "" 4
|
326
|
-
.
|
327
213
|
.nf
|
328
|
-
|
329
214
|
> ## This is a header\.
|
330
215
|
>
|
331
216
|
> 1\. This is the first list item\.
|
@@ -334,235 +219,146 @@ Blockquotes can contain other Markdown elements, including headers, lists, and c
|
|
334
219
|
> Here\'s some example code:
|
335
220
|
>
|
336
221
|
> return shell_exec("echo $input | $markdown_script");
|
337
|
-
.
|
338
222
|
.fi
|
339
|
-
.
|
340
223
|
.IP "" 0
|
341
|
-
.
|
342
224
|
.P
|
343
225
|
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\.
|
344
|
-
.
|
345
226
|
.SS "Lists"
|
346
227
|
Markdown supports ordered (numbered) and unordered (bulleted) lists\.
|
347
|
-
.
|
348
228
|
.P
|
349
229
|
Unordered lists use asterisks, pluses, and hyphens \-\- interchangably \-\- as list markers:
|
350
|
-
.
|
351
230
|
.IP "" 4
|
352
|
-
.
|
353
231
|
.nf
|
354
|
-
|
355
232
|
* Red
|
356
233
|
* Green
|
357
234
|
* Blue
|
358
|
-
.
|
359
235
|
.fi
|
360
|
-
.
|
361
236
|
.IP "" 0
|
362
|
-
.
|
363
237
|
.P
|
364
238
|
is equivalent to:
|
365
|
-
.
|
366
239
|
.IP "" 4
|
367
|
-
.
|
368
240
|
.nf
|
369
|
-
|
370
241
|
+ Red
|
371
242
|
+ Green
|
372
243
|
+ Blue
|
373
|
-
.
|
374
244
|
.fi
|
375
|
-
.
|
376
245
|
.IP "" 0
|
377
|
-
.
|
378
246
|
.P
|
379
247
|
and:
|
380
|
-
.
|
381
248
|
.IP "" 4
|
382
|
-
.
|
383
249
|
.nf
|
384
|
-
|
385
250
|
\- Red
|
386
251
|
\- Green
|
387
252
|
\- Blue
|
388
|
-
.
|
389
253
|
.fi
|
390
|
-
.
|
391
254
|
.IP "" 0
|
392
|
-
.
|
393
255
|
.P
|
394
256
|
Ordered lists use numbers followed by periods:
|
395
|
-
.
|
396
257
|
.IP "" 4
|
397
|
-
.
|
398
258
|
.nf
|
399
|
-
|
400
259
|
1\. Bird
|
401
260
|
2\. McHale
|
402
261
|
3\. Parish
|
403
|
-
.
|
404
262
|
.fi
|
405
|
-
.
|
406
263
|
.IP "" 0
|
407
|
-
.
|
408
264
|
.P
|
409
265
|
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:
|
410
|
-
.
|
411
266
|
.IP "" 4
|
412
|
-
.
|
413
267
|
.nf
|
414
|
-
|
415
268
|
<ol>
|
416
269
|
<li>Bird</li>
|
417
270
|
<li>McHale</li>
|
418
271
|
<li>Parish</li>
|
419
272
|
</ol>
|
420
|
-
.
|
421
273
|
.fi
|
422
|
-
.
|
423
274
|
.IP "" 0
|
424
|
-
.
|
425
275
|
.P
|
426
276
|
If you instead wrote the list in Markdown like this:
|
427
|
-
.
|
428
277
|
.IP "" 4
|
429
|
-
.
|
430
278
|
.nf
|
431
|
-
|
432
279
|
1\. Bird
|
433
280
|
1\. McHale
|
434
281
|
1\. Parish
|
435
|
-
.
|
436
282
|
.fi
|
437
|
-
.
|
438
283
|
.IP "" 0
|
439
|
-
.
|
440
284
|
.P
|
441
285
|
or even:
|
442
|
-
.
|
443
286
|
.IP "" 4
|
444
|
-
.
|
445
287
|
.nf
|
446
|
-
|
447
288
|
3\. Bird
|
448
289
|
1\. McHale
|
449
290
|
8\. Parish
|
450
|
-
.
|
451
291
|
.fi
|
452
|
-
.
|
453
292
|
.IP "" 0
|
454
|
-
.
|
455
293
|
.P
|
456
294
|
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\.
|
457
|
-
.
|
458
295
|
.P
|
459
296
|
If you do use lazy list numbering, however, you should still start the list with the number 1\. At some point in the future, Markdown may support starting ordered lists at an arbitrary number\.
|
460
|
-
.
|
461
297
|
.P
|
462
298
|
List markers typically start at the left margin, but may be indented by up to three spaces\. List markers must be followed by one or more spaces or a tab\.
|
463
|
-
.
|
464
299
|
.P
|
465
300
|
To make lists look nice, you can wrap items with hanging indents:
|
466
|
-
.
|
467
301
|
.IP "" 4
|
468
|
-
.
|
469
302
|
.nf
|
470
|
-
|
471
303
|
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit\.
|
472
304
|
Aliquam hendrerit mi posuere lectus\. Vestibulum enim wisi,
|
473
305
|
viverra nec, fringilla in, laoreet vitae, risus\.
|
474
306
|
* Donec sit amet nisl\. Aliquam semper ipsum sit amet velit\.
|
475
307
|
Suspendisse id sem consectetuer libero luctus adipiscing\.
|
476
|
-
.
|
477
308
|
.fi
|
478
|
-
.
|
479
309
|
.IP "" 0
|
480
|
-
.
|
481
310
|
.P
|
482
311
|
But if you want to be lazy, you don\'t have to:
|
483
|
-
.
|
484
312
|
.IP "" 4
|
485
|
-
.
|
486
313
|
.nf
|
487
|
-
|
488
314
|
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit\.
|
489
315
|
Aliquam hendrerit mi posuere lectus\. Vestibulum enim wisi,
|
490
316
|
viverra nec, fringilla in, laoreet vitae, risus\.
|
491
317
|
* Donec sit amet nisl\. Aliquam semper ipsum sit amet velit\.
|
492
318
|
Suspendisse id sem consectetuer libero luctus adipiscing\.
|
493
|
-
.
|
494
319
|
.fi
|
495
|
-
.
|
496
320
|
.IP "" 0
|
497
|
-
.
|
498
321
|
.P
|
499
322
|
If list items are separated by blank lines, Markdown will wrap the items in \fB<p>\fR tags in the HTML output\. For example, this input:
|
500
|
-
.
|
501
323
|
.IP "" 4
|
502
|
-
.
|
503
324
|
.nf
|
504
|
-
|
505
325
|
* Bird
|
506
326
|
* Magic
|
507
|
-
.
|
508
327
|
.fi
|
509
|
-
.
|
510
328
|
.IP "" 0
|
511
|
-
.
|
512
329
|
.P
|
513
330
|
will turn into:
|
514
|
-
.
|
515
331
|
.IP "" 4
|
516
|
-
.
|
517
332
|
.nf
|
518
|
-
|
519
333
|
<ul>
|
520
334
|
<li>Bird</li>
|
521
335
|
<li>Magic</li>
|
522
336
|
</ul>
|
523
|
-
.
|
524
337
|
.fi
|
525
|
-
.
|
526
338
|
.IP "" 0
|
527
|
-
.
|
528
339
|
.P
|
529
340
|
But this:
|
530
|
-
.
|
531
341
|
.IP "" 4
|
532
|
-
.
|
533
342
|
.nf
|
534
|
-
|
535
343
|
* Bird
|
536
344
|
|
537
345
|
* Magic
|
538
|
-
.
|
539
346
|
.fi
|
540
|
-
.
|
541
347
|
.IP "" 0
|
542
|
-
.
|
543
348
|
.P
|
544
349
|
will turn into:
|
545
|
-
.
|
546
350
|
.IP "" 4
|
547
|
-
.
|
548
351
|
.nf
|
549
|
-
|
550
352
|
<ul>
|
551
353
|
<li><p>Bird</p></li>
|
552
354
|
<li><p>Magic</p></li>
|
553
355
|
</ul>
|
554
|
-
.
|
555
356
|
.fi
|
556
|
-
.
|
557
357
|
.IP "" 0
|
558
|
-
.
|
559
358
|
.P
|
560
359
|
List items may consist of multiple paragraphs\. Each subsequent paragraph in a list item must be indented by either 4 spaces or one tab:
|
561
|
-
.
|
562
360
|
.IP "" 4
|
563
|
-
.
|
564
361
|
.nf
|
565
|
-
|
566
362
|
1\. This is a list item with two paragraphs\. Lorem ipsum dolor
|
567
363
|
sit amet, consectetuer adipiscing elit\. Aliquam hendrerit
|
568
364
|
mi posuere lectus\.
|
@@ -572,18 +368,12 @@ List items may consist of multiple paragraphs\. Each subsequent paragraph in a l
|
|
572
368
|
sit amet velit\.
|
573
369
|
|
574
370
|
2\. Suspendisse id sem consectetuer libero luctus adipiscing\.
|
575
|
-
.
|
576
371
|
.fi
|
577
|
-
.
|
578
372
|
.IP "" 0
|
579
|
-
.
|
580
373
|
.P
|
581
374
|
It looks nice if you indent every line of the subsequent paragraphs, but here again, Markdown will allow you to be lazy:
|
582
|
-
.
|
583
375
|
.IP "" 4
|
584
|
-
.
|
585
376
|
.nf
|
586
|
-
|
587
377
|
* This is a list item with two paragraphs\.
|
588
378
|
|
589
379
|
This is the second paragraph in the list item\. You\'re
|
@@ -591,181 +381,112 @@ only required to indent the first line\. Lorem ipsum dolor
|
|
591
381
|
sit amet, consectetuer adipiscing elit\.
|
592
382
|
|
593
383
|
* Another item in the same list\.
|
594
|
-
.
|
595
384
|
.fi
|
596
|
-
.
|
597
385
|
.IP "" 0
|
598
|
-
.
|
599
386
|
.P
|
600
387
|
To put a blockquote within a list item, the blockquote\'s \fB>\fR delimiters need to be indented:
|
601
|
-
.
|
602
388
|
.IP "" 4
|
603
|
-
.
|
604
389
|
.nf
|
605
|
-
|
606
390
|
* A list item with a blockquote:
|
607
391
|
|
608
392
|
> This is a blockquote
|
609
393
|
> inside a list item\.
|
610
|
-
.
|
611
394
|
.fi
|
612
|
-
.
|
613
395
|
.IP "" 0
|
614
|
-
.
|
615
396
|
.P
|
616
397
|
To put a code block within a list item, the code block needs to be indented \fItwice\fR \-\- 8 spaces or two tabs:
|
617
|
-
.
|
618
398
|
.IP "" 4
|
619
|
-
.
|
620
399
|
.nf
|
621
|
-
|
622
400
|
* A list item with a code block:
|
623
401
|
|
624
402
|
<code goes here>
|
625
|
-
.
|
626
403
|
.fi
|
627
|
-
.
|
628
404
|
.IP "" 0
|
629
|
-
.
|
630
405
|
.P
|
631
406
|
It\'s worth noting that it\'s possible to trigger an ordered list by accident, by writing something like this:
|
632
|
-
.
|
633
407
|
.IP "" 4
|
634
|
-
.
|
635
408
|
.nf
|
636
|
-
|
637
409
|
1986\. What a great season\.
|
638
|
-
.
|
639
410
|
.fi
|
640
|
-
.
|
641
411
|
.IP "" 0
|
642
|
-
.
|
643
412
|
.P
|
644
413
|
In other words, a \fInumber\-period\-space\fR sequence at the beginning of a line\. To avoid this, you can backslash\-escape the period:
|
645
|
-
.
|
646
414
|
.IP "" 4
|
647
|
-
.
|
648
415
|
.nf
|
649
|
-
|
650
416
|
1986\e\. What a great season\.
|
651
|
-
.
|
652
417
|
.fi
|
653
|
-
.
|
654
418
|
.IP "" 0
|
655
|
-
.
|
656
419
|
.SS "Code Blocks"
|
657
420
|
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 \fB<pre>\fR and \fB<code>\fR tags\.
|
658
|
-
.
|
659
421
|
.P
|
660
422
|
To produce a code block in Markdown, simply indent every line of the block by at least 4 spaces or 1 tab\. For example, given this input:
|
661
|
-
.
|
662
423
|
.IP "" 4
|
663
|
-
.
|
664
424
|
.nf
|
665
|
-
|
666
425
|
This is a normal paragraph:
|
667
426
|
|
668
427
|
This is a code block\.
|
669
|
-
.
|
670
428
|
.fi
|
671
|
-
.
|
672
429
|
.IP "" 0
|
673
|
-
.
|
674
430
|
.P
|
675
431
|
Markdown will generate:
|
676
|
-
.
|
677
432
|
.IP "" 4
|
678
|
-
.
|
679
433
|
.nf
|
680
|
-
|
681
434
|
<p>This is a normal paragraph:</p>
|
682
435
|
|
683
436
|
<pre><code>This is a code block\.
|
684
437
|
</code></pre>
|
685
|
-
.
|
686
438
|
.fi
|
687
|
-
.
|
688
439
|
.IP "" 0
|
689
|
-
.
|
690
440
|
.P
|
691
441
|
One level of indentation \-\- 4 spaces or 1 tab \-\- is removed from each line of the code block\. For example, this:
|
692
|
-
.
|
693
442
|
.IP "" 4
|
694
|
-
.
|
695
443
|
.nf
|
696
|
-
|
697
444
|
Here is an example of AppleScript:
|
698
445
|
|
699
446
|
tell application "Foo"
|
700
447
|
beep
|
701
448
|
end tell
|
702
|
-
.
|
703
449
|
.fi
|
704
|
-
.
|
705
450
|
.IP "" 0
|
706
|
-
.
|
707
451
|
.P
|
708
452
|
will turn into:
|
709
|
-
.
|
710
453
|
.IP "" 4
|
711
|
-
.
|
712
454
|
.nf
|
713
|
-
|
714
455
|
<p>Here is an example of AppleScript:</p>
|
715
456
|
|
716
457
|
<pre><code>tell application "Foo"
|
717
458
|
beep
|
718
459
|
end tell
|
719
460
|
</code></pre>
|
720
|
-
.
|
721
461
|
.fi
|
722
|
-
.
|
723
462
|
.IP "" 0
|
724
|
-
.
|
725
463
|
.P
|
726
464
|
A code block continues until it reaches a line that is not indented (or the end of the article)\.
|
727
|
-
.
|
728
465
|
.P
|
729
466
|
Within a code block, ampersands (\fB&\fR) and angle brackets (\fB<\fR and \fB>\fR) are automatically converted into HTML entities\. This makes it very easy to include example HTML source code using Markdown \-\- just paste it and indent it, and Markdown will handle the hassle of encoding the ampersands and angle brackets\. For example, this:
|
730
|
-
.
|
731
467
|
.IP "" 4
|
732
|
-
.
|
733
468
|
.nf
|
734
|
-
|
735
469
|
<div class="footer">
|
736
470
|
© 2004 Foo Corporation
|
737
471
|
</div>
|
738
|
-
.
|
739
472
|
.fi
|
740
|
-
.
|
741
473
|
.IP "" 0
|
742
|
-
.
|
743
474
|
.P
|
744
475
|
will turn into:
|
745
|
-
.
|
746
476
|
.IP "" 4
|
747
|
-
.
|
748
477
|
.nf
|
749
|
-
|
750
478
|
<pre><code><div class="footer">
|
751
479
|
&copy; 2004 Foo Corporation
|
752
480
|
</div>
|
753
481
|
</code></pre>
|
754
|
-
.
|
755
482
|
.fi
|
756
|
-
.
|
757
483
|
.IP "" 0
|
758
|
-
.
|
759
484
|
.P
|
760
485
|
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\.
|
761
|
-
.
|
762
486
|
.SS "Horizontal Rules"
|
763
487
|
You can produce a horizontal rule tag (\fB<hr />\fR) by placing three or more hyphens, asterisks, or underscores on a line by themselves\. If you wish, you may use spaces between the hyphens or asterisks\. Each of the following lines will produce a horizontal rule:
|
764
|
-
.
|
765
488
|
.IP "" 4
|
766
|
-
.
|
767
489
|
.nf
|
768
|
-
|
769
490
|
* * *
|
770
491
|
|
771
492
|
***
|
@@ -775,323 +496,193 @@ You can produce a horizontal rule tag (\fB<hr />\fR) by placing three or more hy
|
|
775
496
|
\- \- \-
|
776
497
|
|
777
498
|
\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
|
778
|
-
.
|
779
499
|
.fi
|
780
|
-
.
|
781
500
|
.IP "" 0
|
782
|
-
.
|
783
501
|
.SH "SPAN ELEMENTS"
|
784
|
-
.
|
785
502
|
.SS "Links"
|
786
503
|
Markdown supports two style of links: \fIinline\fR and \fIreference\fR\.
|
787
|
-
.
|
788
504
|
.P
|
789
505
|
In both styles, the link text is delimited by [square brackets]\.
|
790
|
-
.
|
791
506
|
.P
|
792
507
|
To create an inline link, use a set of regular parentheses immediately after the link text\'s closing square bracket\. Inside the parentheses, put the URL where you want the link to point, along with an \fIoptional\fR title for the link, surrounded in quotes\. For example:
|
793
|
-
.
|
794
508
|
.IP "" 4
|
795
|
-
.
|
796
509
|
.nf
|
797
|
-
|
798
510
|
This is [an example](http://example\.com/ "Title") inline link\.
|
799
511
|
|
800
512
|
[This link](http://example\.net/) has no title attribute\.
|
801
|
-
.
|
802
513
|
.fi
|
803
|
-
.
|
804
514
|
.IP "" 0
|
805
|
-
.
|
806
515
|
.P
|
807
516
|
Will produce:
|
808
|
-
.
|
809
517
|
.IP "" 4
|
810
|
-
.
|
811
518
|
.nf
|
812
|
-
|
813
519
|
<p>This is <a href="http://example\.com/" title="Title">
|
814
520
|
an example</a> inline link\.</p>
|
815
521
|
|
816
522
|
<p><a href="http://example\.net/">This link</a> has no
|
817
523
|
title attribute\.</p>
|
818
|
-
.
|
819
524
|
.fi
|
820
|
-
.
|
821
525
|
.IP "" 0
|
822
|
-
.
|
823
526
|
.P
|
824
527
|
If you\'re referring to a local resource on the same server, you can use relative paths:
|
825
|
-
.
|
826
528
|
.IP "" 4
|
827
|
-
.
|
828
529
|
.nf
|
829
|
-
|
830
530
|
See my [About](/about/) page for details\.
|
831
|
-
.
|
832
531
|
.fi
|
833
|
-
.
|
834
532
|
.IP "" 0
|
835
|
-
.
|
836
533
|
.P
|
837
534
|
Reference\-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:
|
838
|
-
.
|
839
535
|
.IP "" 4
|
840
|
-
.
|
841
536
|
.nf
|
842
|
-
|
843
537
|
This is [an example][id] reference\-style link\.
|
844
|
-
.
|
845
538
|
.fi
|
846
|
-
.
|
847
539
|
.IP "" 0
|
848
|
-
.
|
849
540
|
.P
|
850
541
|
You can optionally use a space to separate the sets of brackets:
|
851
|
-
.
|
852
542
|
.IP "" 4
|
853
|
-
.
|
854
543
|
.nf
|
855
|
-
|
856
544
|
This is [an example] [id] reference\-style link\.
|
857
|
-
.
|
858
545
|
.fi
|
859
|
-
.
|
860
546
|
.IP "" 0
|
861
|
-
.
|
862
547
|
.P
|
863
548
|
Then, anywhere in the document, you define your link label like this, on a line by itself:
|
864
|
-
.
|
865
549
|
.IP "" 4
|
866
|
-
.
|
867
550
|
.nf
|
868
|
-
|
869
551
|
[id]: http://example\.com/ "Optional Title Here"
|
870
|
-
.
|
871
552
|
.fi
|
872
|
-
.
|
873
553
|
.IP "" 0
|
874
|
-
.
|
875
554
|
.P
|
876
555
|
That is:
|
877
|
-
.
|
878
556
|
.IP "\[ci]" 4
|
879
557
|
Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);
|
880
|
-
.
|
881
558
|
.IP "\[ci]" 4
|
882
559
|
followed by a colon;
|
883
|
-
.
|
884
560
|
.IP "\[ci]" 4
|
885
561
|
followed by one or more spaces (or tabs);
|
886
|
-
.
|
887
562
|
.IP "\[ci]" 4
|
888
563
|
followed by the URL for the link;
|
889
|
-
.
|
890
564
|
.IP "\[ci]" 4
|
891
565
|
optionally followed by a title attribute for the link, enclosed in double or single quotes, or enclosed in parentheses\.
|
892
|
-
.
|
893
566
|
.IP "" 0
|
894
|
-
.
|
895
567
|
.P
|
896
568
|
The following three link definitions are equivalent:
|
897
|
-
.
|
898
569
|
.IP "" 4
|
899
|
-
.
|
900
570
|
.nf
|
901
|
-
|
902
571
|
[foo]: http://example\.com/ "Optional Title Here"
|
903
572
|
[foo]: http://example\.com/ \'Optional Title Here\'
|
904
573
|
[foo]: http://example\.com/ (Optional Title Here)
|
905
|
-
.
|
906
574
|
.fi
|
907
|
-
.
|
908
575
|
.IP "" 0
|
909
|
-
.
|
910
576
|
.P
|
911
577
|
\fBNote:\fR There is a known bug in Markdown\.pl 1\.0\.1 which prevents single quotes from being used to delimit link titles\.
|
912
|
-
.
|
913
578
|
.P
|
914
579
|
The link URL may, optionally, be surrounded by angle brackets:
|
915
|
-
.
|
916
580
|
.IP "" 4
|
917
|
-
.
|
918
581
|
.nf
|
919
|
-
|
920
582
|
[id]: <http://example\.com/> "Optional Title Here"
|
921
|
-
.
|
922
583
|
.fi
|
923
|
-
.
|
924
584
|
.IP "" 0
|
925
|
-
.
|
926
585
|
.P
|
927
586
|
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:
|
928
|
-
.
|
929
587
|
.IP "" 4
|
930
|
-
.
|
931
588
|
.nf
|
932
|
-
|
933
589
|
[id]: http://example\.com/longish/path/to/resource/here
|
934
590
|
"Optional Title Here"
|
935
|
-
.
|
936
591
|
.fi
|
937
|
-
.
|
938
592
|
.IP "" 0
|
939
|
-
.
|
940
593
|
.P
|
941
594
|
Link definitions are only used for creating links during Markdown processing, and are stripped from your document in the HTML output\.
|
942
|
-
.
|
943
595
|
.P
|
944
596
|
Link definition names may consist of letters, numbers, spaces, and punctuation \-\- but they are \fInot\fR case sensitive\. E\.g\. these two links:
|
945
|
-
.
|
946
597
|
.IP "" 4
|
947
|
-
.
|
948
598
|
.nf
|
949
|
-
|
950
599
|
[link text][a]
|
951
600
|
[link text][A]
|
952
|
-
.
|
953
601
|
.fi
|
954
|
-
.
|
955
602
|
.IP "" 0
|
956
|
-
.
|
957
603
|
.P
|
958
604
|
are equivalent\.
|
959
|
-
.
|
960
605
|
.P
|
961
606
|
The \fIimplicit link name\fR 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:
|
962
|
-
.
|
963
607
|
.IP "" 4
|
964
|
-
.
|
965
608
|
.nf
|
966
|
-
|
967
609
|
[Google][]
|
968
|
-
.
|
969
610
|
.fi
|
970
|
-
.
|
971
611
|
.IP "" 0
|
972
|
-
.
|
973
612
|
.P
|
974
613
|
And then define the link:
|
975
|
-
.
|
976
614
|
.IP "" 4
|
977
|
-
.
|
978
615
|
.nf
|
979
|
-
|
980
616
|
[Google]: http://google\.com/
|
981
|
-
.
|
982
617
|
.fi
|
983
|
-
.
|
984
618
|
.IP "" 0
|
985
|
-
.
|
986
619
|
.P
|
987
620
|
Because link names may contain spaces, this shortcut even works for multiple words in the link text:
|
988
|
-
.
|
989
621
|
.IP "" 4
|
990
|
-
.
|
991
622
|
.nf
|
992
|
-
|
993
623
|
Visit [Daring Fireball][] for more information\.
|
994
|
-
.
|
995
624
|
.fi
|
996
|
-
.
|
997
625
|
.IP "" 0
|
998
|
-
.
|
999
626
|
.P
|
1000
627
|
And then define the link:
|
1001
|
-
.
|
1002
628
|
.IP "" 4
|
1003
|
-
.
|
1004
629
|
.nf
|
1005
|
-
|
1006
630
|
[Daring Fireball]: http://daringfireball\.net/
|
1007
|
-
.
|
1008
631
|
.fi
|
1009
|
-
.
|
1010
632
|
.IP "" 0
|
1011
|
-
.
|
1012
633
|
.P
|
1013
634
|
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\.
|
1014
|
-
.
|
1015
635
|
.P
|
1016
636
|
Here\'s an example of reference links in action:
|
1017
|
-
.
|
1018
637
|
.IP "" 4
|
1019
|
-
.
|
1020
638
|
.nf
|
1021
|
-
|
1022
639
|
I get 10 times more traffic from [Google] [1] than from
|
1023
640
|
[Yahoo] [2] or [MSN] [3]\.
|
1024
641
|
|
1025
642
|
[1]: http://google\.com/ "Google"
|
1026
643
|
[2]: http://search\.yahoo\.com/ "Yahoo Search"
|
1027
644
|
[3]: http://search\.msn\.com/ "MSN Search"
|
1028
|
-
.
|
1029
645
|
.fi
|
1030
|
-
.
|
1031
646
|
.IP "" 0
|
1032
|
-
.
|
1033
647
|
.P
|
1034
648
|
Using the implicit link name shortcut, you could instead write:
|
1035
|
-
.
|
1036
649
|
.IP "" 4
|
1037
|
-
.
|
1038
650
|
.nf
|
1039
|
-
|
1040
651
|
I get 10 times more traffic from [Google][] than from
|
1041
652
|
[Yahoo][] or [MSN][]\.
|
1042
653
|
|
1043
654
|
[google]: http://google\.com/ "Google"
|
1044
655
|
[yahoo]: http://search\.yahoo\.com/ "Yahoo Search"
|
1045
656
|
[msn]: http://search\.msn\.com/ "MSN Search"
|
1046
|
-
.
|
1047
657
|
.fi
|
1048
|
-
.
|
1049
658
|
.IP "" 0
|
1050
|
-
.
|
1051
659
|
.P
|
1052
660
|
Both of the above examples will produce the following HTML output:
|
1053
|
-
.
|
1054
661
|
.IP "" 4
|
1055
|
-
.
|
1056
662
|
.nf
|
1057
|
-
|
1058
663
|
<p>I get 10 times more traffic from <a href="http://google\.com/"
|
1059
664
|
title="Google">Google</a> than from
|
1060
665
|
<a href="http://search\.yahoo\.com/" title="Yahoo Search">Yahoo</a>
|
1061
666
|
or <a href="http://search\.msn\.com/" title="MSN Search">MSN</a>\.</p>
|
1062
|
-
.
|
1063
667
|
.fi
|
1064
|
-
.
|
1065
668
|
.IP "" 0
|
1066
|
-
.
|
1067
669
|
.P
|
1068
670
|
For comparison, here is the same paragraph written using Markdown\'s inline link style:
|
1069
|
-
.
|
1070
671
|
.IP "" 4
|
1071
|
-
.
|
1072
672
|
.nf
|
1073
|
-
|
1074
673
|
I get 10 times more traffic from [Google](http://google\.com/ "Google")
|
1075
674
|
than from [Yahoo](http://search\.yahoo\.com/ "Yahoo Search") or
|
1076
675
|
[MSN](http://search\.msn\.com/ "MSN Search")\.
|
1077
|
-
.
|
1078
676
|
.fi
|
1079
|
-
.
|
1080
677
|
.IP "" 0
|
1081
|
-
.
|
1082
678
|
.P
|
1083
679
|
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\.
|
1084
|
-
.
|
1085
680
|
.P
|
1086
681
|
With Markdown\'s reference\-style links, a source document much more closely resembles the final output, as rendered in a browser\. By allowing you to move the markup\-related metadata out of the paragraph, you can add links without interrupting the narrative flow of your prose\.
|
1087
|
-
.
|
1088
682
|
.SS "Emphasis"
|
1089
683
|
Markdown treats asterisks (\fB*\fR) and underscores (\fB_\fR) as indicators of emphasis\. Text wrapped with one \fB*\fR or \fB_\fR will be wrapped with an HTML \fB<em>\fR tag; double \fB*\fR\'s or \fB_\fR\'s will be wrapped with an HTML \fB<strong>\fR tag\. E\.g\., this input:
|
1090
|
-
.
|
1091
684
|
.IP "" 4
|
1092
|
-
.
|
1093
685
|
.nf
|
1094
|
-
|
1095
686
|
*single asterisks*
|
1096
687
|
|
1097
688
|
_single underscores_
|
@@ -1099,18 +690,12 @@ _single underscores_
|
|
1099
690
|
**double asterisks**
|
1100
691
|
|
1101
692
|
__double underscores__
|
1102
|
-
.
|
1103
693
|
.fi
|
1104
|
-
.
|
1105
694
|
.IP "" 0
|
1106
|
-
.
|
1107
695
|
.P
|
1108
696
|
will produce:
|
1109
|
-
.
|
1110
697
|
.IP "" 4
|
1111
|
-
.
|
1112
698
|
.nf
|
1113
|
-
|
1114
699
|
<em>single asterisks</em>
|
1115
700
|
|
1116
701
|
<em>single underscores</em>
|
@@ -1118,325 +703,186 @@ will produce:
|
|
1118
703
|
<strong>double asterisks</strong>
|
1119
704
|
|
1120
705
|
<strong>double underscores</strong>
|
1121
|
-
.
|
1122
706
|
.fi
|
1123
|
-
.
|
1124
707
|
.IP "" 0
|
1125
|
-
.
|
1126
708
|
.P
|
1127
709
|
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\.
|
1128
|
-
.
|
1129
710
|
.P
|
1130
711
|
Emphasis can be used in the middle of a word:
|
1131
|
-
.
|
1132
712
|
.IP "" 4
|
1133
|
-
.
|
1134
713
|
.nf
|
1135
|
-
|
1136
714
|
un*frigging*believable
|
1137
|
-
.
|
1138
715
|
.fi
|
1139
|
-
.
|
1140
716
|
.IP "" 0
|
1141
|
-
.
|
1142
717
|
.P
|
1143
718
|
But if you surround an \fB*\fR or \fB_\fR with spaces, it\'ll be treated as a literal asterisk or underscore\.
|
1144
|
-
.
|
1145
719
|
.P
|
1146
720
|
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:
|
1147
|
-
.
|
1148
721
|
.IP "" 4
|
1149
|
-
.
|
1150
722
|
.nf
|
1151
|
-
|
1152
723
|
\e*this text is surrounded by literal asterisks\e*
|
1153
|
-
.
|
1154
724
|
.fi
|
1155
|
-
.
|
1156
725
|
.IP "" 0
|
1157
|
-
.
|
1158
726
|
.SS "Code"
|
1159
727
|
To indicate a span of code, wrap it with backtick quotes (\fB`\fR)\. Unlike a pre\-formatted code block, a code span indicates code within a normal paragraph\. For example:
|
1160
|
-
.
|
1161
728
|
.IP "" 4
|
1162
|
-
.
|
1163
729
|
.nf
|
1164
|
-
|
1165
730
|
Use the `printf()` function\.
|
1166
|
-
.
|
1167
731
|
.fi
|
1168
|
-
.
|
1169
732
|
.IP "" 0
|
1170
|
-
.
|
1171
733
|
.P
|
1172
734
|
will produce:
|
1173
|
-
.
|
1174
735
|
.IP "" 4
|
1175
|
-
.
|
1176
736
|
.nf
|
1177
|
-
|
1178
737
|
<p>Use the <code>printf()</code> function\.</p>
|
1179
|
-
.
|
1180
738
|
.fi
|
1181
|
-
.
|
1182
739
|
.IP "" 0
|
1183
|
-
.
|
1184
740
|
.P
|
1185
741
|
To include a literal backtick character within a code span, you can use multiple backticks as the opening and closing delimiters:
|
1186
|
-
.
|
1187
742
|
.IP "" 4
|
1188
|
-
.
|
1189
743
|
.nf
|
1190
|
-
|
1191
744
|
``There is a literal backtick (`) here\.``
|
1192
|
-
.
|
1193
745
|
.fi
|
1194
|
-
.
|
1195
746
|
.IP "" 0
|
1196
|
-
.
|
1197
747
|
.P
|
1198
748
|
which will produce this:
|
1199
|
-
.
|
1200
749
|
.IP "" 4
|
1201
|
-
.
|
1202
750
|
.nf
|
1203
|
-
|
1204
751
|
<p><code>There is a literal backtick (`) here\.</code></p>
|
1205
|
-
.
|
1206
752
|
.fi
|
1207
|
-
.
|
1208
753
|
.IP "" 0
|
1209
|
-
.
|
1210
754
|
.P
|
1211
755
|
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:
|
1212
|
-
.
|
1213
756
|
.IP "" 4
|
1214
|
-
.
|
1215
757
|
.nf
|
1216
|
-
|
1217
758
|
A single backtick in a code span: `` ` ``
|
1218
759
|
|
1219
760
|
A backtick\-delimited string in a code span: `` `foo` ``
|
1220
|
-
.
|
1221
761
|
.fi
|
1222
|
-
.
|
1223
762
|
.IP "" 0
|
1224
|
-
.
|
1225
763
|
.P
|
1226
764
|
will produce:
|
1227
|
-
.
|
1228
765
|
.IP "" 4
|
1229
|
-
.
|
1230
766
|
.nf
|
1231
|
-
|
1232
767
|
<p>A single backtick in a code span: <code>`</code></p>
|
1233
768
|
|
1234
769
|
<p>A backtick\-delimited string in a code span: <code>`foo`</code></p>
|
1235
|
-
.
|
1236
770
|
.fi
|
1237
|
-
.
|
1238
771
|
.IP "" 0
|
1239
|
-
.
|
1240
772
|
.P
|
1241
773
|
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:
|
1242
|
-
.
|
1243
774
|
.IP "" 4
|
1244
|
-
.
|
1245
775
|
.nf
|
1246
|
-
|
1247
776
|
Please don\'t use any `<blink>` tags\.
|
1248
|
-
.
|
1249
777
|
.fi
|
1250
|
-
.
|
1251
778
|
.IP "" 0
|
1252
|
-
.
|
1253
779
|
.P
|
1254
780
|
into:
|
1255
|
-
.
|
1256
781
|
.IP "" 4
|
1257
|
-
.
|
1258
782
|
.nf
|
1259
|
-
|
1260
783
|
<p>Please don\'t use any <code><blink></code> tags\.</p>
|
1261
|
-
.
|
1262
784
|
.fi
|
1263
|
-
.
|
1264
785
|
.IP "" 0
|
1265
|
-
.
|
1266
786
|
.P
|
1267
787
|
You can write this:
|
1268
|
-
.
|
1269
788
|
.IP "" 4
|
1270
|
-
.
|
1271
789
|
.nf
|
1272
|
-
|
1273
790
|
`—` is the decimal\-encoded equivalent of `—`\.
|
1274
|
-
.
|
1275
791
|
.fi
|
1276
|
-
.
|
1277
792
|
.IP "" 0
|
1278
|
-
.
|
1279
793
|
.P
|
1280
794
|
to produce:
|
1281
|
-
.
|
1282
795
|
.IP "" 4
|
1283
|
-
.
|
1284
796
|
.nf
|
1285
|
-
|
1286
797
|
<p><code>&#8212;</code> is the decimal\-encoded
|
1287
798
|
equivalent of <code>&mdash;</code>\.</p>
|
1288
|
-
.
|
1289
799
|
.fi
|
1290
|
-
.
|
1291
800
|
.IP "" 0
|
1292
|
-
.
|
1293
801
|
.SS "Images"
|
1294
802
|
Admittedly, it\'s fairly difficult to devise a "natural" syntax for placing images into a plain text document format\.
|
1295
|
-
.
|
1296
803
|
.P
|
1297
804
|
Markdown uses an image syntax that is intended to resemble the syntax for links, allowing for two styles: \fIinline\fR and \fIreference\fR\.
|
1298
|
-
.
|
1299
805
|
.P
|
1300
806
|
Inline image syntax looks like this:
|
1301
|
-
.
|
1302
807
|
.IP "" 4
|
1303
|
-
.
|
1304
808
|
.nf
|
1305
|
-
|
1306
809
|
![Alt text](/path/to/img\.jpg)
|
1307
810
|
|
1308
811
|
![Alt text](/path/to/img\.jpg "Optional title")
|
1309
|
-
.
|
1310
812
|
.fi
|
1311
|
-
.
|
1312
813
|
.IP "" 0
|
1313
|
-
.
|
1314
814
|
.P
|
1315
815
|
That is:
|
1316
|
-
.
|
1317
816
|
.IP "\[ci]" 4
|
1318
817
|
An exclamation mark: \fB!\fR;
|
1319
|
-
.
|
1320
818
|
.IP "\[ci]" 4
|
1321
819
|
followed by a set of square brackets, containing the \fBalt\fR attribute text for the image;
|
1322
|
-
.
|
1323
820
|
.IP "\[ci]" 4
|
1324
821
|
followed by a set of parentheses, containing the URL or path to the image, and an optional \fBtitle\fR attribute enclosed in double or single quotes\.
|
1325
|
-
.
|
1326
822
|
.IP "" 0
|
1327
|
-
.
|
1328
823
|
.P
|
1329
824
|
Reference\-style image syntax looks like this:
|
1330
|
-
.
|
1331
825
|
.IP "" 4
|
1332
|
-
.
|
1333
826
|
.nf
|
1334
|
-
|
1335
827
|
![Alt text][id]
|
1336
|
-
.
|
1337
828
|
.fi
|
1338
|
-
.
|
1339
829
|
.IP "" 0
|
1340
|
-
.
|
1341
830
|
.P
|
1342
831
|
Where "id" is the name of a defined image reference\. Image references are defined using syntax identical to link references:
|
1343
|
-
.
|
1344
832
|
.IP "" 4
|
1345
|
-
.
|
1346
833
|
.nf
|
1347
|
-
|
1348
834
|
[id]: url/to/image "Optional title attribute"
|
1349
|
-
.
|
1350
835
|
.fi
|
1351
|
-
.
|
1352
836
|
.IP "" 0
|
1353
|
-
.
|
1354
837
|
.P
|
1355
838
|
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 \fB<img>\fR tags\.
|
1356
|
-
.
|
1357
839
|
.SH "MISCELLANEOUS"
|
1358
|
-
.
|
1359
840
|
.SS "Automatic Links"
|
1360
841
|
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:
|
1361
|
-
.
|
1362
842
|
.IP "" 4
|
1363
|
-
.
|
1364
843
|
.nf
|
1365
|
-
|
1366
844
|
<http://example\.com/>
|
1367
|
-
.
|
1368
845
|
.fi
|
1369
|
-
.
|
1370
846
|
.IP "" 0
|
1371
|
-
.
|
1372
847
|
.P
|
1373
848
|
Markdown will turn this into:
|
1374
|
-
.
|
1375
849
|
.IP "" 4
|
1376
|
-
.
|
1377
850
|
.nf
|
1378
|
-
|
1379
851
|
<a href="http://example\.com/">http://example\.com/</a>
|
1380
|
-
.
|
1381
852
|
.fi
|
1382
|
-
.
|
1383
853
|
.IP "" 0
|
1384
|
-
.
|
1385
854
|
.P
|
1386
855
|
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:
|
1387
|
-
.
|
1388
856
|
.IP "" 4
|
1389
|
-
.
|
1390
857
|
.nf
|
1391
|
-
|
1392
858
|
<address@example\.com>
|
1393
|
-
.
|
1394
859
|
.fi
|
1395
|
-
.
|
1396
860
|
.IP "" 0
|
1397
|
-
.
|
1398
861
|
.P
|
1399
862
|
into something like this:
|
1400
|
-
.
|
1401
863
|
.IP "" 4
|
1402
|
-
.
|
1403
864
|
.nf
|
1404
|
-
|
1405
865
|
<a href="mailto:addre
|
1406
866
|
ss@example.co
|
1407
867
|
m">address@exa
|
1408
868
|
mple.com</a>
|
1409
|
-
.
|
1410
869
|
.fi
|
1411
|
-
.
|
1412
870
|
.IP "" 0
|
1413
|
-
.
|
1414
871
|
.P
|
1415
872
|
which will render in a browser as a clickable link to "address@example\.com"\.
|
1416
|
-
.
|
1417
873
|
.P
|
1418
874
|
(This sort of entity\-encoding trick will indeed fool many, if not most, address\-harvesting bots, but it definitely won\'t fool all of them\. It\'s better than nothing, but an address published in this way will probably eventually start receiving spam\.)
|
1419
|
-
.
|
1420
875
|
.SS "Backslash Escapes"
|
1421
876
|
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 \fB<em>\fR tag), you can use backslashes before the asterisks, like this:
|
1422
|
-
.
|
1423
877
|
.IP "" 4
|
1424
|
-
.
|
1425
878
|
.nf
|
1426
|
-
|
1427
879
|
\e*literal asterisks\e*
|
1428
|
-
.
|
1429
880
|
.fi
|
1430
|
-
.
|
1431
881
|
.IP "" 0
|
1432
|
-
.
|
1433
882
|
.P
|
1434
883
|
Markdown provides backslash escapes for the following characters:
|
1435
|
-
.
|
1436
884
|
.IP "" 4
|
1437
|
-
.
|
1438
885
|
.nf
|
1439
|
-
|
1440
886
|
\e backslash
|
1441
887
|
` backtick
|
1442
888
|
* asterisk
|
@@ -1447,21 +893,15 @@ _ underscore
|
|
1447
893
|
# hash mark
|
1448
894
|
+ plus sign
|
1449
895
|
\- minus sign (hyphen)
|
1450
|
-
|
896
|
+
\&\. dot
|
1451
897
|
! exclamation mark
|
1452
|
-
.
|
1453
898
|
.fi
|
1454
|
-
.
|
1455
899
|
.IP "" 0
|
1456
|
-
.
|
1457
900
|
.SH "AUTHOR"
|
1458
901
|
Markdown was created by John Gruber\.
|
1459
|
-
.
|
1460
902
|
.P
|
1461
903
|
Manual page by Ryan Tomayko\. It\'s pretty much a direct copy of the Markdown Syntax Reference \fIhttp://daringfireball\.net/projects/markdown/syntax\fR, also by John Gruber\.
|
1462
|
-
.
|
1463
904
|
.SH "SEE ALSO"
|
1464
905
|
ronn(5)
|
1465
|
-
.
|
1466
906
|
.br
|
1467
907
|
\fIhttp://daringfireball\.net/projects/markdown/\fR
|