@@ -1,1726 +0,0 @@
1−.\"t
2−.TH PANDOC_MARKDOWN 5 "July 30, 2011" "Pandoc"
3−.SH NAME
4−pandoc_markdown - markdown syntax for pandoc(1)
5−.SH DESCRIPTION
6−.PP
7−Pandoc understands an extended and slightly revised version of John
8−Gruber\[aq]s markdown syntax.
9−This document explains the syntax, noting differences from standard
10−markdown.
11−Except where noted, these differences can be suppressed by specifying
12−the \f[C]--strict\f[] command-line option.
13−.SH PHILOSOPHY
14−.PP
15−Markdown is designed to be easy to write, and, even more importantly,
16−easy to read:
17−.RS
18−.PP
19−A Markdown-formatted document should be publishable as-is, as plain
20−text, without looking like it\[aq]s been marked up with tags or
21−formatting instructions.
22−-- John Gruber
23−.RE
24−.PP
25−This principle has guided pandoc\[aq]s decisions in finding syntax for
26−tables, footnotes, and other extensions.
27−.PP
28−There is, however, one respect in which pandoc\[aq]s aims are different
29−from the original aims of markdown.
30−Whereas markdown was originally designed with HTML generation in mind,
31−pandoc is designed for multiple output formats.
32−Thus, while pandoc allows the embedding of raw HTML, it discourages it,
33−and provides other, non-HTMLish ways of representing important document
34−elements like definition lists, tables, mathematics, and footnotes.
35−.SH PARAGRAPHS
36−.PP
37−A paragraph is one or more lines of text followed by one or more blank
38−line.
39−Newlines are treated as spaces, so you can reflow your paragraphs as you
40−like.
41−If you need a hard line break, put two or more spaces at the end of a
42−line, or type a backslash followed by a newline.
43−.SH HEADERS
44−.PP
45−There are two kinds of headers, Setext and atx.
46−.SS Setext-style headers
47−.PP
48−A setext-style header is a line of text "underlined" with a row of
49−\f[C]=\f[] signs (for a level one header) of \f[C]-\f[] signs (for a
50−level two header):
51−.IP
52−.nf
53−\f[C]
54−A\ level-one\ header
55−==================
56−
57−A\ level-two\ header
58−------------------
59−\f[]
60−.fi
61−.PP
62−The header text can contain inline formatting, such as emphasis (see
63−Inline formatting, below).
64−.SS Atx-style headers
65−.PP
66−An Atx-style header consists of one to six \f[C]#\f[] signs and a line
67−of text, optionally followed by any number of \f[C]#\f[] signs.
68−The number of \f[C]#\f[] signs at the beginning of the line is the
69−header level:
70−.IP
71−.nf
72−\f[C]
73−##\ A\ level-two\ header
74−
75−###\ A\ level-three\ header\ ###
76−\f[]
77−.fi
78−.PP
79−As with setext-style headers, the header text can contain formatting:
80−.IP
81−.nf
82−\f[C]
83−#\ A\ level-one\ header\ with\ a\ [link](/url)\ and\ *emphasis*
84−\f[]
85−.fi
86−.PP
87−Standard markdown syntax does not require a blank line before a header.
88−Pandoc does require this (except, of course, at the beginning of the
89−document).
90−The reason for the requirement is that it is all too easy for a
91−\f[C]#\f[] to end up at the beginning of a line by accident (perhaps
92−through line wrapping).
93−Consider, for example:
94−.IP
95−.nf
96−\f[C]
97−I\ like\ several\ of\ their\ flavors\ of\ ice\ cream:
98−#22,\ for\ example,\ and\ #5.
99−\f[]
100−.fi
101−.SS Header identifiers in HTML
102−.PP
103−\f[I]Pandoc extension\f[].
104−.PP
105−Each header element in pandoc\[aq]s HTML output is given a unique
106−identifier.
107−This identifier is based on the text of the header.
108−To derive the identifier from the header text,
109−.IP \[bu] 2
110−Remove all formatting, links, etc.
111−.IP \[bu] 2
112−Remove all punctuation, except underscores, hyphens, and periods.
113−.IP \[bu] 2
114−Replace all spaces and newlines with hyphens.
115−.IP \[bu] 2
116−Convert all alphabetic characters to lowercase.
117−.IP \[bu] 2
118−Remove everything up to the first letter (identifiers may not begin with
119−a number or punctuation mark).
120−.IP \[bu] 2
121−If nothing is left after this, use the identifier \f[C]section\f[].
122−.PP
123−Thus, for example,
124−.PP
125−.TS
126−tab(@);
127−l l.
128−T{
129−Header
130−T}@T{
131−Identifier
132−T}
133−_
134−T{
135−Header identifiers in HTML
136−T}@T{
137−\f[C]header-identifiers-in-html\f[]
138−T}
139−T{
140−\f[I]Dogs\f[]?--in \f[I]my\f[] house?
141−T}@T{
142−\f[C]dogs--in-my-house\f[]
143−T}
144−T{
145−HTML, S5, or RTF?
146−T}@T{
147−\f[C]html-s5-or-rtf\f[]
148−T}
149−T{
150−3.
151−Applications
152−T}@T{
153−\f[C]applications\f[]
154−T}
155−T{
156−33
157−T}@T{
158−\f[C]section\f[]
159−T}
160−.TE
161−.PP
162−These rules should, in most cases, allow one to determine the identifier
163−from the header text.
164−The exception is when several headers have the same text; in this case,
165−the first will get an identifier as described above; the second will get
166−the same identifier with \f[C]-1\f[] appended; the third with
167−\f[C]-2\f[]; and so on.
168−.PP
169−These identifiers are used to provide link targets in the table of
170−contents generated by the \f[C]--toc|--table-of-contents\f[] option.
171−They also make it easy to provide links from one section of a document
172−to another.
173−A link to this section, for example, might look like this:
174−.IP
175−.nf
176−\f[C]
177−See\ the\ section\ on
178−[header\ identifiers](#header-identifiers-in-html).
179−\f[]
180−.fi
181−.PP
182−Note, however, that this method of providing links to sections works
183−only in HTML.
184−.PP
185−If the \f[C]--section-divs\f[] option is specified, then each section
186−will be wrapped in a \f[C]div\f[] (or a \f[C]section\f[], if
187−\f[C]--html5\f[] was specified), and the identifier will be attached to
188−the enclosing \f[C]<div>\f[] (or \f[C]<section>\f[]) tag rather than the
189−header itself.
190−This allows entire sections to be manipulated using javascript or
191−treated differently in CSS.
192−.SH BLOCK QUOTATIONS
193−.PP
194−Markdown uses email conventions for quoting blocks of text.
195−A block quotation is one or more paragraphs or other block elements
196−(such as lists or headers), with each line preceded by a \f[C]>\f[]
197−character and a space.
198−(The \f[C]>\f[] need not start at the left margin, but it should not be
199−indented more than three spaces.)
200−.IP
201−.nf
202−\f[C]
203−>\ This\ is\ a\ block\ quote.\ This
204−>\ paragraph\ has\ two\ lines.
205−>
206−>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
207−>\ 2.\ Second\ item.
208−\f[]
209−.fi
210−.PP
211−A "lazy" form, which requires the \f[C]>\f[] character only on the first
212−line of each block, is also allowed:
213−.IP
214−.nf
215−\f[C]
216−>\ This\ is\ a\ block\ quote.\ This
217−paragraph\ has\ two\ lines.
218−
219−>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
220−2.\ Second\ item.
221−\f[]
222−.fi
223−.PP
224−Among the block elements that can be contained in a block quote are
225−other block quotes.
226−That is, block quotes can be nested:
227−.IP
228−.nf
229−\f[C]
230−>\ This\ is\ a\ block\ quote.
231−>
232−>\ >\ A\ block\ quote\ within\ a\ block\ quote.
233−\f[]
234−.fi
235−.PP
236−Standard markdown syntax does not require a blank line before a block
237−quote.
238−Pandoc does require this (except, of course, at the beginning of the
239−document).
240−The reason for the requirement is that it is all too easy for a
241−\f[C]>\f[] to end up at the beginning of a line by accident (perhaps
242−through line wrapping).
243−So, unless \f[C]--strict\f[] is used, the following does not produce a
244−nested block quote in pandoc:
245−.IP
246−.nf
247−\f[C]
248−>\ This\ is\ a\ block\ quote.
249−>>\ Nested.
250−\f[]
251−.fi
252−.SH VERBATIM (CODE) BLOCKS
253−.SS Indented code blocks
254−.PP
255−A block of text indented four spaces (or one tab) is treated as verbatim
256−text: that is, special characters do not trigger special formatting, and
257−all spaces and line breaks are preserved.
258−For example,
259−.IP
260−.nf
261−\f[C]
262−\ \ \ \ if\ (a\ >\ 3)\ {
263−\ \ \ \ \ \ moveShip(5\ *\ gravity,\ DOWN);
264−\ \ \ \ }
265−\f[]
266−.fi
267−.PP
268−The initial (four space or one tab) indentation is not considered part
269−of the verbatim text, and is removed in the output.
270−.PP
271−Note: blank lines in the verbatim text need not begin with four spaces.
272−.SS Delimited code blocks
273−.PP
274−\f[I]Pandoc extension\f[].
275−.PP
276−In addition to standard indented code blocks, Pandoc supports
277−\f[I]delimited\f[] code blocks.
278−These begin with a row of three or more tildes (\f[C]~\f[]) and end with
279−a row of tildes that must be at least as long as the starting row.
280−Everything between the tilde-lines is treated as code.
281−No indentation is necessary:
282−.IP
283−.nf
284−\f[C]
285−~~~~~~~
286−if\ (a\ >\ 3)\ {
287−\ \ moveShip(5\ *\ gravity,\ DOWN);
288−}
289−~~~~~~~
290−\f[]
291−.fi
292−.PP
293−Like regular code blocks, delimited code blocks must be separated from
294−surrounding text by blank lines.
295−.PP
296−If the code itself contains a row of tildes, just use a longer row of
297−tildes at the start and end:
298−.IP
299−.nf
300−\f[C]
301−~~~~~~~~~~~~~~~~
302−~~~~~~~~~~
303−code\ including\ tildes
304−~~~~~~~~~~
305−~~~~~~~~~~~~~~~~
306−\f[]
307−.fi
308−.PP
309−Optionally, you may specify the language of the code block using this
310−syntax:
311−.IP
312−.nf
313−\f[C]
314−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ {.haskell\ .numberLines}
315−qsort\ []\ \ \ \ \ =\ []
316−qsort\ (x:xs)\ =\ qsort\ (filter\ (<\ x)\ xs)\ ++\ [x]\ ++
317−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qsort\ (filter\ (>=\ x)\ xs)\
318−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
319−\f[]
320−.fi
321−.PP
322−Some output formats can use this information to do syntax highlighting.
323−Currently, the only output format that uses this information is HTML.
324−.PP
325−If pandoc has been compiled with syntax highlighting support, then the
326−code block above will appear highlighted, with numbered lines.
327−(To see which languages are supported, do \f[C]pandoc\ --version\f[].)
328−.PP
329−If pandoc has not been compiled with syntax highlighting support, the
330−code block above will appear as follows:
331−.IP
332−.nf
333−\f[C]
334−<pre\ class="haskell">
335−\ \ <code>
336−\ \ ...
337−\ \ </code>
338−</pre>
339−\f[]
340−.fi
341−.SH LISTS
342−.SS Bullet lists
343−.PP
344−A bullet list is a list of bulleted list items.
345−A bulleted list item begins with a bullet (\f[C]*\f[], \f[C]+\f[], or
346−\f[C]-\f[]).
347−Here is a simple example:
348−.IP
349−.nf
350−\f[C]
351−*\ one
352−*\ two
353−*\ three
354−\f[]
355−.fi
356−.PP
357−This will produce a "compact" list.
358−If you want a "loose" list, in which each item is formatted as a
359−paragraph, put spaces between the items:
360−.IP
361−.nf
362−\f[C]
363−*\ one
364−
365−*\ two
366−
367−*\ three
368−\f[]
369−.fi
370−.PP
371−The bullets need not be flush with the left margin; they may be indented
372−one, two, or three spaces.
373−The bullet must be followed by whitespace.
374−.PP
375−List items look best if subsequent lines are flush with the first line
376−(after the bullet):
377−.IP
378−.nf
379−\f[C]
380−*\ here\ is\ my\ first
381−\ \ list\ item.
382−*\ and\ my\ second.
383−\f[]
384−.fi
385−.PP
386−But markdown also allows a "lazy" format:
387−.IP
388−.nf
389−\f[C]
390−*\ here\ is\ my\ first
391−list\ item.
392−*\ and\ my\ second.
393−\f[]
394−.fi
395−.SS The four-space rule
396−.PP
397−A list item may contain multiple paragraphs and other block-level
398−content.
399−However, subsequent paragraphs must be preceded by a blank line and
400−indented four spaces or a tab.
401−The list will look better if the first paragraph is aligned with the
402−rest:
403−.IP
404−.nf
405−\f[C]
406−\ \ *\ First\ paragraph.
407−
408−\ \ \ \ Continued.
409−
410−\ \ *\ Second\ paragraph.\ With\ a\ code\ block,\ which\ must\ be\ indented
411−\ \ \ \ eight\ spaces:
412−
413−\ \ \ \ \ \ \ \ {\ code\ }
414−\f[]
415−.fi
416−.PP
417−List items may include other lists.
418−In this case the preceding blank line is optional.
419−The nested list must be indented four spaces or one tab:
420−.IP
421−.nf
422−\f[C]
423−*\ fruits
424−\ \ \ \ +\ apples
425−\ \ \ \ \ \ \ \ -\ macintosh
426−\ \ \ \ \ \ \ \ -\ red\ delicious
427−\ \ \ \ +\ pears
428−\ \ \ \ +\ peaches
429−*\ vegetables
430−\ \ \ \ +\ brocolli
431−\ \ \ \ +\ chard
432−\f[]
433−.fi
434−.PP
435−As noted above, markdown allows you to write list items "lazily,"
436−instead of indenting continuation lines.
437−However, if there are multiple paragraphs or other blocks in a list
438−item, the first line of each must be indented.
439−.IP
440−.nf
441−\f[C]
442−+\ A\ lazy,\ lazy,\ list
443−item.
444−
445−+\ Another\ one;\ this\ looks
446−bad\ but\ is\ legal.
447−
448−\ \ \ \ Second\ paragraph\ of\ second
449−list\ item.
450−\f[]
451−.fi
452−.PP
453−\f[B]Note:\f[] Although the four-space rule for continuation paragraphs
454−comes from the official markdown syntax guide, the reference
455−implementation, \f[C]Markdown.pl\f[], does not follow it.
456−So pandoc will give different results than \f[C]Markdown.pl\f[] when
457−authors have indented continuation paragraphs fewer than four spaces.
458−.PP
459−The markdown syntax guide is not explicit whether the four-space rule
460−applies to \f[I]all\f[] block-level content in a list item; it only
461−mentions paragraphs and code blocks.
462−But it implies that the rule applies to all block-level content
463−(including nested lists), and pandoc interprets it that way.
464−.SS Ordered lists
465−.PP
466−Ordered lists work just like bulleted lists, except that the items begin
467−with enumerators rather than bullets.
468−.PP
469−In standard markdown, enumerators are decimal numbers followed by a
470−period and a space.
471−The numbers themselves are ignored, so there is no difference between
472−this list:
473−.IP
474−.nf
475−\f[C]
476−1.\ \ one
477−2.\ \ two
478−3.\ \ three
479−\f[]
480−.fi
481−.PP
482−and this one:
483−.IP
484−.nf
485−\f[C]
486−5.\ \ one
487−7.\ \ two
488−1.\ \ three
489−\f[]
490−.fi
491−.PP
492−\f[I]Pandoc extension\f[].
493−.PP
494−Unlike standard markdown, Pandoc allows ordered list items to be marked
495−with uppercase and lowercase letters and roman numerals, in addition to
496−arabic numerals.
497−List markers may be enclosed in parentheses or followed by a single
498−right-parentheses or period.
499−They must be separated from the text that follows by at least one space,
500−and, if the list marker is a capital letter with a period, by at least
501−two spaces.[1]
502−.PP
503−Pandoc also pays attention to the type of list marker used, and to the
504−starting number, and both of these are preserved where possible in the
505−output format.
506−Thus, the following yields a list with numbers followed by a single
507−parenthesis, starting with 9, and a sublist with lowercase roman
508−numerals:
509−.IP
510−.nf
511−\f[C]
512−\ 9)\ \ Ninth
513−10)\ \ Tenth
514−11)\ \ Eleventh
515−\ \ \ \ \ \ \ i.\ subone
516−\ \ \ \ \ \ ii.\ subtwo
517−\ \ \ \ \ iii.\ subthree
518−\f[]
519−.fi
520−.PP
521−Note that Pandoc pays attention only to the \f[I]starting\f[] marker in
522−a list.
523−So, the following yields a list numbered sequentially starting from 2:
524−.IP
525−.nf
526−\f[C]
527−(2)\ Two
528−(5)\ Three
529−1.\ \ Four
530−*\ \ \ Five
531−\f[]
532−.fi
533−.PP
534−If default list markers are desired, use \f[C]#.\f[]:
535−.IP
536−.nf
537−\f[C]
538−#.\ \ one
539−#.\ \ two
540−#.\ \ three
541−\f[]
542−.fi
543−.SS Definition lists
544−.PP
545−\f[I]Pandoc extension\f[].
546−.PP
547−Pandoc supports definition lists, using a syntax inspired by PHP
548−Markdown Extra and reStructuredText:[2]
549−.IP
550−.nf
551−\f[C]
552−Term\ 1
553−
554−:\ \ \ Definition\ 1
555−
556−Term\ 2\ with\ *inline\ markup*
557−
558−:\ \ \ Definition\ 2
559−
560−\ \ \ \ \ \ \ \ {\ some\ code,\ part\ of\ Definition\ 2\ }
561−
562−\ \ \ \ Third\ paragraph\ of\ definition\ 2.
563−\f[]
564−.fi
565−.PP
566−Each term must fit on one line, which may optionally be followed by a
567−blank line, and must be followed by one or more definitions.
568−A definition begins with a colon or tilde, which may be indented one or
569−two spaces.
570−A term may have multiple definitions, and each definition may consist of
571−one or more block elements (paragraph, code block, list, etc.)
572−, each indented four spaces or one tab stop.
573−.PP
574−If you leave space after the definition (as in the example above), the
575−blocks of the definitions will be considered paragraphs.
576−In some output formats, this will mean greater spacing between
577−term/definition pairs.
578−For a compact definition list, do not leave space between the definition
579−and the next term:
580−.IP
581−.nf
582−\f[C]
583−Term\ 1
584−\ \ ~\ Definition\ 1
585−Term\ 2
586−\ \ ~\ Definition\ 2a
587−\ \ ~\ Definition\ 2b
588−\f[]
589−.fi
590−.SS Numbered example lists
591−.PP
592−\f[I]Pandoc extension\f[].
593−.PP
594−The special list marker \f[C]\@\f[] can be used for sequentially
595−numbered examples.
596−The first list item with a \f[C]\@\f[] marker will be numbered
597−\[aq]1\[aq], the next \[aq]2\[aq], and so on, throughout the document.
598−The numbered examples need not occur in a single list; each new list
599−using \f[C]\@\f[] will take up where the last stopped.
600−So, for example:
601−.IP
602−.nf
603−\f[C]
604−(\@)\ \ My\ first\ example\ will\ be\ numbered\ (1).
605−(\@)\ \ My\ second\ example\ will\ be\ numbered\ (2).
606−
607−Explanation\ of\ examples.
608−
609−(\@)\ \ My\ third\ example\ will\ be\ numbered\ (3).
610−\f[]
611−.fi
612−.PP
613−Numbered examples can be labeled and referred to elsewhere in the
614−document:
615−.IP
616−.nf
617−\f[C]
618−(\@good)\ \ This\ is\ a\ good\ example.
619−
620−As\ (\@good)\ illustrates,\ ...
621−\f[]
622−.fi
623−.PP
624−The label can be any string of alphanumeric characters, underscores, or
625−hyphens.
626−.SS Compact and loose lists
627−.PP
628−Pandoc behaves differently from \f[C]Markdown.pl\f[] on some "edge
629−cases" involving lists.
630−Consider this source:
631−.IP
632−.nf
633−\f[C]
634−+\ \ \ First
635−+\ \ \ Second:
636−\ -\ \ \ Fee
637−\ -\ \ \ Fie
638−\ -\ \ \ Foe
639−
640−+\ \ \ Third
641−\f[]
642−.fi
643−.PP
644−Pandoc transforms this into a "compact list" (with no \f[C]<p>\f[] tags
645−around "First", "Second", or "Third"), while markdown puts \f[C]<p>\f[]
646−tags around "Second" and "Third" (but not "First"), because of the blank
647−space around "Third".
648−Pandoc follows a simple rule: if the text is followed by a blank line,
649−it is treated as a paragraph.
650−Since "Second" is followed by a list, and not a blank line, it isn\[aq]t
651−treated as a paragraph.
652−The fact that the list is followed by a blank line is irrelevant.
653−(Note: Pandoc works this way even when the \f[C]--strict\f[] option is
654−specified.
655−This behavior is consistent with the official markdown syntax
656−description, even though it is different from that of
657−\f[C]Markdown.pl\f[].)
658−.SS Ending a list
659−.PP
660−What if you want to put an indented code block after a list?
661−.IP
662−.nf
663−\f[C]
664−-\ \ \ item\ one
665−-\ \ \ item\ two
666−
667−\ \ \ \ {\ my\ code\ block\ }
668−\f[]
669−.fi
670−.PP
671−Trouble! Here pandoc (like other markdown implementations) will treat
672−\f[C]{\ my\ code\ block\ }\f[] as the second paragraph of item two, and
673−not as a code block.
674−.PP
675−To "cut off" the list after item two, you can insert some non-indented
676−content, like an HTML comment, which won\[aq]t produce visible output in
677−any format:
678−.IP
679−.nf
680−\f[C]
681−-\ \ \ item\ one
682−-\ \ \ item\ two
683−
684−<!--\ end\ of\ list\ -->
685−
686−\ \ \ \ {\ my\ code\ block\ }
687−\f[]
688−.fi
689−.PP
690−You can use the same trick if you want two consecutive lists instead of
691−one big list:
692−.IP
693−.nf
694−\f[C]
695−1.\ \ one
696−2.\ \ two
697−3.\ \ three
698−
699−<!--\ -->
700−
701−a.\ \ uno
702−b.\ \ dos
703−c.\ \ tres
704−\f[]
705−.fi
706−.SH HORIZONTAL RULES
707−.PP
708−A line containing a row of three or more \f[C]*\f[], \f[C]-\f[], or
709−\f[C]_\f[] characters (optionally separated by spaces) produces a
710−horizontal rule:
711−.IP
712−.nf
713−\f[C]
714−*\ \ *\ \ *\ \ *
715−
716−---------------
717−\f[]
718−.fi
719−.SH TABLES
720−.PP
721−\f[I]Pandoc extension\f[].
722−.PP
723−Three kinds of tables may be used.
724−All three kinds presuppose the use of a fixed-width font, such as
725−Courier.
726−.PP
727−\f[B]Simple tables\f[] look like this:
728−.IP
729−.nf
730−\f[C]
731−\ \ Right\ \ \ \ \ Left\ \ \ \ \ Center\ \ \ \ \ Default
732−-------\ \ \ \ \ ------\ ----------\ \ \ -------
733−\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ 12
734−\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ 123
735−\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ 1
736−
737−Table:\ \ Demonstration\ of\ simple\ table\ syntax.
738−\f[]
739−.fi
740−.PP
741−The headers and table rows must each fit on one line.
742−Column alignments are determined by the position of the header text
743−relative to the dashed line below it:[3]
744−.IP \[bu] 2
745−If the dashed line is flush with the header text on the right side but
746−extends beyond it on the left, the column is right-aligned.
747−.IP \[bu] 2
748−If the dashed line is flush with the header text on the left side but
749−extends beyond it on the right, the column is left-aligned.
750−.IP \[bu] 2
751−If the dashed line extends beyond the header text on both sides, the
752−column is centered.
753−.IP \[bu] 2
754−If the dashed line is flush with the header text on both sides, the
755−default alignment is used (in most cases, this will be left).
756−.PP
757−The table must end with a blank line, or a line of dashes followed by a
758−blank line.
759−A caption may optionally be provided (as illustrated in the example
760−above).
761−A caption is a paragraph beginning with the string \f[C]Table:\f[] (or
762−just \f[C]:\f[]), which will be stripped off.
763−It may appear either before or after the table.
764−.PP
765−The column headers may be omitted, provided a dashed line is used to end
766−the table.
767−For example:
768−.IP
769−.nf
770−\f[C]
771−-------\ \ \ \ \ ------\ ----------\ \ \ -------
772−\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ \ 12
773−\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ \ 123
774−\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ 1
775−-------\ \ \ \ \ ------\ ----------\ \ \ -------
776−\f[]
777−.fi
778−.PP
779−When headers are omitted, column alignments are determined on the basis
780−of the first line of the table body.
781−So, in the tables above, the columns would be right, left, center, and
782−right aligned, respectively.
783−.PP
784−\f[B]Multiline tables\f[] allow headers and table rows to span multiple
785−lines of text (but cells that span multiple columns or rows of the table
786−are not supported).
787−Here is an example:
788−.IP
789−.nf
790−\f[C]
791−-------------------------------------------------------------
792−\ Centered\ \ \ Default\ \ \ \ \ \ \ \ \ \ \ Right\ Left
793−\ \ Header\ \ \ \ Aligned\ \ \ \ \ \ \ \ \ Aligned\ Aligned
794−-----------\ -------\ ---------------\ -------------------------
795−\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that
796−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.
797−
798−\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note
799−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
800−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
801−-------------------------------------------------------------
802−
803−Table:\ Here\[aq]s\ the\ caption.\ It,\ too,\ may\ span
804−multiple\ lines.
805−\f[]
806−.fi
807−.PP
808−These work like simple tables, but with the following differences:
809−.IP \[bu] 2
810−They must begin with a row of dashes, before the header text (unless the
811−headers are omitted).
812−.IP \[bu] 2
813−They must end with a row of dashes, then a blank line.
814−.IP \[bu] 2
815−The rows must be separated by blank lines.
816−.PP
817−In multiline tables, the table parser pays attention to the widths of
818−the columns, and the writers try to reproduce these relative widths in
819−the output.
820−So, if you find that one of the columns is too narrow in the output, try
821−widening it in the markdown source.
822−.PP
823−Headers may be omitted in multiline tables as well as simple tables:
824−.IP
825−.nf
826−\f[C]
827−-----------\ -------\ ---------------\ -------------------------
828−\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that
829−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.
830−
831−\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note
832−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
833−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
834−-------------------------------------------------------------
835−
836−:\ Here\[aq]s\ a\ multiline\ table\ without\ headers.
837−\f[]
838−.fi
839−.PP
840−It is possible for a multiline table to have just one row, but the row
841−should be followed by a blank line (and then the row of dashes that ends
842−the table), or the table may be interpreted as a simple table.
843−.PP
844−\f[B]Grid tables\f[] look like this:
845−.IP
846−.nf
847−\f[C]
848−:\ Sample\ grid\ table.
849−
850−+---------------+---------------+--------------------+
851−|\ Fruit\ \ \ \ \ \ \ \ \ |\ Price\ \ \ \ \ \ \ \ \ |\ Advantages\ \ \ \ \ \ \ \ \ |
852−+===============+===============+====================+
853−|\ Bananas\ \ \ \ \ \ \ |\ $1.34\ \ \ \ \ \ \ \ \ |\ -\ built-in\ wrapper\ |
854−|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ -\ bright\ color\ \ \ \ \ |
855−+---------------+---------------+--------------------+
856−|\ Oranges\ \ \ \ \ \ \ |\ $2.10\ \ \ \ \ \ \ \ \ |\ -\ cures\ scurvy\ \ \ \ \ |
857−|\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ |\ -\ tasty\ \ \ \ \ \ \ \ \ \ \ \ |
858−+---------------+---------------+--------------------+
859−\f[]
860−.fi
861−.PP
862−The row of \f[C]=\f[]s separates the header from the table body, and can
863−be omitted for a headerless table.
864−The cells of grid tables may contain arbitrary block elements (multiple
865−paragraphs, code blocks, lists, etc.)
866−\&.
867−Alignments are not supported, nor are cells that span multiple columns
868−or rows.
869−Grid tables can be created easily using Emacs table mode.
870−.SH TITLE BLOCK
871−.PP
872−\f[I]Pandoc extension\f[].
873−.PP
874−If the file begins with a title block
875−.IP
876−.nf
877−\f[C]
878−%\ title
879−%\ author(s)\ (separated\ by\ semicolons)
880−%\ date
881−\f[]
882−.fi
883−.PP
884−it will be parsed as bibliographic information, not regular text.
885−(It will be used, for example, in the title of standalone LaTeX or HTML
886−output.)
887− The block may contain just a title, a title and an author, or all three
888−elements.
889−If you want to include an author but no title, or a title and a date but
890−no author, you need a blank line:
891−.IP
892−.nf
893−\f[C]
894−%
895−%\ Author
896−
897−%\ My\ title
898−%
899−%\ June\ 15,\ 2006
900−\f[]
901−.fi
902−.PP
903−The title may occupy multiple lines, but continuation lines must begin
904−with leading space, thus:
905−.IP
906−.nf
907−\f[C]
908−%\ My\ title
909−\ \ on\ multiple\ lines
910−\f[]
911−.fi
912−.PP
913−If a document has multiple authors, the authors may be put on separate
914−lines with leading space, or separated by semicolons, or both.
915−So, all of the following are equivalent:
916−.IP
917−.nf
918−\f[C]
919−%\ Author\ One
920−\ \ Author\ Two
921−
922−%\ Author\ One;\ Author\ Two
923−
924−%\ Author\ One;
925−\ \ Author\ Two
926−\f[]
927−.fi
928−.PP
929−The date must fit on one line.
930−.PP
931−All three metadata fields may contain standard inline formatting
932−(italics, links, footnotes, etc.)
933−\&.
934−.PP
935−Title blocks will always be parsed, but they will affect the output only
936−when the \f[C]--standalone\f[] (\f[C]-s\f[]) option is chosen.
937−In HTML output, titles will appear twice: once in the document head --
938−this is the title that will appear at the top of the window in a browser
939−-- and once at the beginning of the document body.
940−The title in the document head can have an optional prefix attached
941−(\f[C]--title-prefix\f[] or \f[C]-T\f[] option).
942−The title in the body appears as an H1 element with class "title", so it
943−can be suppressed or reformatted with CSS.
944−If a title prefix is specified with \f[C]-T\f[] and no title block
945−appears in the document, the title prefix will be used by itself as the
946−HTML title.
947−.PP
948−The man page writer extracts a title, man page section number, and other
949−header and footer information from the title line.
950−The title is assumed to be the first word on the title line, which may
951−optionally end with a (single-digit) section number in parentheses.
952−(There should be no space between the title and the parentheses.)
953− Anything after this is assumed to be additional footer and header text.
954−A single pipe character (\f[C]|\f[]) should be used to separate the
955−footer text from the header text.
956−Thus,
957−.IP
958−.nf
959−\f[C]
960−%\ PANDOC(1)
961−\f[]
962−.fi
963−.PP
964−will yield a man page with the title \f[C]PANDOC\f[] and section 1.
965−.IP
966−.nf
967−\f[C]
968−%\ PANDOC(1)\ Pandoc\ User\ Manuals
969−\f[]
970−.fi
971−.PP
972−will also have "Pandoc User Manuals" in the footer.
973−.IP
974−.nf
975−\f[C]
976−%\ PANDOC(1)\ Pandoc\ User\ Manuals\ |\ Version\ 4.0
977−\f[]
978−.fi
979−.PP
980−will also have "Version 4.0" in the header.
981−.SH BACKSLASH ESCAPES
982−.PP
983−Except inside a code block or inline code, any punctuation or space
984−character preceded by a backslash will be treated literally, even if it
985−would normally indicate formatting.
986−Thus, for example, if one writes
987−.IP
988−.nf
989−\f[C]
990−*\\*hello\\**
991−\f[]
992−.fi
993−.PP
994−one will get
995−.IP
996−.nf
997−\f[C]
998−<em>*hello*</em>
999−\f[]
1000−.fi
1001−.PP
1002−instead of
1003−.IP
1004−.nf
1005−\f[C]
1006−<strong>hello</strong>
1007−\f[]
1008−.fi
1009−.PP
1010−This rule is easier to remember than standard markdown\[aq]s rule, which
1011−allows only the following characters to be backslash-escaped:
1012−.IP
1013−.nf
1014−\f[C]
1015−\\`*_{}[]()>#+-.!
1016−\f[]
1017−.fi
1018−.PP
1019−(However, if the \f[C]--strict\f[] option is supplied, the standard
1020−markdown rule will be used.)
1021−.PP
1022−A backslash-escaped space is parsed as a nonbreaking space.
1023−It will appear in TeX output as \f[C]~\f[] and in HTML and XML as
1024−\f[C]\\ \f[] or \f[C]\\ \f[].
1025−.PP
1026−A backslash-escaped newline (i.e.
1027−a backslash occurring at the end of a line) is parsed as a hard line
1028−break.
1029−It will appear in TeX output as \f[C]\\\\\f[] and in HTML as
1030−\f[C]<br\ />\f[].
1031−This is a nice alternative to markdown\[aq]s "invisible" way of
1032−indicating hard line breaks using two trailing spaces on a line.
1033−.PP
1034−Backslash escapes do not work in verbatim contexts.
1035−.SH SMART PUNCTUATION
1036−.PP
1037−If the \f[C]--smart\f[] option is specified, pandoc will produce
1038−typographically correct output, converting straight quotes to curly
1039−quotes, \f[C]---\f[] and \f[C]--\f[] to Em-dashes, and \f[C]...\f[] to
1040−ellipses.
1041−Nonbreaking spaces are inserted after certain abbreviations, such as
1042−"Mr."
1043−.PP
1044−Note: if your LaTeX template uses the \f[C]csquotes\f[] package, pandoc
1045−will detect automatically this and use \f[C]\\enquote{...}\f[] for
1046−quoted text.
1047−.SH INLINE FORMATTING
1048−.SS Emphasis
1049−.PP
1050−To \f[I]emphasize\f[] some text, surround it with \f[C]*\f[]s or
1051−\f[C]_\f[], like this:
1052−.IP
1053−.nf
1054−\f[C]
1055−This\ text\ is\ _emphasized\ with\ underscores_,\ and\ this
1056−is\ *emphasized\ with\ asterisks*.
1057−\f[]
1058−.fi
1059−.PP
1060−Double \f[C]*\f[] or \f[C]_\f[] produces \f[B]strong emphasis\f[]:
1061−.IP
1062−.nf
1063−\f[C]
1064−This\ is\ **strong\ emphasis**\ and\ __with\ underscores__.
1065−\f[]
1066−.fi
1067−.PP
1068−A \f[C]*\f[] or \f[C]_\f[] character surrounded by spaces, or
1069−backslash-escaped, will not trigger emphasis:
1070−.IP
1071−.nf
1072−\f[C]
1073−This\ is\ *\ not\ emphasized\ *,\ and\ \\*neither\ is\ this\\*.
1074−\f[]
1075−.fi
1076−.PP
1077−Because \f[C]_\f[] is sometimes used inside words and identifiers,
1078−pandoc does not interpret a \f[C]_\f[] surrounded by alphanumeric
1079−characters as an emphasis marker.
1080−If you want to emphasize just part of a word, use \f[C]*\f[]:
1081−.IP
1082−.nf
1083−\f[C]
1084−feas*ible*,\ not\ feas*able*.
1085−\f[]
1086−.fi
1087−.SS Strikeout
1088−.PP
1089−\f[I]Pandoc extension\f[].
1090−.PP
1091−To strikeout a section of text with a horizontal line, begin and end it
1092−with \f[C]~~\f[].
1093−Thus, for example,
1094−.IP
1095−.nf
1096−\f[C]
1097−This\ ~~is\ deleted\ text.~~
1098−\f[]
1099−.fi
1100−.SS Superscripts and subscripts
1101−.PP
1102−\f[I]Pandoc extension\f[].
1103−.PP
1104−Superscripts may be written by surrounding the superscripted text by
1105−\f[C]^\f[] characters; subscripts may be written by surrounding the
1106−subscripted text by \f[C]~\f[] characters.
1107−Thus, for example,
1108−.IP
1109−.nf
1110−\f[C]
1111−H~2~O\ is\ a\ liquid.\ \ 2^10^\ is\ 1024.
1112−\f[]
1113−.fi
1114−.PP
1115−If the superscripted or subscripted text contains spaces, these spaces
1116−must be escaped with backslashes.
1117−(This is to prevent accidental superscripting and subscripting through
1118−the ordinary use of \f[C]~\f[] and \f[C]^\f[].)
1119− Thus, if you want the letter P with \[aq]a cat\[aq] in subscripts, use
1120−\f[C]P~a\\\ cat~\f[], not \f[C]P~a\ cat~\f[].
1121−.SS Verbatim
1122−.PP
1123−To make a short span of text verbatim, put it inside backticks:
1124−.IP
1125−.nf
1126−\f[C]
1127−What\ is\ the\ difference\ between\ `>>=`\ and\ `>>`?
1128−\f[]
1129−.fi
1130−.PP
1131−If the verbatim text includes a backtick, use double backticks:
1132−.IP
1133−.nf
1134−\f[C]
1135−Here\ is\ a\ literal\ backtick\ ``\ `\ ``.
1136−\f[]
1137−.fi
1138−.PP
1139−(The spaces after the opening backticks and before the closing backticks
1140−will be ignored.)
1141−.PP
1142−The general rule is that a verbatim span starts with a string of
1143−consecutive backticks (optionally followed by a space) and ends with a
1144−string of the same number of backticks (optionally preceded by a space).
1145−.PP
1146−Note that backslash-escapes (and other markdown constructs) do not work
1147−in verbatim contexts:
1148−.IP
1149−.nf
1150−\f[C]
1151−This\ is\ a\ backslash\ followed\ by\ an\ asterisk:\ `\\*`.
1152−\f[]
1153−.fi
1154−.SH MATH
1155−.PP
1156−\f[I]Pandoc extension\f[].
1157−.PP
1158−Anything between two \f[C]$\f[] characters will be treated as TeX math.
1159−The opening \f[C]$\f[] must have a character immediately to its right,
1160−while the closing \f[C]$\f[] must have a character immediately to its
1161−left.
1162−Thus, \f[C]$20,000\ and\ $30,000\f[] won\[aq]t parse as math.
1163−If for some reason you need to enclose text in literal \f[C]$\f[]
1164−characters, backslash-escape them and they won\[aq]t be treated as math
1165−delimiters.
1166−.PP
1167−TeX math will be printed in all output formats.
1168−How it is rendered depends on the output format:
1169−.TP
1170−.B Markdown, reStructuredText, LaTeX, Org-Mode, ConTeXt
1171−It will appear verbatim between \f[C]$\f[] characters.
1172−.RS
1173−.RE
1174−.TP
1175−.B reStructuredText
1176−It will be rendered using an interpreted text role \f[C]:math:\f[], as
1177−described here.
1178−.RS
1179−.RE
1180−.TP
1181−.B Texinfo
1182−It will be rendered inside a \f[C]\@math\f[] command.
1183−.RS
1184−.RE
1185−.TP
1186−.B groff man
1187−It will be rendered verbatim without \f[C]$\f[]\[aq]s.
1188−.RS
1189−.RE
1190−.TP
1191−.B MediaWiki
1192−It will be rendered inside \f[C]<math>\f[] tags.
1193−.RS
1194−.RE
1195−.TP
1196−.B Textile
1197−It will be rendered inside \f[C]<span\ class="math">\f[] tags.
1198−.RS
1199−.RE
1200−.TP
1201−.B RTF, Docbook, OpenDocument, ODT
1202−It will be rendered, if possible, using unicode characters, and will
1203−otherwise appear verbatim.
1204−.RS
1205−.RE
1206−.TP
1207−.B HTML, Slidy, DZSlides, S5, EPUB
1208−The way math is rendered in HTML will depend on the command-line options
1209−selected:
1210−.RS
1211−.IP "1." 3
1212−The default is to render TeX math as far as possible using unicode
1213−characters, as with RTF, Docbook, and OpenDocument output.
1214−Formulas are put inside a \f[C]span\f[] with \f[C]class="math"\f[], so
1215−that they may be styled differently from the surrounding text if needed.
1216−.IP "2." 3
1217−If the \f[C]--latexmathml\f[] option is used, TeX math will be displayed
1218−between $ or $$ characters and put in \f[C]<span>\f[] tags with class
1219−\f[C]LaTeX\f[].
1220−The LaTeXMathML script will be used to render it as formulas.
1221−(This trick does not work in all browsers, but it works in Firefox.
1222−In browsers that do not support LaTeXMathML, TeX math will appear
1223−verbatim between $ characters.)
1224−.IP "3." 3
1225−If the \f[C]--jsmath\f[] option is used, TeX math will be put inside
1226−\f[C]<span>\f[] tags (for inline math) or \f[C]<div>\f[] tags (for
1227−display math) with class \f[C]math\f[].
1228−The jsMath script will be used to render it.
1229−.IP "4." 3
1230−If the \f[C]--mimetex\f[] option is used, the mimeTeX CGI script will be
1231−called to generate images for each TeX formula.
1232−This should work in all browsers.
1233−The \f[C]--mimetex\f[] option takes an optional URL as argument.
1234−If no URL is specified, it will be assumed that the mimeTeX CGI script
1235−is at \f[C]/cgi-bin/mimetex.cgi\f[].
1236−.IP "5." 3
1237−If the \f[C]--gladtex\f[] option is used, TeX formulas will be enclosed
1238−in \f[C]<eq>\f[] tags in the HTML output.
1239−The resulting \f[C]htex\f[] file may then be processed by gladTeX, which
1240−will produce image files for each formula and an \f[C]html\f[] file with
1241−links to these images.
1242−So, the procedure is:
1243−.RS 4
1244−.IP
1245−.nf
1246−\f[C]
1247−pandoc\ -s\ --gladtex\ myfile.txt\ -o\ myfile.htex
1248−gladtex\ -d\ myfile-images\ myfile.htex
1249−#\ produces\ myfile.html\ and\ images\ in\ myfile-images
1250−\f[]
1251−.fi
1252−.RE
1253−.IP "6." 3
1254−If the \f[C]--webtex\f[] option is used, TeX formulas will be converted
1255−to \f[C]<img>\f[] tags that link to an external script that converts
1256−formulas to images.
1257−The formula will be URL-encoded and concatenated with the URL provided.
1258−If no URL is specified, the Google Chart API will be used
1259−(\f[C]http://chart.apis.google.com/chart?cht=tx&chl=\f[]).
1260−.RE
1261−.SH RAW HTML
1262−.PP
1263−Markdown allows you to insert raw HTML anywhere in a document (except
1264−verbatim contexts, where \f[C]<\f[], \f[C]>\f[], and \f[C]&\f[] are
1265−interpreted literally).
1266−.PP
1267−The raw HTML is passed through unchanged in HTML, S5, Slidy, DZSlides,
1268−EPUB, Markdown, and Textile output, and suppressed in other formats.
1269−.PP
1270−\f[I]Pandoc extension\f[].
1271−.PP
1272−Standard markdown allows you to include HTML "blocks": blocks of HTML
1273−between balanced tags that are separated from the surrounding text with
1274−blank lines, and start and end at the left margin.
1275−Within these blocks, everything is interpreted as HTML, not markdown; so
1276−(for example), \f[C]*\f[] does not signify emphasis.
1277−.PP
1278−Pandoc behaves this way when \f[C]--strict\f[] is specified; but by
1279−default, pandoc interprets material between HTML block tags as markdown.
1280−Thus, for example, Pandoc will turn
1281−.IP
1282−.nf
1283−\f[C]
1284−<table>
1285−\ <tr>
1286−\ \ <td>*one*</td>
1287−\ \ <td>[a\ link](http://google.com)</td>
1288−\ </tr>
1289−</table>
1290−\f[]
1291−.fi
1292−.PP
1293−into
1294−.IP
1295−.nf
1296−\f[C]
1297−<table>
1298−\ <tr>
1299−\ \ <td><em>one</em></td>
1300−\ \ <td><a\ href="http://google.com">a\ link</a></td>
1301−\ </tr>
1302−</table>
1303−\f[]
1304−.fi
1305−.PP
1306−whereas \f[C]Markdown.pl\f[] will preserve it as is.
1307−.PP
1308−There is one exception to this rule: text between \f[C]<script>\f[] and
1309−\f[C]<style>\f[] tags is not interpreted as markdown.
1310−.PP
1311−This departure from standard markdown should make it easier to mix
1312−markdown with HTML block elements.
1313−For example, one can surround a block of markdown text with
1314−\f[C]<div>\f[] tags without preventing it from being interpreted as
1315−markdown.
1316−.SH RAW TEX
1317−.PP
1318−\f[I]Pandoc extension\f[].
1319−.PP
1320−In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be
1321−included in a document.
1322−Inline TeX commands will be preserved and passed unchanged to the LaTeX
1323−and ConTeXt writers.
1324−Thus, for example, you can use LaTeX to include BibTeX citations:
1325−.IP
1326−.nf
1327−\f[C]
1328−This\ result\ was\ proved\ in\ \\cite{jones.1967}.
1329−\f[]
1330−.fi
1331−.PP
1332−Note that in LaTeX environments, like
1333−.IP
1334−.nf
1335−\f[C]
1336−\\begin{tabular}{|l|l|}\\hline
1337−Age\ &\ Frequency\ \\\\\ \\hline
1338−18--25\ \ &\ 15\ \\\\
1339−26--35\ \ &\ 33\ \\\\\
1340−36--45\ \ &\ 22\ \\\\\ \\hline
1341−\\end{tabular}
1342−\f[]
1343−.fi
1344−.PP
1345−the material between the begin and end tags will be interpreted as raw
1346−LaTeX, not as markdown.
1347−.PP
1348−Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
1349−and ConTeXt.
1350−.SS Macros
1351−.PP
1352−For output formats other than LaTeX, pandoc will parse LaTeX
1353−\f[C]\\newcommand\f[] and \f[C]\\renewcommand\f[] definitions and apply
1354−the resulting macros to all LaTeX math.
1355−So, for example, the following will work in all output formats, not just
1356−LaTeX:
1357−.IP
1358−.nf
1359−\f[C]
1360−\\newcommand{\\tuple}[1]{\\langle\ #1\ \\rangle}
1361−
1362−$\\tuple{a,\ b,\ c}$
1363−\f[]
1364−.fi
1365−.PP
1366−In LaTeX output, the \f[C]\\newcommand\f[] definition will simply be
1367−passed unchanged to the output.
1368−.SH LINKS
1369−.PP
1370−Markdown allows links to be specified in several ways.
1371−.SS Automatic links
1372−.PP
1373−If you enclose a URL or email address in pointy brackets, it will become
1374−a link:
1375−.IP
1376−.nf
1377−\f[C]
1378−<http://google.com>
1379−<sam\@green.eggs.ham>
1380−\f[]
1381−.fi
1382−.SS Inline links
1383−.PP
1384−An inline link consists of the link text in square brackets, followed by
1385−the URL in parentheses.
1386−(Optionally, the URL can be followed by a link title, in quotes.)
1387−.IP
1388−.nf
1389−\f[C]
1390−This\ is\ an\ [inline\ link](/url),\ and\ here\[aq]s\ [one\ with
1391−a\ title](http://fsf.org\ "click\ here\ for\ a\ good\ time!").
1392−\f[]
1393−.fi
1394−.PP
1395−There can be no space between the bracketed part and the parenthesized
1396−part.
1397−The link text can contain formatting (such as emphasis), but the title
1398−cannot.
1399−.SS Reference links
1400−.PP
1401−An \f[I]explicit\f[] reference link has two parts, the link itself and
1402−the link definition, which may occur elsewhere in the document (either
1403−before or after the link).
1404−.PP
1405−The link consists of link text in square brackets, followed by a label
1406−in square brackets.
1407−(There can be space between the two.)
1408− The link definition must begin at the left margin or indented no more
1409−than three spaces.
1410−It consists of the bracketed label, followed by a colon and a space,
1411−followed by the URL, and optionally (after a space) a link title either
1412−in quotes or in parentheses.
1413−.PP
1414−Here are some examples:
1415−.IP
1416−.nf
1417−\f[C]
1418−[my\ label\ 1]:\ /foo/bar.html\ \ "My\ title,\ optional"
1419−[my\ label\ 2]:\ /foo
1420−[my\ label\ 3]:\ http://fsf.org\ (The\ free\ software\ foundation)
1421−[my\ label\ 4]:\ /bar#special\ \ \[aq]A\ title\ in\ single\ quotes\[aq]
1422−\f[]
1423−.fi
1424−.PP
1425−The URL may optionally be surrounded by angle brackets:
1426−.IP
1427−.nf
1428−\f[C]
1429−[my\ label\ 5]:\ <http://foo.bar.baz>
1430−\f[]
1431−.fi
1432−.PP
1433−The title may go on the next line:
1434−.IP
1435−.nf
1436−\f[C]
1437−[my\ label\ 3]:\ http://fsf.org
1438−\ \ "The\ free\ software\ foundation"
1439−\f[]
1440−.fi
1441−.PP
1442−Note that link labels are not case sensitive.
1443−So, this will work:
1444−.IP
1445−.nf
1446−\f[C]
1447−Here\ is\ [my\ link][FOO]
1448−
1449−[Foo]:\ /bar/baz
1450−\f[]
1451−.fi
1452−.PP
1453−In an \f[I]implicit\f[] reference link, the second pair of brackets is
1454−empty, or omitted entirely:
1455−.IP
1456−.nf
1457−\f[C]
1458−See\ [my\ website][],\ or\ [my\ website].
1459−
1460−[my\ website]:\ http://foo.bar.baz
1461−\f[]
1462−.fi
1463−.SH IMAGES
1464−.PP
1465−A link immediately preceded by a \f[C]!\f[] will be treated as an image.
1466−The link text will be used as the image\[aq]s alt text:
1467−.IP
1468−.nf
1469−\f[C]
1470−
1471−
1472−![movie\ reel]
1473−
1474−[movie\ reel]:\ movie.gif
1475−\f[]
1476−.fi
1477−.SS Pictures with captions
1478−.PP
1479−\f[I]Pandoc extension\f[].
1480−.PP
1481−An image occurring by itself in a paragraph will be rendered as a figure
1482−with a caption.[4] (In LaTeX, a figure environment will be used; in
1483−HTML, the image will be placed in a \f[C]div\f[] with class
1484−\f[C]figure\f[], together with a caption in a \f[C]p\f[] with class
1485−\f[C]caption\f[].)
1486− The image\[aq]s alt text will be used as the caption.
1487−.IP
1488−.nf
1489−\f[C]
1490−
1491−\f[]
1492−.fi
1493−.PP
1494−If you just want a regular inline image, just make sure it is not the
1495−only thing in the paragraph.
1496−One way to do this is to insert a nonbreaking space after the image:
1497−.IP
1498−.nf
1499−\f[C]
1500−![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\\
1501−\f[]
1502−.fi
1503−.SH FOOTNOTES
1504−.PP
1505−\f[I]Pandoc extension\f[].
1506−.PP
1507−Pandoc\[aq]s markdown allows footnotes, using the following syntax:
1508−.IP
1509−.nf
1510−\f[C]
1511−Here\ is\ a\ footnote\ reference,[^1]\ and\ another.[^longnote]
1512−
1513−[^1]:\ Here\ is\ the\ footnote.
1514−
1515−[^longnote]:\ Here\[aq]s\ one\ with\ multiple\ blocks.
1516−
1517−\ \ \ \ Subsequent\ paragraphs\ are\ indented\ to\ show\ that\ they\
1518−belong\ to\ the\ previous\ footnote.
1519−
1520−\ \ \ \ \ \ \ \ {\ some.code\ }
1521−
1522−\ \ \ \ The\ whole\ paragraph\ can\ be\ indented,\ or\ just\ the\ first
1523−\ \ \ \ line.\ \ In\ this\ way,\ multi-paragraph\ footnotes\ work\ like
1524−\ \ \ \ multi-paragraph\ list\ items.
1525−
1526−This\ paragraph\ won\[aq]t\ be\ part\ of\ the\ note,\ because\ it
1527−isn\[aq]t\ indented.
1528−\f[]
1529−.fi
1530−.PP
1531−The identifiers in footnote references may not contain spaces, tabs, or
1532−newlines.
1533−These identifiers are used only to correlate the footnote reference with
1534−the note itself; in the output, footnotes will be numbered sequentially.
1535−.PP
1536−The footnotes themselves need not be placed at the end of the document.
1537−They may appear anywhere except inside other block elements (lists,
1538−block quotes, tables, etc.)
1539−\&.
1540−.PP
1541−Inline footnotes are also allowed (though, unlike regular notes, they
1542−cannot contain multiple paragraphs).
1543−The syntax is as follows:
1544−.IP
1545−.nf
1546−\f[C]
1547−Here\ is\ an\ inline\ note.^[Inlines\ notes\ are\ easier\ to\ write,\ since
1548−you\ don\[aq]t\ have\ to\ pick\ an\ identifier\ and\ move\ down\ to\ type\ the
1549−note.]
1550−\f[]
1551−.fi
1552−.PP
1553−Inline and regular footnotes may be mixed freely.
1554−.SH CITATIONS
1555−.PP
1556−\f[I]Pandoc extension\f[].
1557−.PP
1558−Pandoc can automatically generate citations and a bibliography in a
1559−number of styles (using Andrea Rossato\[aq]s \f[C]hs-citeproc\f[]).
1560−In order to use this feature, you will need a bibliographic database in
1561−one of the following formats:
1562−.PP
1563−.TS
1564−tab(@);
1565−l l.
1566−T{
1567−Format
1568−T}@T{
1569−File extension
1570−T}
1571−_
1572−T{
1573−MODS
1574−T}@T{
1575−\&.mods
1576−T}
1577−T{
1578−BibTeX/BibLaTeX
1579−T}@T{
1580−\&.bib
1581−T}
1582−T{
1583−RIS
1584−T}@T{
1585−\&.ris
1586−T}
1587−T{
1588−EndNote
1589−T}@T{
1590−\&.enl
1591−T}
1592−T{
1593−EndNote XML
1594−T}@T{
1595−\&.xml
1596−T}
1597−T{
1598−ISI
1599−T}@T{
1600−\&.wos
1601−T}
1602−T{
1603−MEDLINE
1604−T}@T{
1605−\&.medline
1606−T}
1607−T{
1608−Copac
1609−T}@T{
1610−\&.copac
1611−T}
1612−T{
1613−JSON citeproc
1614−T}@T{
1615−\&.json
1616−T}
1617−.TE
1618−.PP
1619−You will need to specify the bibliography file using the
1620−\f[C]--bibliography\f[] command-line option (which may be repeated if
1621−you have several bibliographies).
1622−.PP
1623−By default, pandoc will use a Chicago author-date format for citations
1624−and references.
1625−To use another style, you will need to use the \f[C]--csl\f[] option to
1626−specify a CSL 1.0 style file.
1627−A primer on creating and modifying CSL styles can be found at
1628−\f[C]http://citationstyles.org/downloads/primer.html\f[].
1629−A repository of CSL styles can be found at
1630−\f[C]https://github.com/citation-style-language/styles\f[].
1631−See also \f[C]http://zotero.org/styles\f[] for easy browsing.
1632−.PP
1633−Citations go inside square brackets and are separated by semicolons.
1634−Each citation must have a key, composed of \[aq]\@\[aq] + the citation
1635−identifier from the database, and may optionally have a prefix, a
1636−locator, and a suffix.
1637−Here are some examples:
1638−.IP
1639−.nf
1640−\f[C]
1641−Blah\ blah\ [see\ \@doe99,\ pp.\ 33-35;\ also\ \@smith04,\ ch.\ 1].
1642−
1643−Blah\ blah\ [\@doe99,\ pp.\ 33-35,\ 38-39\ and\ *passim*].
1644−
1645−Blah\ blah\ [\@smith04;\ \@doe99].
1646−\f[]
1647−.fi
1648−.PP
1649−A minus sign (\f[C]-\f[]) before the \f[C]\@\f[] will suppress mention
1650−of the author in the citation.
1651−This can be useful when the author is already mentioned in the text:
1652−.IP
1653−.nf
1654−\f[C]
1655−Smith\ says\ blah\ [-\@smith04].
1656−\f[]
1657−.fi
1658−.PP
1659−You can also write an in-text citation, as follows:
1660−.IP
1661−.nf
1662−\f[C]
1663−\@smith04\ says\ blah.
1664−
1665−\@smith04\ [p.\ 33]\ says\ blah.
1666−\f[]
1667−.fi
1668−.PP
1669−If the style calls for a list of works cited, it will be placed at the
1670−end of the document.
1671−Normally, you will want to end your document with an appropriate header:
1672−.IP
1673−.nf
1674−\f[C]
1675−last\ paragraph...
1676−
1677−#\ References
1678−\f[]
1679−.fi
1680−.PP
1681−The bibliography will be inserted after this header.
1682−.SH NOTES
1683−.SS [1]
1684−.PP
1685−The point of this rule is to ensure that normal paragraphs starting with
1686−people\[aq]s initials, like
1687−.IP
1688−.nf
1689−\f[C]
1690−B.\ Russell\ was\ an\ English\ philosopher.
1691−\f[]
1692−.fi
1693−.PP
1694−do not get treated as list items.
1695−.PP
1696−This rule will not prevent
1697−.IP
1698−.nf
1699−\f[C]
1700−(C)\ 2007\ Joe\ Smith
1701−\f[]
1702−.fi
1703−.PP
1704−from being interpreted as a list item.
1705−In this case, a backslash escape can be used:
1706−.IP
1707−.nf
1708−\f[C]
1709−(C\\)\ 2007\ Joe\ Smith
1710−\f[]
1711−.fi
1712−.SS [2]
1713−.PP
1714−I have also been influenced by the suggestions of David Wheeler.
1715−.SS [3]
1716−.PP
1717−This scheme is due to Michel Fortin, who proposed it on the Markdown
1718−discussion list.
1719−.SS [4]
1720−.PP
1721−This feature is not yet implemented for RTF, OpenDocument, or ODT.
1722−In those formats, you\[aq]ll just get an image in a paragraph by itself,
1723−with no caption.
1724−.SH SEE ALSO
1725−.PP
1726−\f[C]pandoc\f[] (1).