1PANDOC_MARKDOWN(5) File Formats Manual PANDOC_MARKDOWN(5)
2
6 pandoc_markdown - markdown syntax for pandoc(1)
7
9 Pandoc understands an extended and slightly revised version of John
10 Gruber's markdown syntax. This document explains the syntax, noting
11 differences from standard markdown. Except where noted, these differ‐
12 ences can be suppressed by specifying the --strict command-line option.
13
15 Markdown is designed to be easy to write, and, even more importantly,
16 easy to read:
17 A Markdown-formatted document should be publishable as-is, as
19 plain text, without looking like it's been marked up with tags
20 or formatting instructions. -- John Gruber
21 This principle has guided pandoc's decisions in finding syntax for
23 tables, footnotes, and other extensions.
24 There is, however, one respect in which pandoc's aims are different
26 from the original aims of markdown. Whereas markdown was originally
27 designed with HTML generation in mind, pandoc is designed for multiple
28 output formats. Thus, while pandoc allows the embedding of raw HTML,
29 it discourages it, and provides other, non-HTMLish ways of representing
30 important document elements like definition lists, tables, mathematics,
31 and footnotes.
32
34 A paragraph is one or more lines of text followed by one or more blank
35 line. Newlines are treated as spaces, so you can reflow your para‐
36 graphs as you like. If you need a hard line break, put two or more
37 spaces at the end of a line, or or type a backslash followed by a new‐
38 line.
39
41 There are two kinds of headers, Setext and atx.
42 Setext-style headers
44 A setext-style header is a line of text "underlined" with a row of =
45 signs (for a level one header) of - signs (for a level two header):
46 A level-one header
48 ==================
49 A level-two header
51 ------------------
52 The header text can contain inline formatting, such as emphasis (see
54 Inline formatting, below).
55 Atx-style headers
57 An Atx-style header consists of one to six # signs and a line of text,
58 optionally followed by any number of # signs. The number of # signs at
59 the beginning of the line is the header level:
60 ## A level-two header
62 ### A level-three header ###
64 As with setext-style headers, the header text can contain formatting:
66 # A level-one header with a [link](/url) and *emphasis*
68 Standard markdown syntax does not require a blank line before a header.
70 Pandoc does require this (except, of course, at the beginning of the
71 document). The reason for the requirement is that it is all too easy
72 for a # to end up at the beginning of a line by accident (perhaps
73 through line wrapping). Consider, for example:
74 I like several of their flavors of ice cream:
76 #22, for example, and #5.
77 Header identifiers in HTML
79 Pandoc extension.
80 Each header element in pandoc's HTML output is given a unique identi‐
82 fier. This identifier is based on the text of the header. To derive
83 the identifier from the header text,
84 · Remove all formatting, links, etc.
86 · Remove all punctuation, except underscores, hyphens, and periods.
88 · Replace all spaces and newlines with hyphens.
90 · Convert all alphabetic characters to lowercase.
92 · Remove everything up to the first letter (identifiers may not begin
94 with a number or punctuation mark).
95 · If nothing is left after this, use the identifier section.
97 Thus, for example,
99 Header Identifier
101 ────────────────────────────────────────────────────────
102 Header identifiers in HTML header-identifiers-in-html
103 Dogs?--in my house? dogs--in-my-house
104 HTML, S5, or RTF? html-s5-or-rtf
105 3. Applications applications
106 33 section
107 These rules should, in most cases, allow one to determine the identi‐
109 fier from the header text. The exception is when several headers have
110 the same text; in this case, the first will get an identifier as
111 described above; the second will get the same identifier with -1
112 appended; the third with -2; and so on.
113 These identifiers are used to provide link targets in the table of con‐
115 tents generated by the --toc|--table-of-contents option. They also
116 make it easy to provide links from one section of a document to
117 another. A link to this section, for example, might look like this:
118 See the section on
120 [header identifiers](#header-identifiers-in-html).
121 Note, however, that this method of providing links to sections works
123 only in HTML.
124 If the --section-divs option is specified, then each section will be
126 wrapped in a div (or a section, if --html5 was specified), and the
127 identifier will be attached to the enclosing <div> (or <section>) tag
128 rather than the header itself. This allows entire sections to be
129 manipulated using javascript or treated differently in CSS.
130
132 Markdown uses email conventions for quoting blocks of text. A block
133 quotation is one or more paragraphs or other block elements (such as
134 lists or headers), with each line preceded by a > character and a
135 space. (The > need not start at the left margin, but it should not be
136 indented more than three spaces.)
137 > This is a block quote. This
139 > paragraph has two lines.
140 >
141 > 1. This is a list inside a block quote.
142 > 2. Second item.
143 A "lazy" form, which requires the > character only on the first line of
145 each block, is also allowed:
146 > This is a block quote. This
148 paragraph has two lines.
149 > 1. This is a list inside a block quote.
151 2. Second item.
152 Among the block elements that can be contained in a block quote are
154 other block quotes. That is, block quotes can be nested:
155 > This is a block quote.
157 >
158 > > A block quote within a block quote.
159 Standard markdown syntax does not require a blank line before a block
161 quote. Pandoc does require this (except, of course, at the beginning
162 of the document). The reason for the requirement is that it is all too
163 easy for a > to end up at the beginning of a line by accident (perhaps
164 through line wrapping). So, unless --strict is used, the following
165 does not produce a nested block quote in pandoc:
166 > This is a block quote.
168 >> Nested.
169
171 Indented code blocks
172 A block of text indented four spaces (or one tab) is treated as verba‐
173 tim text: that is, special characters do not trigger special format‐
174 ting, and all spaces and line breaks are preserved. For example,
175 if (a > 3) {
177 moveShip(5 * gravity, DOWN);
178 }
179 The initial (four space or one tab) indentation is not considered part
181 of the verbatim text, and is removed in the output.
182 Note: blank lines in the verbatim text need not begin with four spaces.
184 Delimited code blocks
186 Pandoc extension.
187 In addition to standard indented code blocks, Pandoc supports delimited
189 code blocks. These begin with a row of three or more tildes (~) and
190 end with a row of tildes that must be at least as long as the starting
191 row. Everything between the tilde-lines is treated as code. No inden‐
192 tation is necessary:
193 ~~~~~~~
195 if (a > 3) {
196 moveShip(5 * gravity, DOWN);
197 }
198 ~~~~~~~
199 Like regular code blocks, delimited code blocks must be separated from
201 surrounding text by blank lines.
202 If the code itself contains a row of tildes, just use a longer row of
204 tildes at the start and end:
205 ~~~~~~~~~~~~~~~~
207 ~~~~~~~~~~
208 code including tildes
209 ~~~~~~~~~~
210 ~~~~~~~~~~~~~~~~
211 Optionally, you may specify the language of the code block using this
213 syntax:
214 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}
216 qsort [] = []
217 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++
218 qsort (filter (>= x) xs)
219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
220 Some output formats can use this information to do syntax highlighting.
222 Currently, the only output format that uses this information is HTML.
223 If pandoc has been compiled with syntax highlighting support, then the
225 code block above will appear highlighted, with numbered lines. (To see
226 which languages are supported, do pandoc --version.)
227 If pandoc has not been compiled with syntax highlighting support, the
229 code block above will appear as follows:
230 <pre class="haskell">
232 <code>
233 ...
234 </code>
235 </pre>
236
238 Bullet lists
239 A bullet list is a list of bulleted list items. A bulleted list item
240 begins with a bullet (*, +, or -). Here is a simple example:
241 * one
243 * two
244 * three
245 This will produce a "compact" list. If you want a "loose" list, in
247 which each item is formatted as a paragraph, put spaces between the
248 items:
249 * one
251 * two
253 * three
255 The bullets need not be flush with the left margin; they may be
257 indented one, two, or three spaces. The bullet must be followed by
258 whitespace.
259 List items look best if subsequent lines are flush with the first line
261 (after the bullet):
262 * here is my first
264 list item.
265 * and my second.
266 But markdown also allows a "lazy" format:
268 * here is my first
270 list item.
271 * and my second.
272 The four-space rule
274 A list item may contain multiple paragraphs and other block-level con‐
275 tent. However, subsequent paragraphs must be preceded by a blank line
276 and indented four spaces or a tab. The list will look better if the
277 first paragraph is aligned with the rest:
278 * First paragraph.
280 Continued.
282 * Second paragraph. With a code block, which must be indented
284 eight spaces:
285 { code }
287 List items may include other lists. In this case the preceding blank
289 line is optional. The nested list must be indented four spaces or one
290 tab:
291 * fruits
293 + apples
294 - macintosh
295 - red delicious
296 + pears
297 + peaches
298 * vegetables
299 + brocolli
300 + chard
301 As noted above, markdown allows you to write list items "lazily,"
303 instead of indenting continuation lines. However, if there are multi‐
304 ple paragraphs or other blocks in a list item, the first line of each
305 must be indented.
306 + A lazy, lazy, list
308 item.
309 + Another one; this looks
311 bad but is legal.
312 Second paragraph of second
314 list item.
315 Note: Although the four-space rule for continuation paragraphs comes
317 from the official markdown syntax guide, the reference implementation,
318 Markdown.pl, does not follow it. So pandoc will give different results
319 than Markdown.pl when authors have indented continuation paragraphs
320 fewer than four spaces.
321 The markdown syntax guide is not explicit whether the four-space rule
323 applies to all block-level content in a list item; it only mentions
324 paragraphs and code blocks. But it implies that the rule applies to
325 all block-level content (including nested lists), and pandoc interprets
326 it that way.
327 Ordered lists
329 Ordered lists work just like bulleted lists, except that the items
330 begin with enumerators rather than bullets.
331 In standard markdown, enumerators are decimal numbers followed by a
333 period and a space. The numbers themselves are ignored, so there is no
334 difference between this list:
335 1. one
337 2. two
338 3. three
339 and this one:
341 5. one
343 7. two
344 1. three
345 Pandoc extension.
347 Unlike standard markdown, Pandoc allows ordered list items to be marked
349 with uppercase and lowercase letters and roman numerals, in addition to
350 arabic numerals. List markers may be enclosed in parentheses or fol‐
351 lowed by a single right-parentheses or period. They must be separated
352 from the text that follows by at least one space, and, if the list
353 marker is a capital letter with a period, by at least two spaces.[1]
354 Pandoc also pays attention to the type of list marker used, and to the
356 starting number, and both of these are preserved where possible in the
357 output format. Thus, the following yields a list with numbers followed
358 by a single parenthesis, starting with 9, and a sublist with lowercase
359 roman numerals:
360 9) Ninth
362 10) Tenth
363 11) Eleventh
364 i. subone
365 ii. subtwo
366 iii. subthree
367 Note that Pandoc pays attention only to the starting marker in a list.
369 So, the following yields a list numbered sequentially starting from 2:
370 (2) Two
372 (5) Three
373 1. Four
374 * Five
375 If default list markers are desired, use #.:
377 #. one
379 #. two
380 #. three
381 Definition lists
383 Pandoc extension.
384 Pandoc supports definition lists, using a syntax inspired by PHP Mark‐
386 down Extra and reStructuredText:[2]
387 Term 1
389 : Definition 1
391 Term 2 with *inline markup*
393 : Definition 2
395 { some code, part of Definition 2 }
397 Third paragraph of definition 2.
399 Each term must fit on one line, which may optionally be followed by a
401 blank line, and must be followed by one or more definitions. A defini‐
402 tion begins with a colon or tilde, which may be indented one or two
403 spaces. A term may have multiple definitions, and each definition may
404 consist of one or more block elements (paragraph, code block, list,
405 etc.) , each indented four spaces or one tab stop.
406 If you leave space after the definition (as in the example above), the
408 blocks of the definitions will be considered paragraphs. In some out‐
409 put formats, this will mean greater spacing between term/definition
410 pairs. For a compact definition list, do not leave space between the
411 definition and the next term:
412 Term 1
414 ~ Definition 1
415 Term 2
416 ~ Definition 2a
417 ~ Definition 2b
418 Numbered example lists
420 Pandoc extension.
421 The special list marker @ can be used for sequentially numbered exam‐
423 ples. The first list item with a @ marker will be numbered '1', the
424 next '2', and so on, throughout the document. The numbered examples
425 need not occur in a single list; each new list using @ will take up
426 where the last stopped. So, for example:
427 (@) My first example will be numbered (1).
429 (@) My second example will be numbered (2).
430 Explanation of examples.
432 (@) My third example will be numbered (3).
434 Numbered examples can be labeled and referred to elsewhere in the docu‐
436 ment:
437 (@good) This is a good example.
439 As (@good) illustrates, ...
441 The label can be any string of alphanumeric characters, underscores, or
443 hyphens.
444 Compact and loose lists
446 Pandoc behaves differently from Markdown.pl on some "edge cases"
447 involving lists. Consider this source:
448 + First
450 + Second:
451 - Fee
452 - Fie
453 - Foe
454 + Third
456 Pandoc transforms this into a "compact list" (with no <p> tags around
458 "First", "Second", or "Third"), while markdown puts <p> tags around
459 "Second" and "Third" (but not "First"), because of the blank space
460 around "Third". Pandoc follows a simple rule: if the text is followed
461 by a blank line, it is treated as a paragraph. Since "Second" is fol‐
462 lowed by a list, and not a blank line, it isn't treated as a paragraph.
463 The fact that the list is followed by a blank line is irrelevant.
464 (Note: Pandoc works this way even when the --strict option is speci‐
465 fied. This behavior is consistent with the official markdown syntax
466 description, even though it is different from that of Markdown.pl.)
467 Ending a list
469 What if you want to put an indented code block after a list?
470 - item one
472 - item two
473 { my code block }
475 Trouble! Here pandoc (like other markdown implementations) will treat
477 { my code block } as the second paragraph of item two, and not as a
478 code block.
479 To "cut off" the list after item two, you can insert some non-indented
481 content, like an HTML comment, which won't produce visible output in
482 any format:
483 - item one
485 - item two
486 <!-- end of list -->
488 { my code block }
490 You can use the same trick if you want two consecutive lists instead of
492 one big list:
493 1. one
495 2. two
496 3. three
497 <!-- -->
499 a. uno
501 b. dos
502 c. tres
503
505 A line containing a row of three or more *, -, or _ characters (option‐
506 ally separated by spaces) produces a horizontal rule:
507 * * * *
509 ---------------
511
513 Pandoc extension.
514 Three kinds of tables may be used. All three kinds presuppose the use
516 of a fixed-width font, such as Courier.
517 Simple tables look like this:
519 Right Left Center Default
521 ------- ------ ---------- -------
522 12 12 12 12
523 123 123 123 123
524 1 1 1 1
525 Table: Demonstration of simple table syntax.
527 The headers and table rows must each fit on one line. Column align‐
529 ments are determined by the position of the header text relative to the
530 dashed line below it:[3]
531 · If the dashed line is flush with the header text on the right side
533 but extends beyond it on the left, the column is right-aligned.
534 · If the dashed line is flush with the header text on the left side but
536 extends beyond it on the right, the column is left-aligned.
537 · If the dashed line extends beyond the header text on both sides, the
539 column is centered.
540 · If the dashed line is flush with the header text on both sides, the
542 default alignment is used (in most cases, this will be left).
543 The table must end with a blank line, or a line of dashes followed by a
545 blank line. A caption may optionally be provided (as illustrated in
546 the example above). A caption is a paragraph beginning with the string
547 Table: (or just :), which will be stripped off. It may appear either
548 before or after the table.
549 The column headers may be omitted, provided a dashed line is used to
551 end the table. For example:
552 ------- ------ ---------- -------
554 12 12 12 12
555 123 123 123 123
556 1 1 1 1
557 ------- ------ ---------- -------
558 When headers are omitted, column alignments are determined on the basis
560 of the first line of the table body. So, in the tables above, the col‐
561 umns would be right, left, center, and right aligned, respectively.
562 Multiline tables allow headers and table rows to span multiple lines of
564 text (but cells that span multiple columns or rows of the table are not
565 supported). Here is an example:
566 -------------------------------------------------------------
568 Centered Default Right Left
569 Header Aligned Aligned Aligned
570 ----------- ------- --------------- -------------------------
571 First row 12.0 Example of a row that
572 spans multiple lines.
573 Second row 5.0 Here's another one. Note
575 the blank line between
576 rows.
577 -------------------------------------------------------------
578 Table: Here's the caption. It, too, may span
580 multiple lines.
581 These work like simple tables, but with the following differences:
583 · They must begin with a row of dashes, before the header text (unless
585 the headers are omitted).
586 · They must end with a row of dashes, then a blank line.
588 · The rows must be separated by blank lines.
590 In multiline tables, the table parser pays attention to the widths of
592 the columns, and the writers try to reproduce these relative widths in
593 the output. So, if you find that one of the columns is too narrow in
594 the output, try widening it in the markdown source.
595 Headers may be omitted in multiline tables as well as simple tables:
597 ----------- ------- --------------- -------------------------
599 First row 12.0 Example of a row that
600 spans multiple lines.
601 Second row 5.0 Here's another one. Note
603 the blank line between
604 rows.
605 -------------------------------------------------------------
606 : Here's a multiline table without headers.
608 It is possible for a multiline table to have just one row, but the row
610 should be followed by a blank line (and then the row of dashes that
611 ends the table), or the table may be interpreted as a simple table.
612 Grid tables look like this:
614 : Sample grid table.
616 +---------------+---------------+--------------------+
618 | Fruit | Price | Advantages |
619 +===============+===============+====================+
620 | Bananas | $1.34 | - built-in wrapper |
621 | | | - bright color |
622 +---------------+---------------+--------------------+
623 | Oranges | $2.10 | - cures scurvy |
624 | | | - tasty |
625 +---------------+---------------+--------------------+
626 The row of =s separates the header from the table body, and can be
628 omitted for a headerless table. The cells of grid tables may contain
629 arbitrary block elements (multiple paragraphs, code blocks, lists,
630 etc.) . Alignments are not supported, nor are cells that span multi‐
631 ple columns or rows. Grid tables can be created easily using Emacs ta‐
632 ble mode.
633
635 Pandoc extension.
636 If the file begins with a title block
638 % title
640 % author(s) (separated by semicolons)
641 % date
642 it will be parsed as bibliographic information, not regular text. (It
644 will be used, for example, in the title of standalone LaTeX or HTML
645 output.)
646 The block may contain just a title, a title and an author, or all
647 three elements. If you want to include an author but no title, or a
648 title and a date but no author, you need a blank line:
649 %
651 % Author
652 % My title
654 %
655 % June 15, 2006
656 The title may occupy multiple lines, but continuation lines must begin
658 with leading space, thus:
659 % My title
661 on multiple lines
662 If a document has multiple authors, the authors may be put on separate
664 lines with leading space, or separated by semicolons, or both. So, all
665 of the following are equivalent:
666 % Author One
668 Author Two
669 % Author One; Author Two
671 % Author One;
673 Author Two
674 The date must fit on one line.
676 All three metadata fields may contain standard inline formatting (ital‐
678 ics, links, footnotes, etc.) .
679 Title blocks will always be parsed, but they will affect the output
681 only when the --standalone (-s) option is chosen. In HTML output,
682 titles will appear twice: once in the document head -- this is the
683 title that will appear at the top of the window in a browser -- and
684 once at the beginning of the document body. The title in the document
685 head can have an optional prefix attached (--title-prefix or -T
686 option). The title in the body appears as an H1 element with class
687 "title", so it can be suppressed or reformatted with CSS. If a title
688 prefix is specified with -T and no title block appears in the document,
689 the title prefix will be used by itself as the HTML title.
690 The man page writer extracts a title, man page section number, and
692 other header and footer information from the title line. The title is
693 assumed to be the first word on the title line, which may optionally
694 end with a (single-digit) section number in parentheses. (There should
695 be no space between the title and the parentheses.)
696 Anything after this is assumed to be additional footer and header
697 text. A single pipe character (|) should be used to separate the
698 footer text from the header text. Thus,
699 % PANDOC(1)
701 will yield a man page with the title PANDOC and section 1.
703 % PANDOC(1) Pandoc User Manuals
705 will also have "Pandoc User Manuals" in the footer.
707 % PANDOC(1) Pandoc User Manuals | Version 4.0
709 will also have "Version 4.0" in the header.
711
713 Except inside a code block or inline code, any punctuation or space
714 character preceded by a backslash will be treated literally, even if it
715 would normally indicate formatting. Thus, for example, if one writes
716 *\*hello\**
718 one will get
720 <em>*hello*</em>
722 instead of
724 <strong>hello</strong>
726 This rule is easier to remember than standard markdown's rule, which
728 allows only the following characters to be backslash-escaped:
729 \`*_{}[]()>#+-.!
731 (However, if the --strict option is supplied, the standard markdown
733 rule will be used.)
734 A backslash-escaped space is parsed as a nonbreaking space. It will
736 appear in TeX output as ~ and in HTML and XML as \  or \ .
737 A backslash-escaped newline (i.e. a backslash occurring at the end of
739 a line) is parsed as a hard line break. It will appear in TeX output
740 as \\ and in HTML as <br />. This is a nice alternative to markdown's
741 "invisible" way of indicating hard line breaks using two trailing spa‐
742 ces on a line.
743 Backslash escapes do not work in verbatim contexts.
745
747 If the --smart option is specified, pandoc will produce typographically
748 correct output, converting straight quotes to curly quotes, --- and --
749 to Em-dashes, and ... to ellipses. Nonbreaking spaces are inserted
750 after certain abbreviations, such as "Mr."
751
753 Emphasis
754 To emphasize some text, surround it with *s or _, like this:
755 This text is _emphasized with underscores_, and this
757 is *emphasized with asterisks*.
758 Double * or _ produces strong emphasis:
760 This is **strong emphasis** and __with underscores__.
762 A * or _ character surrounded by spaces, or backslash-escaped, will not
764 trigger emphasis:
765 This is * not emphasized *, and \*neither is this\*.
767 Because _ is sometimes used inside words and identifiers, pandoc does
769 not interpret a _ surrounded by alphanumeric characters as an emphasis
770 marker. If you want to emphasize just part of a word, use *:
771 feas*ible*, not feas*able*.
773 Strikeout
775 Pandoc extension.
776 To strikeout a section of text with a horizontal line, begin and end it
778 with ~~. Thus, for example,
779 This ~~is deleted text.~~
781 Superscripts and subscripts
783 Pandoc extension.
784 Superscripts may be written by surrounding the superscripted text by ^
786 characters; subscripts may be written by surrounding the subscripted
787 text by ~ characters. Thus, for example,
788 H~2~O is a liquid. 2^10^ is 1024.
790 If the superscripted or subscripted text contains spaces, these spaces
792 must be escaped with backslashes. (This is to prevent accidental
793 superscripting and subscripting through the ordinary use of ~ and ^.)
794 Thus, if you want the letter P with 'a cat' in subscripts, use
795 P~a\ cat~, not P~a cat~.
796 Verbatim
798 To make a short span of text verbatim, put it inside backticks:
799 What is the difference between `>>=` and `>>`?
801 If the verbatim text includes a backtick, use double backticks:
803 Here is a literal backtick `` ` ``.
805 (The spaces after the opening backticks and before the closing back‐
807 ticks will be ignored.)
808 The general rule is that a verbatim span starts with a string of con‐
810 secutive backticks (optionally followed by a space) and ends with a
811 string of the same number of backticks (optionally preceded by a
812 space).
813 Note that backslash-escapes (and other markdown constructs) do not work
815 in verbatim contexts:
816 This is a backslash followed by an asterisk: `\*`.
818
820 Pandoc extension.
821 Anything between two $ characters will be treated as TeX math. The
823 opening $ must have a character immediately to its right, while the
824 closing $ must have a character immediately to its left. Thus,
825 $20,000 and $30,000 won't parse as math. If for some reason you need
826 to enclose text in literal $ characters, backslash-escape them and they
827 won't be treated as math delimiters.
828 TeX math will be printed in all output formats. How it is rendered
830 depends on the output format:
831 Markdown, reStructuredText, LaTeX, Org-Mode, ConTeXt
833 It will appear verbatim between $ characters.
834 reStructuredText
836 It will be rendered using an interpreted text role :math:, as
837 described here.
838 Texinfo
840 It will be rendered inside a @math command.
841 groff man
843 It will be rendered verbatim without $'s.
844 MediaWiki
846 It will be rendered inside <math> tags.
847 Textile
849 It will be rendered inside <span class="math"> tags.
850 RTF, Docbook, OpenDocument, ODT
852 It will be rendered, if possible, using unicode characters, and
853 will otherwise appear verbatim.
854 HTML, Slidy, S5, EPUB
856 The way math is rendered in HTML will depend on the command-line
857 options selected:
858 1. The default is to render TeX math as far as possible using
860 unicode characters, as with RTF, Docbook, and OpenDocument
861 output. Formulas are put inside a span with class="math", so
862 that they may be styled differently from the surrounding text
863 if needed.
864 2. If the --latexmathml option is used, TeX math will be dis‐
866 played between $ or $$ characters and put in <span> tags with
867 class LaTeX. The LaTeXMathML script will be used to render
868 it as formulas. (This trick does not work in all browsers,
869 but it works in Firefox. In browsers that do not support
870 LaTeXMathML, TeX math will appear verbatim between $ charac‐
871 ters.)
872 3. If the --jsmath option is used, TeX math will be put inside
874 <span> tags (for inline math) or <div> tags (for display
875 math) with class math. The jsMath script will be used to
876 render it.
877 4. If the --mimetex option is used, the mimeTeX CGI script will
879 be called to generate images for each TeX formula. This
880 should work in all browsers. The --mimetex option takes an
881 optional URL as argument. If no URL is specified, it will be
882 assumed that the mimeTeX CGI script is at /cgi-bin/mime‐
883 tex.cgi.
884 5. If the --gladtex option is used, TeX formulas will be
886 enclosed in <eq> tags in the HTML output. The resulting htex
887 file may then be processed by gladTeX, which will produce
888 image files for each formula and an html file with links to
889 these images. So, the procedure is:
890 pandoc -s --gladtex myfile.txt -o myfile.htex
892 gladtex -d myfile-images myfile.htex
893 # produces myfile.html and images in myfile-images
894 6. If the --webtex option is used, TeX formulas will be con‐
896 verted to <img> tags that link to an external script that
897 converts formulas to images. The formula will be URL-encoded
898 and concatenated with the URL provided. If no URL is speci‐
899 fied, the Google Chart API will be used
900 (http://chart.apis.google.com/chart?cht=tx&chl=).
901
903 Markdown allows you to insert raw HTML anywhere in a document (except
904 verbatim contexts, where <, >, and & are interpreted literally).
905 The raw HTML is passed through unchanged in HTML, S5, Slidy, EPUB,
907 Markdown, and Textile output, and suppressed in other formats.
908 Pandoc extension.
910 Standard markdown allows you to include HTML "blocks": blocks of HTML
912 between balanced tags that are separated from the surrounding text with
913 blank lines, and start and end at the left margin. Within these
914 blocks, everything is interpreted as HTML, not markdown; so (for exam‐
915 ple), * does not signify emphasis.
916 Pandoc behaves this way when --strict is specified; but by default,
918 pandoc interprets material between HTML block tags as markdown. Thus,
919 for example, Pandoc will turn
920 <table>
922 <tr>
923 <td>*one*</td>
924 <td>[a link](http://google.com)</td>
925 </tr>
926 </table>
927 into
929 <table>
931 <tr>
932 <td><em>one</em></td>
933 <td><a href="http://google.com">a link</a></td>
934 </tr>
935 </table>
936 whereas Markdown.pl will preserve it as is.
938 There is one exception to this rule: text between <script> and <style>
940 tags is not interpreted as markdown.
941 This departure from standard markdown should make it easier to mix
943 markdown with HTML block elements. For example, one can surround a
944 block of markdown text with <div> tags without preventing it from being
945 interpreted as markdown.
946
948 Pandoc extension.
949 In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to
951 be included in a document. Inline TeX commands will be preserved and
952 passed unchanged to the LaTeX and ConTeXt writers. Thus, for example,
953 you can use LaTeX to include BibTeX citations:
954 This result was proved in \cite{jones.1967}.
956 Note that in LaTeX environments, like
958 \begin{tabular}{|l|l|}\hline
960 Age & Frequency \\ \hline
961 18--25 & 15 \\
962 26--35 & 33 \\
963 36--45 & 22 \\ \hline
964 \end{tabular}
965 the material between the begin and end tags will be interpreted as raw
967 LaTeX, not as markdown.
968 Inline LaTeX is ignored in output formats other than Markdown, LaTeX,
970 and ConTeXt.
971 Macros
973 For output formats other than LaTeX, pandoc will parse LaTeX \newcom‐
974 mand and \renewcommand definitions and apply the resulting macros to
975 all LaTeX math. So, for example, the following will work in all output
976 formats, not just LaTeX:
977 \newcommand{\tuple}[1]{\langle #1 \rangle}
979 $\tuple{a, b, c}$
981 In LaTeX output, the \newcommand definition will simply be passed
983 unchanged to the output.
984
986 Markdown allows links to be specified in several ways.
987 Automatic links
989 If you enclose a URL or email address in pointy brackets, it will
990 become a link:
991 <http://google.com>
993 <sam@green.eggs.ham>
994 Inline links
996 An inline link consists of the link text in square brackets, followed
997 by the URL in parentheses. (Optionally, the URL can be followed by a
998 link title, in quotes.)
999 This is an [inline link](/url), and here's [one with
1001 a title](http://fsf.org "click here for a good time!").
1002 There can be no space between the bracketed part and the parenthesized
1004 part. The link text can contain formatting (such as emphasis), but the
1005 title cannot.
1006 Reference links
1008 An explicit reference link has two parts, the link itself and the link
1009 definition, which may occur elsewhere in the document (either before or
1010 after the link).
1011 The link consists of link text in square brackets, followed by a label
1013 in square brackets. (There can be space between the two.)
1014 The link definition must begin at the left margin or indented no more
1015 than three spaces. It consists of the bracketed label, followed by a
1016 colon and a space, followed by the URL, and optionally (after a space)
1017 a link title either in quotes or in parentheses.
1018 Here are some examples:
1020 [my label 1]: /foo/bar.html "My title, optional"
1022 [my label 2]: /foo
1023 [my label 3]: http://fsf.org (The free software foundation)
1024 [my label 4]: /bar#special 'A title in single quotes'
1025 The URL may optionally be surrounded by angle brackets:
1027 [my label 5]: <http://foo.bar.baz>
1029 The title may go on the next line:
1031 [my label 3]: http://fsf.org
1033 "The free software foundation"
1034 Note that link labels are not case sensitive. So, this will work:
1036 Here is [my link][FOO]
1038 [Foo]: /bar/baz
1040 In an implicit reference link, the second pair of brackets is empty, or
1042 omitted entirely:
1043 See [my website][], or [my website].
1045 [my website]: http://foo.bar.baz
1047
1049 A link immediately preceded by a ! will be treated as an image. The
1050 link text will be used as the image's alt text:
1051 
1053 ![movie reel]
1055 [movie reel]: movie.gif
1057 Pictures with captions
1059 Pandoc extension.
1060 An image occurring by itself in a paragraph will be rendered as a fig‐
1062 ure with a caption.[4] (In LaTeX, a figure environment will be used; in
1063 HTML, the image will be placed in a div with class figure, together
1064 with a caption in a p with class caption.)
1065 The image's alt text will be used as the caption.
1066 
1068 If you just want a regular inline image, just make sure it is not the
1070 only thing in the paragraph. One way to do this is to insert a non‐
1071 breaking space after the image:
1072 \
1074
1076 Pandoc extension.
1077 Pandoc's markdown allows footnotes, using the following syntax:
1079 Here is a footnote reference,[^1] and another.[^longnote]
1081 [^1]: Here is the footnote.
1083 [^longnote]: Here's one with multiple blocks.
1085 Subsequent paragraphs are indented to show that they
1087 belong to the previous footnote.
1088 { some.code }
1090 The whole paragraph can be indented, or just the first
1092 line. In this way, multi-paragraph footnotes work like
1093 multi-paragraph list items.
1094 This paragraph won't be part of the note, because it
1096 isn't indented.
1097 The identifiers in footnote references may not contain spaces, tabs, or
1099 newlines. These identifiers are used only to correlate the footnote
1100 reference with the note itself; in the output, footnotes will be num‐
1101 bered sequentially.
1102 The footnotes themselves need not be placed at the end of the document.
1104 They may appear anywhere except inside other block elements (lists,
1105 block quotes, tables, etc.) .
1106 Inline footnotes are also allowed (though, unlike regular notes, they
1108 cannot contain multiple paragraphs). The syntax is as follows:
1109 Here is an inline note.^[Inlines notes are easier to write, since
1111 you don't have to pick an identifier and move down to type the
1112 note.]
1113 Inline and regular footnotes may be mixed freely.
1115
1117 Pandoc extension.
1118 Pandoc can automatically generate citations and a bibliography in a
1120 number of styles (using Andrea Rossato's hs-citeproc). In order to use
1121 this feature, you will need a bibliographic database in one of the fol‐
1122 lowing formats:
1123 Format File extension
1125 ───────────────────────────────
1126 MODS .mods
1127 BibTeX .bib
1128 BibLaTeX .bbx
1129 RIS .ris
1130 EndNote .enl
1131 EndNote XML .xml
1132 ISI .wos
1133 MEDLINE .medline
1134 Copac .copac
1135 JSON citeproc .json
1136 You will need to specify the bibliography file using the --bibliography
1138 command-line option (which may be repeated if you have several bibli‐
1139 ographies).
1140 By default, pandoc will use a Chicago author-date format for citations
1142 and references. To use another style, you will need to use the --csl
1143 option to specify a CSL 1.0 style file. A primer on creating and modi‐
1144 fying CSL styles can be found at http://citationstyles.org/down‐
1145 loads/primer.html. A repository of CSL styles can be found at
1146 https://github.com/citation-style-language/styles.
1147 Citations go inside square brackets and are separated by semicolons.
1149 Each citation must have a key, composed of '@' + the citation identi‐
1150 fier from the database, and may optionally have a prefix, a locator,
1151 and a suffix. Here are some examples:
1152 Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].
1154 Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].
1156 Blah blah [@smith04; @doe99].
1158 A minus sign (-) before the @ will suppress mention of the author in
1160 the citation. This can be useful when the author is already mentioned
1161 in the text:
1162 Smith says blah [-@smith04].
1164 You can also write an in-text citation, as follows:
1166 @smith04 says blah.
1168 @smith04 [p. 33] says blah.
1170 If the style calls for a list of works cited, it will be placed at the
1172 end of the document. Normally, you will want to end your document with
1173 an appropriate header:
1174 last paragraph...
1176 # References
1178 The bibliography will be inserted after this header.
1180
1182 [1]
1183 The point of this rule is to ensure that normal paragraphs starting
1184 with people's initials, like
1185 B. Russell was an English philosopher.
1187 do not get treated as list items.
1189 This rule will not prevent
1191 (C) 2007 Joe Smith
1193 from being interpreted as a list item. In this case, a backslash
1195 escape can be used:
1196 (C\) 2007 Joe Smith
1198 [2]
1200 I have also been influenced by the suggestions of David Wheeler.
1201 [3]
1203 This scheme is due to Michel Fortin, who proposed it on the Markdown
1204 discussion list.
1205 [4]
1207 This feature is not yet implemented for RTF, OpenDocument, or ODT. In
1208 those formats, you'll just get an image in a paragraph by itself, with
1209 no caption.
1210
1212 pandoc (1).
1213Pandoc January 29, 2011 PANDOC_MARKDOWN(5)