-
Notifications
You must be signed in to change notification settings - Fork 141
/
markdown.6
543 lines (543 loc) · 12.3 KB
/
markdown.6
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
.TH MARKDOWN 6
.SH NAME
Markdown \- text formatting syntax
.SH DESCRIPTION
Markdown
is a text markup syntax for machine conversion to
the more complex
.SM HTML
or
.SM XHTML
markup languages.
It is intended to be easy to read and to write, with
emphasis on readability.
A Markdown-formatted document should be publishable as-is,
in plain text, without the formatting distracting the reader.
.PP
The biggest source of inspiration for Markdown's
syntax is the format of plain text email. The markup is comprised entirely
of punctuation characters, chosen so as to look like what they mean.
Asterisks around a word look like
.IR *emphasis* .
Markdown lists look like lists. Even
blockquotes look like quoted passages of text, assuming the reader has
used email.
.PP
.SS Block Elements
.TF W
.PD
.TP
Paragraphs and Line Breaks
A paragraph is 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.
.IP
Lines may be freely broken for readability; Markdown
does not translate source line breaks to
.B <br />
tags. To request generation of
.B <br />
in the output, end a line with two or more spaces, then a newline.
.TP
Headings
Headings can be marked in two ways, called
.I setext
and
.IR atx .
.IP
Setext-style headings are
``underlined'' using equal signs (for first-level
headings) and dashes (for second-level headings).
.IP
Atx-style headings use 1-6 hash characters at the start of the line,
corresponding to
.SM HTML
.BR <h^(1-6)^> .
Optional closing hashes may follow
the heading text.
.TP
Blockquotes
Lines beginning with
.B >
are output in blockquotes.
Blockquotes can be nested
by multiple levels of
.BR >> .
Blockquotes can contain other Markdown elements, including
headings, lists, and code blocks.
.TP
Lists
Markdown supports ordered (numbered) and unordered (bulleted) lists.
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, then the list item text.
A newline terminates each list item.
.IP
Unordered lists use asterisks, pluses, and hyphens interchangeably as
list markers.
.IP
Ordered lists use integers followed by periods as list markers.
The order of the integers is not interpreted,
but the list should begin with
.BR 1 .
.IP
If list items are separated by blank lines, Markdown will wrap each list
item in
.B <p>
tags in the
.SM HTML
output.
.IP
List items may consist of multiple paragraphs.
Each subsequent
paragraph within a list item must be indented by either 4 spaces
or one tab.
To put a blockquote within a list item, the blockquote's
.B >
marker needs to be indented.
To put a code block within a list item, the code block needs
to be indented
.I twice
-- 8 spaces or two tabs.
.TP
Code Blocks
To produce a code block, indent every line of the
block by at least 4 spaces or 1 tab.
A code block continues until it reaches a line that is not indented.
.IP
Rather than forming normal paragraphs, the lines
of a code block are interpreted literally.
Regular Markdown syntax is not processed within code blocks.
Markdown wraps a code block in both
.B <pre>
and
.B <code>
tags.
One level of indentation -- 4
spaces or 1 tab -- is removed from each line of the code block in
the output.
.TP
Horizontal Rules
Produce a horizontal rule tag
.RB ( <hr\ /> )
by placing three or
more hyphens, asterisks, or underscores on a line by themselves.
.SS Span Elements
.TF W
.PD
.TP
Links
Markdown supports two styles of links:
.I inline
and
.IR reference .
In both styles, the link text is delimited by square brackets
.RB ( [] ).
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 link URL, along with an optional
title for the link surrounded in double quotes.
For example:
.IP
.EX
An [example](http://example.com/ "Title") inline link.
.EE
.IP
Reference-style links use a second set of square brackets, inside
which you place a label of your choosing to identify the link:
.IP
.EX
An [example][id] reference-style link.
.EE
.IP
The label is then assigned a value on its own line, anywhere in the document:
.IP
.EX
[id]: http://example.com/ "Optional Title"
.EE
.IP
Link label names may consist of letters, numbers, spaces, and
punctuation.
Labels are not case sensitive.
An empty label bracket
set after a reference-style link implies the link label is equivalent to
the link text.
A URL value can then be assigned to the link by referencing
the link text as the label name.
.TP
Emphasis
Markdown treats asterisks
.RB ( * )
and underscores
.RB ( _ )
as indicators of emphasis.
Text surrounded with single asterisks or underscores
will be wrapped with an
.SM HTML
.B <em>
tag.
Double asterisks or underscores generate an
.SM HTML
.B <strong>
tag.
.TP
Code
To indicate a span of code, wrap it with backtick quotes
.RB ( ` ).
Unlike a code block, a code span indicates code within a
normal paragraph.
To include a literal backtick character within a code span, you can use
multiple backticks as the opening and closing delimiters:
.IP
.EX
``There is a literal backtick (`) here.``
.EE
.TP
Images
Markdown image syntax is intended to resemble that
for links, allowing for two styles, once again
.I inline
and
.IR reference .
The syntax is as for each respective style of link, described above, but
prefixed with an exclamation mark character
.RB ( ! ).
Inline image syntax looks like this:
.IP
.EX
![Alt text](/path/to/img.jpg "Optional title")
.EE
.IP
That is:
An exclamation mark;
followed by a set of square brackets containing the `alt'
attribute text for the image;
followed by a set of parentheses containing the URL or path to
the image, and an optional `title' attribute enclosed in double
or single quotes.
.IP
Reference-style image syntax looks like this:
.IP
.EX
![Alt text][id]
.EE
.IP
Where
.I id
is a label used as for reference-style URL links, described above.
.SS Convenience
.TF W
.PD
.TP
Automatic Links
There is a shortcut style for creating ``automatic''
links for URLs and email addresses.
Surround the URL
or address with angle brackets.
.TP
Backslash Escapes
Use backslash escapes to generate literal
characters which would otherwise have special meaning in Markdown's
formatting syntax.
.TP
Inline HTML
For markup that is not covered by Markdown's
syntax, simply use the
.SM HTML
directly.
The only restrictions are that block-level
.SM HTML
elements --
.BR <div> ,
.BR <table> ,
.BR <pre> ,
.BR <p> ,
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 formatting syntax is
not processed within block-level
.SM HTML
tags.
.IP
Span-level
.SM HTML
tags -- e.g.
.BR <span> ,
.BR <cite> ,
or
.B <del>
-- can be
used anywhere in a Markdown
paragraph, list item, or heading.
It is permitted to use
.SM HTML
tags instead of Markdown formatting; e.g.
.SM HTML
.B <a>
or
.B <img>
tags instead of Markdown's
link or image syntax.
Unlike block-level
.SM HTML
tags, Markdown
syntax
.I is
processed within the elements of span-level tags.
.TP
Automatic Special Character Escapes
To be displayed literally in a user agent, the characters
.B <
and
.B &
must appear as escaped entities in
.SM HTML
source, e.g.
.B <
and
.BR & .
Markdown
allows natural use of these characters, taking care of
the necessary escaping.
The ampersand part of a directly-used
.SM HTML
entity remains unchanged; otherwise it will be translated
into
.BR & .
Inside code spans and blocks, angle brackets and
ampersands are always encoded automatically.
This makes it easy to use Markdown to write about
.SM HTML
code.
.PP
.SS Smarty Pants
The
.IR markdown (1)
utility transforms a few plain text symbols into their typographically-fancier
.SM HTML
entity equivalents.
These are extensions to the standard Markdown syntax.
.TF W
.PD
.TP
Punctuation
Input single- and double-quotes are transformed
into ``curly'' quote entities in the output (e.g.,
.B 'text'
becomes
.BR ‘text’ ).
Input double-dashes
.RB ( -- )
and triple-dashes become en- and em-dashes, respectively,
while a series of three dots
.RB ( ... )
in the input becomes an ellipsis entity
.RB ( … )
in the
.SM HTML
output.
.TP
Symbols
Three other transformations replace the common plain-text shorthands
.BR (c) ,
.BR (r) ,
and
.BR (tm)
from the input with their respective
.SM HTML
entities. (As in
.B (c)
becoming
.BR © ,
the Copyright symbol entity.)
.TP
Fractions
A small set of plain-text shorthands for fractions is recognized.
.B 1/4
becomes
.BR ¼ ,
for example. These fraction notations are replaced with their
.SM HTML
entity equivalents:
.BR 1/4 ,
.BR 1/2 ,
.BR 3/4 .
.B 1/4th
and
.B 3/4ths
are replaced with their entity and the indicated ordinal suffix letters.
.PP
Like the basic Markdown syntax, none of the ``Smarty Pants'' extensions are processed
inside code blocks or spans.
.PP
.SS Discount Extensions
.IR Markdown (1)
recognizes some extensions to the Markdown format,
many of them adopted or adapted from other Markdown
interpreters or document formatting systems.
.TF W
.PD
.TP
Pandoc Headers
If
.I markdown
was configured with
.BR --enable-pandoc-header ,
the markdown source can have a 3-line Pandoc header in the format of
.IP
.EX
% Title
% Author
% Date
.EE
.IP
whose data is available to the
.IR mkd_doc_title ,
.IR mkd_doc_author ,
and
.I mkd_doc_date
(in
.IR markdown (2))
functions.
.TP
Embedded Stylesheets
Stylesheets may be defined and modified in a
.B <style>
block. A style block is parsed like any other block-level
.SM HTML;
.B <style>
starting on column 1, raw
.SM HTML
(or, in this case,
.SM CSS \)
following it, and either ending with a
.B </style>
at the end of the line or at the beginning of a subsequent line.
.IP
Style blocks apply to the entire document regardless of where they are defined.
.TP
Image Dimensions
Image specification has been extended with an argument describing image dimensions:
.BI = height x width.
For an image 400 pixels high and 300 wide, the new syntax is:
.IP
.EX
![Alt text](/path/to/image.jpg =400x300 "Title")
.EE
.TP
Pseudo-Protocols
Pseudo-protocols that may replace the common
.B http:
or
.B mailto:
have been added to the link syntax described above.
.IP
.BR abbr :
Text following is used as the
.B title
attribute of an
.B abbr
tag wrapping the link text. So
.B [LT](abbr:Link Text)
gives
.B <abbr title="Link Text">LT</abbr>.
.IP
.BR id :
The link text is marked up and written to the output, wrapped with
.B <a id=text following>
and
.BR </a> .
.IP
.BR class :
The link text is marked up and written to the output, wrapped with
.B <span class=text following>
and
.BR </span> .
.IP
.BR raw :
Text following is written to the output with no further processing.
The link text is discarded.
.TP
Alphabetic Lists
If
.I markdown
was configured with
.BR --enable-alpha-list ,
.IP
.EX
a. this
b. is
c. an alphabetic
d. list
.EE
.IP
yields an
.SM HTML
.B ol
ordered list.
.TP
Definition Lists
If configured with
.BR --enable-dl-tag ,
markup for definition lists is enabled. A definition list item is defined as
.IP
.EX
=term=
definition
.EE
.TP
Tables
Tables are specified with a pipe
.RB ( | )
and dash
.RB ( - )
marking. The markdown text
.IP
.EX
header0|header1
-------|-------
textA|textB
textC|textD
.EE
.IP
will produce an
.SM HTML
.B table
of two columns and three rows.
A header row is designated by ``underlining'' with dashes.
Declare a column's alignment by affixing a colon
.RB ( : )
to the left or right end of the dashes underlining its header.
In the output, this
yields the corresponding value for the
.B align
attribute on each
.B td
cell in the column.
A colon at both ends of a column's header dashes indicates center alignment.
.TP
Relaxed Emphasis
If configured with
.BR --relaxed-emphasis ,
the rules for emphasis are changed so that a single
.B _
will not count as an emphasis character in the middle of a word.
This is useful for documenting some code where
.B _
appears frequently, and would normally require a backslash escape.
.PD
.SH SEE ALSO
.IR markdown (1),
.IR markdown (2)
.PP
http://daringfireball.net/projects/markdown/syntax/,
``Markdown: Syntax''.
.PP
http://daringfireball.net/projects/smartypants/,
``Smarty Pants''.
.PP
http://michelf.com/projects/php-markdown/extra/#table,
``PHP Markdown Extra: Tables''.