@@ -1,1726 +0,0 @@
2−.TH PANDOC_MARKDOWN 5 "July 30, 2011" "Pandoc"
4−pandoc_markdown - markdown syntax for pandoc(1)
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
11−Except where noted, these differences can be suppressed by specifying
12−the \f[C]--strict\f[] command-line option.
15−Markdown is designed to be easy to write, and, even more importantly,
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.
25−This principle has guided pandoc\[aq]s decisions in finding syntax for
26−tables, footnotes, and other extensions.
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.
37−A paragraph is one or more lines of text followed by one or more blank
39−Newlines are treated as spaces, so you can reflow your paragraphs as you
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.
45−There are two kinds of headers, Setext and atx.
46−.SS Setext-style headers
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
62−The header text can contain inline formatting, such as emphasis (see
63−Inline formatting, below).
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
73−##\ A\ level-two\ header
75−###\ A\ level-three\ header\ ###
79−As with setext-style headers, the header text can contain formatting:
83−#\ A\ level-one\ header\ with\ a\ [link](/url)\ and\ *emphasis*
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
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:
97−I\ like\ several\ of\ their\ flavors\ of\ ice\ cream:
98−#22,\ for\ example,\ and\ #5.
101−.SS Header identifiers in HTML
103−\f[I]Pandoc extension\f[].
105−Each header element in pandoc\[aq]s HTML output is given a unique
107−This identifier is based on the text of the header.
108−To derive the identifier from the header text,
110−Remove all formatting, links, etc.
112−Remove all punctuation, except underscores, hyphens, and periods.
114−Replace all spaces and newlines with hyphens.
116−Convert all alphabetic characters to lowercase.
118−Remove everything up to the first letter (identifiers may not begin with
119−a number or punctuation mark).
121−If nothing is left after this, use the identifier \f[C]section\f[].
135−Header identifiers in HTML
137−\f[C]header-identifiers-in-html\f[]
140−\f[I]Dogs\f[]?--in \f[I]my\f[] house?
142−\f[C]dogs--in-my-house\f[]
147−\f[C]html-s5-or-rtf\f[]
153−\f[C]applications\f[]
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.
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
173−A link to this section, for example, might look like this:
177−See\ the\ section\ on
178−[header\ identifiers](#header-identifiers-in-html).
182−Note, however, that this method of providing links to sections works
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
190−This allows entire sections to be manipulated using javascript or
191−treated differently in CSS.
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.)
203−>\ This\ is\ a\ block\ quote.\ This
204−>\ paragraph\ has\ two\ lines.
206−>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
211−A "lazy" form, which requires the \f[C]>\f[] character only on the first
212−line of each block, is also allowed:
216−>\ This\ is\ a\ block\ quote.\ This
217−paragraph\ has\ two\ lines.
219−>\ 1.\ This\ is\ a\ list\ inside\ a\ block\ quote.
224−Among the block elements that can be contained in a block quote are
226−That is, block quotes can be nested:
230−>\ This\ is\ a\ block\ quote.
232−>\ >\ A\ block\ quote\ within\ a\ block\ quote.
236−Standard markdown syntax does not require a blank line before a block
238−Pandoc does require this (except, of course, at the beginning of the
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:
248−>\ This\ is\ a\ block\ quote.
252−.SH VERBATIM (CODE) BLOCKS
253−.SS Indented code blocks
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.
262−\ \ \ \ if\ (a\ >\ 3)\ {
263−\ \ \ \ \ \ moveShip(5\ *\ gravity,\ DOWN);
268−The initial (four space or one tab) indentation is not considered part
269−of the verbatim text, and is removed in the output.
271−Note: blank lines in the verbatim text need not begin with four spaces.
272−.SS Delimited code blocks
274−\f[I]Pandoc extension\f[].
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:
287−\ \ moveShip(5\ *\ gravity,\ DOWN);
293−Like regular code blocks, delimited code blocks must be separated from
294−surrounding text by blank lines.
296−If the code itself contains a row of tildes, just use a longer row of
297−tildes at the start and end:
303−code\ including\ tildes
309−Optionally, you may specify the language of the code block using this
314−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\ {.haskell\ .numberLines}
315−qsort\ []\ \ \ \ \ =\ []
316−qsort\ (x:xs)\ =\ qsort\ (filter\ (<\ x)\ xs)\ ++\ [x]\ ++
317−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ qsort\ (filter\ (>=\ x)\ xs)\
318−~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
322−Some output formats can use this information to do syntax highlighting.
323−Currently, the only output format that uses this information is HTML.
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[].)
329−If pandoc has not been compiled with syntax highlighting support, the
330−code block above will appear as follows:
334−<pre\ class="haskell">
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
347−Here is a simple example:
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:
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.
375−List items look best if subsequent lines are flush with the first line
380−*\ here\ is\ my\ first
386−But markdown also allows a "lazy" format:
390−*\ here\ is\ my\ first
395−.SS The four-space rule
397−A list item may contain multiple paragraphs and other block-level
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
406−\ \ *\ First\ paragraph.
410−\ \ *\ Second\ paragraph.\ With\ a\ code\ block,\ which\ must\ be\ indented
411−\ \ \ \ eight\ spaces:
413−\ \ \ \ \ \ \ \ {\ code\ }
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:
425−\ \ \ \ \ \ \ \ -\ macintosh
426−\ \ \ \ \ \ \ \ -\ red\ delicious
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.
442−+\ A\ lazy,\ lazy,\ list
445−+\ Another\ one;\ this\ looks
448−\ \ \ \ Second\ paragraph\ of\ second
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.
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.
466−Ordered lists work just like bulleted lists, except that the items begin
467−with enumerators rather than bullets.
469−In standard markdown, enumerators are decimal numbers followed by a
471−The numbers themselves are ignored, so there is no difference between
492−\f[I]Pandoc extension\f[].
494−Unlike standard markdown, Pandoc allows ordered list items to be marked
495−with uppercase and lowercase letters and roman numerals, in addition to
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
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
506−Thus, the following yields a list with numbers followed by a single
507−parenthesis, starting with 9, and a sublist with lowercase roman
515−\ \ \ \ \ \ \ i.\ subone
516−\ \ \ \ \ \ ii.\ subtwo
517−\ \ \ \ \ iii.\ subthree
521−Note that Pandoc pays attention only to the \f[I]starting\f[] marker in
523−So, the following yields a list numbered sequentially starting from 2:
534−If default list markers are desired, use \f[C]#.\f[]:
545−\f[I]Pandoc extension\f[].
547−Pandoc supports definition lists, using a syntax inspired by PHP
548−Markdown Extra and reStructuredText:[2]
556−Term\ 2\ with\ *inline\ markup*
560−\ \ \ \ \ \ \ \ {\ some\ code,\ part\ of\ Definition\ 2\ }
562−\ \ \ \ Third\ paragraph\ of\ definition\ 2.
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
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.
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
586−\ \ ~\ Definition\ 2a
587−\ \ ~\ Definition\ 2b
590−.SS Numbered example lists
592−\f[I]Pandoc extension\f[].
594−The special list marker \f[C]\@\f[] can be used for sequentially
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.
604−(\@)\ \ My\ first\ example\ will\ be\ numbered\ (1).
605−(\@)\ \ My\ second\ example\ will\ be\ numbered\ (2).
607−Explanation\ of\ examples.
609−(\@)\ \ My\ third\ example\ will\ be\ numbered\ (3).
613−Numbered examples can be labeled and referred to elsewhere in the
618−(\@good)\ \ This\ is\ a\ good\ example.
620−As\ (\@good)\ illustrates,\ ...
624−The label can be any string of alphanumeric characters, underscores, or
626−.SS Compact and loose lists
628−Pandoc behaves differently from \f[C]Markdown.pl\f[] on some "edge
629−cases" involving lists.
630−Consider this source:
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
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[].)
660−What if you want to put an indented code block after a list?
667−\ \ \ \ {\ my\ code\ block\ }
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
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
684−<!--\ end\ of\ list\ -->
686−\ \ \ \ {\ my\ code\ block\ }
690−You can use the same trick if you want two consecutive lists instead of
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
721−\f[I]Pandoc extension\f[].
723−Three kinds of tables may be used.
724−All three kinds presuppose the use of a fixed-width font, such as
727−\f[B]Simple tables\f[] look like this:
731−\ \ Right\ \ \ \ \ Left\ \ \ \ \ Center\ \ \ \ \ Default
732−-------\ \ \ \ \ ------\ ----------\ \ \ -------
733−\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ 12
734−\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ 123
735−\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ 1
737−Table:\ \ Demonstration\ of\ simple\ table\ syntax.
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]
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.
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.
751−If the dashed line extends beyond the header text on both sides, the
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).
757−The table must end with a blank line, or a line of dashes followed by a
759−A caption may optionally be provided (as illustrated in the example
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.
765−The column headers may be omitted, provided a dashed line is used to end
771−-------\ \ \ \ \ ------\ ----------\ \ \ -------
772−\ \ \ \ \ 12\ \ \ \ \ 12\ \ \ \ \ \ \ \ 12\ \ \ \ \ \ \ \ \ \ \ \ \ 12
773−\ \ \ \ 123\ \ \ \ \ 123\ \ \ \ \ \ \ 123\ \ \ \ \ \ \ \ \ \ \ 123
774−\ \ \ \ \ \ 1\ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ 1\ \ \ \ \ \ \ \ \ \ \ \ \ \ 1
775−-------\ \ \ \ \ ------\ ----------\ \ \ -------
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.
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
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.
798−\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note
799−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
800−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
801−-------------------------------------------------------------
803−Table:\ Here\[aq]s\ the\ caption.\ It,\ too,\ may\ span
808−These work like simple tables, but with the following differences:
810−They must begin with a row of dashes, before the header text (unless the
811−headers are omitted).
813−They must end with a row of dashes, then a blank line.
815−The rows must be separated by blank lines.
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
820−So, if you find that one of the columns is too narrow in the output, try
821−widening it in the markdown source.
823−Headers may be omitted in multiline tables as well as simple tables:
827−-----------\ -------\ ---------------\ -------------------------
828−\ \ \ First\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 12.0\ Example\ of\ a\ row\ that
829−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ spans\ multiple\ lines.
831−\ \ Second\ \ \ \ row\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ 5.0\ Here\[aq]s\ another\ one.\ Note
832−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ the\ blank\ line\ between
833−\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ rows.
834−-------------------------------------------------------------
836−:\ Here\[aq]s\ a\ multiline\ table\ without\ headers.
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.
844−\f[B]Grid tables\f[] look like this:
848−:\ Sample\ grid\ table.
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−+---------------+---------------+--------------------+
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.)
867−Alignments are not supported, nor are cells that span multiple columns
869−Grid tables can be created easily using Emacs table mode.
872−\f[I]Pandoc extension\f[].
874−If the file begins with a title block
879−%\ author(s)\ (separated\ by\ semicolons)
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
887− The block may contain just a title, a title and an author, or all three
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:
903−The title may occupy multiple lines, but continuation lines must begin
904−with leading space, thus:
909−\ \ on\ multiple\ lines
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:
922−%\ Author\ One;\ Author\ Two
929−The date must fit on one line.
931−All three metadata fields may contain standard inline formatting
932−(italics, links, footnotes, etc.)
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
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.
964−will yield a man page with the title \f[C]PANDOC\f[] and section 1.
968−%\ PANDOC(1)\ Pandoc\ User\ Manuals
972−will also have "Pandoc User Manuals" in the footer.
976−%\ PANDOC(1)\ Pandoc\ User\ Manuals\ |\ Version\ 4.0
980−will also have "Version 4.0" in the header.
981−.SH BACKSLASH ESCAPES
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
1006−<strong>hello</strong>
1010−This rule is easier to remember than standard markdown\[aq]s rule, which
1011−allows only the following characters to be backslash-escaped:
1019−(However, if the \f[C]--strict\f[] option is supplied, the standard
1020−markdown rule will be used.)
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[].
1026−A backslash-escaped newline (i.e.
1027−a backslash occurring at the end of a line) is parsed as a hard line
1029−It will appear in TeX output as \f[C]\\\\\f[] and in HTML as
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.
1034−Backslash escapes do not work in verbatim contexts.
1035−.SH SMART PUNCTUATION
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
1041−Nonbreaking spaces are inserted after certain abbreviations, such as
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
1047−.SH INLINE FORMATTING
1050−To \f[I]emphasize\f[] some text, surround it with \f[C]*\f[]s or
1051−\f[C]_\f[], like this:
1055−This\ text\ is\ _emphasized\ with\ underscores_,\ and\ this
1056−is\ *emphasized\ with\ asterisks*.
1060−Double \f[C]*\f[] or \f[C]_\f[] produces \f[B]strong emphasis\f[]:
1064−This\ is\ **strong\ emphasis**\ and\ __with\ underscores__.
1068−A \f[C]*\f[] or \f[C]_\f[] character surrounded by spaces, or
1069−backslash-escaped, will not trigger emphasis:
1073−This\ is\ *\ not\ emphasized\ *,\ and\ \\*neither\ is\ this\\*.
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[]:
1084−feas*ible*,\ not\ feas*able*.
1089−\f[I]Pandoc extension\f[].
1091−To strikeout a section of text with a horizontal line, begin and end it
1097−This\ ~~is\ deleted\ text.~~
1100−.SS Superscripts and subscripts
1102−\f[I]Pandoc extension\f[].
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.
1111−H~2~O\ is\ a\ liquid.\ \ 2^10^\ is\ 1024.
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[].
1123−To make a short span of text verbatim, put it inside backticks:
1127−What\ is\ the\ difference\ between\ `>>=`\ and\ `>>`?
1131−If the verbatim text includes a backtick, use double backticks:
1135−Here\ is\ a\ literal\ backtick\ ``\ `\ ``.
1139−(The spaces after the opening backticks and before the closing backticks
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).
1146−Note that backslash-escapes (and other markdown constructs) do not work
1147−in verbatim contexts:
1151−This\ is\ a\ backslash\ followed\ by\ an\ asterisk:\ `\\*`.
1156−\f[I]Pandoc extension\f[].
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
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
1167−TeX math will be printed in all output formats.
1168−How it is rendered depends on the output format:
1170−.B Markdown, reStructuredText, LaTeX, Org-Mode, ConTeXt
1171−It will appear verbatim between \f[C]$\f[] characters.
1176−It will be rendered using an interpreted text role \f[C]:math:\f[], as
1182−It will be rendered inside a \f[C]\@math\f[] command.
1187−It will be rendered verbatim without \f[C]$\f[]\[aq]s.
1192−It will be rendered inside \f[C]<math>\f[] tags.
1197−It will be rendered inside \f[C]<span\ class="math">\f[] tags.
1201−.B RTF, Docbook, OpenDocument, ODT
1202−It will be rendered, if possible, using unicode characters, and will
1203−otherwise appear verbatim.
1207−.B HTML, Slidy, DZSlides, S5, EPUB
1208−The way math is rendered in HTML will depend on the command-line options
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.
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
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.)
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.
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[].
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:
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
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
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[]).
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).
1267−The raw HTML is passed through unchanged in HTML, S5, Slidy, DZSlides,
1268−EPUB, Markdown, and Textile output, and suppressed in other formats.
1270−\f[I]Pandoc extension\f[].
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.
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
1287−\ \ <td>[a\ link](http://google.com)</td>
1299−\ \ <td><em>one</em></td>
1300−\ \ <td><a\ href="http://google.com">a\ link</a></td>
1306−whereas \f[C]Markdown.pl\f[] will preserve it as is.
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.
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
1318−\f[I]Pandoc extension\f[].
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:
1328−This\ result\ was\ proved\ in\ \\cite{jones.1967}.
1332−Note that in LaTeX environments, like
1336−\\begin{tabular}{|l|l|}\\hline
1337−Age\ &\ Frequency\ \\\\\ \\hline
1338−18--25\ \ &\ 15\ \\\\
1339−26--35\ \ &\ 33\ \\\\\
1340−36--45\ \ &\ 22\ \\\\\ \\hline
1345−the material between the begin and end tags will be interpreted as raw
1346−LaTeX, not as markdown.
1348−Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
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
1360−\\newcommand{\\tuple}[1]{\\langle\ #1\ \\rangle}
1362−$\\tuple{a,\ b,\ c}$
1366−In LaTeX output, the \f[C]\\newcommand\f[] definition will simply be
1367−passed unchanged to the output.
1370−Markdown allows links to be specified in several ways.
1373−If you enclose a URL or email address in pointy brackets, it will become
1379−<sam\@green.eggs.ham>
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.)
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!").
1395−There can be no space between the bracketed part and the parenthesized
1397−The link text can contain formatting (such as emphasis), but the title
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).
1405−The link consists of link text in square brackets, followed by a label
1407−(There can be space between the two.)
1408− The link definition must begin at the left margin or indented no more
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.
1414−Here are some examples:
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]
1425−The URL may optionally be surrounded by angle brackets:
1429−[my\ label\ 5]:\ <http://foo.bar.baz>
1433−The title may go on the next line:
1437−[my\ label\ 3]:\ http://fsf.org
1438−\ \ "The\ free\ software\ foundation"
1442−Note that link labels are not case sensitive.
1447−Here\ is\ [my\ link][FOO]
1453−In an \f[I]implicit\f[] reference link, the second pair of brackets is
1454−empty, or omitted entirely:
1458−See\ [my\ website][],\ or\ [my\ website].
1460−[my\ website]:\ http://foo.bar.baz
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:
1470−
1474−[movie\ reel]:\ movie.gif
1477−.SS Pictures with captions
1479−\f[I]Pandoc extension\f[].
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
1486− The image\[aq]s alt text will be used as the caption.
1490−
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:
1500−![This\ image\ won\[aq]t\ be\ a\ figure](/url/of/image.png)\\\
1505−\f[I]Pandoc extension\f[].
1507−Pandoc\[aq]s markdown allows footnotes, using the following syntax:
1511−Here\ is\ a\ footnote\ reference,[^1]\ and\ another.[^longnote]
1513−[^1]:\ Here\ is\ the\ footnote.
1515−[^longnote]:\ Here\[aq]s\ one\ with\ multiple\ blocks.
1517−\ \ \ \ Subsequent\ paragraphs\ are\ indented\ to\ show\ that\ they\
1518−belong\ to\ the\ previous\ footnote.
1520−\ \ \ \ \ \ \ \ {\ some.code\ }
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.
1526−This\ paragraph\ won\[aq]t\ be\ part\ of\ the\ note,\ because\ it
1527−isn\[aq]t\ indented.
1531−The identifiers in footnote references may not contain spaces, tabs, or
1533−These identifiers are used only to correlate the footnote reference with
1534−the note itself; in the output, footnotes will be numbered sequentially.
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.)
1541−Inline footnotes are also allowed (though, unlike regular notes, they
1542−cannot contain multiple paragraphs).
1543−The syntax is as follows:
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
1553−Inline and regular footnotes may be mixed freely.
1556−\f[I]Pandoc extension\f[].
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:
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).
1623−By default, pandoc will use a Chicago author-date format for citations
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.
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:
1641−Blah\ blah\ [see\ \@doe99,\ pp.\ 33-35;\ also\ \@smith04,\ ch.\ 1].
1643−Blah\ blah\ [\@doe99,\ pp.\ 33-35,\ 38-39\ and\ *passim*].
1645−Blah\ blah\ [\@smith04;\ \@doe99].
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:
1655−Smith\ says\ blah\ [-\@smith04].
1659−You can also write an in-text citation, as follows:
1663−\@smith04\ says\ blah.
1665−\@smith04\ [p.\ 33]\ says\ blah.
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:
1681−The bibliography will be inserted after this header.
1685−The point of this rule is to ensure that normal paragraphs starting with
1686−people\[aq]s initials, like
1690−B.\ Russell\ was\ an\ English\ philosopher.
1694−do not get treated as list items.
1696−This rule will not prevent
1700−(C)\ 2007\ Joe\ Smith
1704−from being interpreted as a list item.
1705−In this case, a backslash escape can be used:
1709−(C\\)\ 2007\ Joe\ Smith
1714−I have also been influenced by the suggestions of David Wheeler.
1717−This scheme is due to Michel Fortin, who proposed it on the Markdown
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,
1726−\f[C]pandoc\f[] (1).