README · typeable/pandoc

1066[^3]: I have also been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html).

1067

1068[PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/

1069

1070

1071### Numbered example lists ###

1072

1073*Pandoc extension*.

1074

1075The special list marker `@` can be used for sequentially numbered

1076examples. The first list item with a `@` marker will be numbered '1',

1077the next '2', and so on, throughout the document. The numbered examples

1078need not occur in a single list; each new list using `@` will take up

1079where the last stopped. So, for example:

1080

1081 (@) My first example will be numbered (1).

1082 (@) My second example will be numbered (2).

1083

1084 Explanation of examples.

1085

1086 (@) My third example will be numbered (3).

1087

1088Numbered examples can be labeled and referred to elsewhere in the

1089document:

1090

1091 (@good) This is a good example.

1092

1093 As (@good) illustrates, ...

1094

1095The label can be any string of alphanumeric characters, underscores,

1096or hyphens.

1097

1098

1099### Compact and loose lists ###

1100

1101Pandoc behaves differently from `Markdown.pl` on some "edge

1102cases" involving lists. Consider this source:

1103

1104 + First

1105 + Second:

1106 - Fee

1107 - Fie

1108 - Foe

1109

1110 + Third

1111

1112Pandoc transforms this into a "compact list" (with no `<p>` tags around

1113"First", "Second", or "Third"), while markdown puts `<p>` tags around

1114"Second" and "Third" (but not "First"), because of the blank space

1115around "Third". Pandoc follows a simple rule: if the text is followed by

1116a blank line, it is treated as a paragraph. Since "Second" is followed

1117by a list, and not a blank line, it isn't treated as a paragraph. The

1118fact that the list is followed by a blank line is irrelevant. (Note:

1119Pandoc works this way even when the `--strict` option is specified. This

1120behavior is consistent with the official markdown syntax description,

1121even though it is different from that of `Markdown.pl`.)

1122

1123

1124### Ending a list ###

1125

1126What if you want to put an indented code block after a list?

1127

1128 - item one

1129 - item two

1130

1131 { my code block }

1132

1133Trouble! Here pandoc (like other markdown implementations) will treat

1134`{ my code block }` as the second paragraph of item two, and not as

1135a code block.

1136

1137To "cut off" the list after item two, you can insert some non-indented

1138content, like an HTML comment, which won't produce visible output in

1139any format:

1140

1141 - item one

1142 - item two

1143

1144

1145

1146 { my code block }

1147

1148You can use the same trick if you want two consecutive lists instead

1149of one big list:

1150

1151 1. one

1152 2. two

1153 3. three

1154

1155

1156

1157 a. uno

1158 b. dos

1159 c. tres

1160

1161

1162Horizontal rules

1163----------------

1164

1165A line containing a row of three or more `*`, `-`, or `_` characters

1166(optionally separated by spaces) produces a horizontal rule:

1168 * * * *

1170 ---------------

1173Tables

1174------

1175

1176*Pandoc extension*.

1177

1178Three kinds of tables may be used. All three kinds presuppose the use of

1179a fixed-width font, such as Courier.

1180

1181**Simple tables** look like this:

1182

1183 Right Left Center Default

1184 ------- ------ ---------- -------

1185 12 12 12 12

1186 123 123 123 123

1187 1 1 1 1

1188

1189 Table: Demonstration of simple table syntax.

1190

1191The headers and table rows must each fit on one line. Column

1192alignments are determined by the position of the header text relative

1193to the dashed line below it:[^4]

1194

1195 - If the dashed line is flush with the header text on the right side

1196 but extends beyond it on the left, the column is right-aligned.

1197 - If the dashed line is flush with the header text on the left side

1198 but extends beyond it on the right, the column is left-aligned.

1199 - If the dashed line extends beyond the header text on both sides,

1200 the column is centered.

1201 - If the dashed line is flush with the header text on both sides,

1202 the default alignment is used (in most cases, this will be left).

1203

1204[^4]: This scheme is due to Michel Fortin, who proposed it on the

1205 [Markdown discussion list](http://six.pairlist.net/pipermail/markdown-discuss/2005-March/001097.html).

1206

1207The table must end with a blank line, or a line of dashes followed by

1208a blank line. A caption may optionally be provided (as illustrated in

1209the example above). A caption is a paragraph beginning with the string

1210`Table:` (or just `:`), which will be stripped off. It may appear either

1211before or after the table.

1212

1213The column headers may be omitted, provided a dashed line is used

1214to end the table. For example:

1215

1216 ------- ------ ---------- -------

1217 12 12 12 12

1218 123 123 123 123

1219 1 1 1 1

1220 ------- ------ ---------- -------

1221

1222When headers are omitted, column alignments are determined on the basis

1223of the first line of the table body. So, in the tables above, the columns

1224would be right, left, center, and right aligned, respectively.

1225

1226**Multiline tables** allow headers and table rows to span multiple lines

1227of text (but cells that span multiple columns or rows of the table are

1228not supported). Here is an example:

1229

1230 -------------------------------------------------------------

1231 Centered Default Right Left

1232 Header Aligned Aligned Aligned

1233 ----------- ------- --------------- -------------------------

1234 First row 12.0 Example of a row that

1235 spans multiple lines.

1236

1237 Second row 5.0 Here's another one. Note

1238 the blank line between

1239 rows.

1240 -------------------------------------------------------------

1241

1242 Table: Here's the caption. It, too, may span

1243 multiple lines.

1244

1245These work like simple tables, but with the following differences:

1246

1247 - They must begin with a row of dashes, before the header text

1248 (unless the headers are omitted).

1249 - They must end with a row of dashes, then a blank line.

1250 - The rows must be separated by blank lines.

1251

1252In multiline tables, the table parser pays attention to the widths of

1253the columns, and the writers try to reproduce these relative widths in

1254the output. So, if you find that one of the columns is too narrow in the

1255output, try widening it in the markdown source.

1256

1257Headers may be omitted in multiline tables as well as simple tables:

1258

1259 ----------- ------- --------------- -------------------------

1260 First row 12.0 Example of a row that

1261 spans multiple lines.

1262

1263 Second row 5.0 Here's another one. Note

1264 the blank line between

1265 rows.

1266 -------------------------------------------------------------

1267

1268 : Here's a multiline table without headers.

1269

1270It is possible for a multiline table to have just one row, but the row

1271should be followed by a blank line (and then the row of dashes that ends

1272the table), or the table may be interpreted as a simple table.

1273

1274**Grid tables** look like this:

1275

1276 : Sample grid table.

1277

1278 +---------------+---------------+--------------------+

1279 | Fruit | Price | Advantages |

1280 +===============+===============+====================+

1281 | Bananas | $1.34 | - built-in wrapper |

1282 | | | - bright color |

1283 +---------------+---------------+--------------------+

1284 | Oranges | $2.10 | - cures scurvy |

1285 | | | - tasty |

1286 +---------------+---------------+--------------------+

1287

1288The row of `=`s separates the header from the table body, and can be

1289omitted for a headerless table. The cells of grid tables may contain

1290arbitrary block elements (multiple paragraphs, code blocks, lists,

1291etc.). Alignments are not supported, nor are cells that span multiple

1292columns or rows. Grid tables can be created easily using [Emacs table mode].

1293

1294 [Emacs table mode]: http://table.sourceforge.net/

1295

1296

1297Title block

1298-----------

1299

1300*Pandoc extension*.

1301

1302If the file begins with a title block

1303

1304 % title

1305 % author(s) (separated by semicolons)

1306 % date

1307

1308it will be parsed as bibliographic information, not regular text. (It

1309will be used, for example, in the title of standalone LaTeX or HTML

1310output.) The block may contain just a title, a title and an author,

1311or all three elements. If you want to include an author but no

1312title, or a title and a date but no author, you need a blank line:

1313

1314 %

1315 % Author

1316

1317 % My title

1318 %

1319 % June 15, 2006

1320

1321The title may occupy multiple lines, but continuation lines must

1322begin with leading space, thus:

1323

1324 % My title

1325 on multiple lines

1326

1327If a document has multiple authors, the authors may be put on

1328separate lines with leading space, or separated by semicolons, or

1329both. So, all of the following are equivalent:

1330

1331 % Author One

1332 Author Two

1333

1334 % Author One; Author Two

1335

1336 % Author One;

1337 Author Two

1338

1339The date must fit on one line.

1340

1341All three metadata fields may contain standard inline formatting

1342(italics, links, footnotes, etc.).

1343

1344Title blocks will always be parsed, but they will affect the output only

1345when the `--standalone` (`-s`) option is chosen. In HTML output, titles

1346will appear twice: once in the document head -- this is the title that

1347will appear at the top of the window in a browser -- and once at the

1348beginning of the document body. The title in the document head can have

1349an optional prefix attached (`--title-prefix` or `-T` option). The title

1350in the body appears as an H1 element with class "title", so it can be

1351suppressed or reformatted with CSS. If a title prefix is specified with

1352`-T` and no title block appears in the document, the title prefix will

1353be used by itself as the HTML title.

1354

1355The man page writer extracts a title, man page section number, and

1356other header and footer information from the title line. The title

1357is assumed to be the first word on the title line, which may optionally

1358end with a (single-digit) section number in parentheses. (There should

1359be no space between the title and the parentheses.) Anything after

1360this is assumed to be additional footer and header text. A single pipe

1361character (`|`) should be used to separate the footer text from the header

1362text. Thus,

1363

1364 % PANDOC(1)

1365

1366will yield a man page with the title `PANDOC` and section 1.

1367

1368 % PANDOC(1) Pandoc User Manuals

1369

1370will also have "Pandoc User Manuals" in the footer.

1371

1372 % PANDOC(1) Pandoc User Manuals | Version 4.0

1373

1374will also have "Version 4.0" in the header.

1375

1376

1377Backslash escapes

1378-----------------

1379

1380Except inside a code block or inline code, any punctuation or space

1381character preceded by a backslash will be treated literally, even if it

1382would normally indicate formatting. Thus, for example, if one writes

1383

1384 *\*hello\**

1385

1386one will get

1387

1388 <em>*hello*</em>

1389

1390instead of

1391

1392 <strong>hello</strong>

1393

1394This rule is easier to remember than standard markdown's rule,

1395which allows only the following characters to be backslash-escaped:

1396

1397 \`*_{}[]()>#+-.!

1398

1399(However, if the `--strict` option is supplied, the standard

1400markdown rule will be used.)

1401

1402A backslash-escaped space is parsed as a nonbreaking space. It will

1403appear in TeX output as `~` and in HTML and XML as `\ ` or

1404`\ `.

1405

1406A backslash-escaped newline (i.e. a backslash occurring at the end of

1407a line) is parsed as a hard line break. It will appear in TeX output as

1408`\\` and in HTML as `<br />`. This is a nice alternative to

1409markdown's "invisible" way of indicating hard line breaks using

1410two trailing spaces on a line.

1411

1412Backslash escapes do not work in verbatim contexts.

1413

1414Smart punctuation

1415-----------------

1416

1417If the `--smart` option is specified, pandoc will produce typographically

1418correct output, converting straight quotes to curly quotes, `---` and `--`

1419to Em-dashes, and `...` to ellipses. Nonbreaking spaces are inserted after

1420certain abbreviations, such as "Mr."

1421

1422Note: if your LaTeX template uses the `csquotes` package, pandoc will

1423detect automatically this and use `\enquote{...}` for quoted text.

1424

1425Inline formatting

1426-----------------

1427

1428### Emphasis ###

1429

1430To *emphasize* some text, surround it with `*`s or `_`, like this:

1431

1432 This text is _emphasized with underscores_, and this

1433 is *emphasized with asterisks*.

1434

1435Double `*` or `_` produces **strong emphasis**:

1436

1437 This is **strong emphasis** and __with underscores__.

1438

1439A `*` or `_` character surrounded by spaces, or backslash-escaped,

1440will not trigger emphasis:

1441

1442 This is * not emphasized *, and \*neither is this\*.

1443

1444Because `_` is sometimes used inside words and identifiers,

1445pandoc does not interpret a `_` surrounded by alphanumeric

1446characters as an emphasis marker. If you want to emphasize

1447just part of a word, use `*`:

1448

1449 feas*ible*, not feas*able*.

1450

1451

1452### Strikeout ###

1453

1454*Pandoc extension*.

1455

1456To strikeout a section of text with a horizontal line, begin and end it

1457with `~~`. Thus, for example,

1458

1459 This ~~is deleted text.~~

1460

1461

1462### Superscripts and subscripts ###

1463

1464*Pandoc extension*.

1465

1466Superscripts may be written by surrounding the superscripted text by `^`

1467characters; subscripts may be written by surrounding the subscripted

1468text by `~` characters. Thus, for example,

1469

1470 H~2~O is a liquid. 2^10^ is 1024.

1471

1472If the superscripted or subscripted text contains spaces, these spaces

1473must be escaped with backslashes. (This is to prevent accidental

1474superscripting and subscripting through the ordinary use of `~` and `^`.)

1475Thus, if you want the letter P with 'a cat' in subscripts, use

1476`P~a\ cat~`, not `P~a cat~`.

1477

1478

1479### Verbatim ###

1480

1481To make a short span of text verbatim, put it inside backticks:

1482

1483 What is the difference between `>>=` and `>>`?

1484

1485If the verbatim text includes a backtick, use double backticks:

1486

1487 Here is a literal backtick `` ` ``.

1488

1489(The spaces after the opening backticks and before the closing

1490backticks will be ignored.)

1491

1492The general rule is that a verbatim span starts with a string

1493of consecutive backticks (optionally followed by a space)

1494and ends with a string of the same number of backticks (optionally

1495preceded by a space).

1496

1497Note that backslash-escapes (and other markdown constructs) do not

1498work in verbatim contexts:

1499

1500 This is a backslash followed by an asterisk: `\*`.

1501

1502

1503Math

1504----

1505

1506*Pandoc extension*.

1507

1508Anything between two `$` characters will be treated as TeX math. The

1509opening `$` must have a character immediately to its right, while the

1510closing `$` must have a character immediately to its left. Thus,

1511`$20,000 and $30,000` won't parse as math. If for some reason

1512you need to enclose text in literal `$` characters, backslash-escape

1513them and they won't be treated as math delimiters.

1514

1515TeX math will be printed in all output formats. How it is rendered

1516depends on the output format:

1517

1518Markdown, reStructuredText, LaTeX, Org-Mode, ConTeXt

1519 ~ It will appear verbatim between `$` characters.

1520

1521reStructuredText

1522 ~ It will be rendered using an interpreted text role `:math:`, as described

1523 [here](http://www.american.edu/econ/itex2mml/mathhack.rst).

1524

1525AsciiDoc

1526 ~ It will be rendered as `latexmath:[...]`.

1527

1528Texinfo

1529 ~ It will be rendered inside a `@math` command.

1530

1531groff man

1532 ~ It will be rendered verbatim without `$`'s.

1533

1534MediaWiki

1535 ~ It will be rendered inside `<math>` tags.

1536

1537Textile

1538 ~ It will be rendered inside `<span class="math">` tags.

1539

1540RTF, DocBook, OpenDocument, ODT

1541 ~ It will be rendered, if possible, using unicode characters,

1542 and will otherwise appear verbatim.

1543

1544HTML, Slidy, DZSlides, S5, EPUB

1545 ~ The way math is rendered in HTML will depend on the

1546 command-line options selected:

1547

1548 1. The default is to render TeX math as far as possible using unicode

1549 characters, as with RTF, DocBook, and OpenDocument output. Formulas

1550 are put inside a `span` with `class="math"`, so that they may be

1551 styled differently from the surrounding text if needed.

1552

1553 2. If the `--latexmathml` option is used, TeX math will be displayed

1554 between $ or $$ characters and put in `<span>` tags with class `LaTeX`.

1555 The [LaTeXMathML] script will be used to render it as formulas.

1556 (This trick does not work in all browsers, but it works in Firefox.

1557 In browsers that do not support LaTeXMathML, TeX math will appear

1558 verbatim between $ characters.)

1559

1560 3. If the `--jsmath` option is used, TeX math will be put inside

1561 `<span>` tags (for inline math) or `<div>` tags (for display math)

1562 with class `math`. The [jsMath] script will be used to render

1563 it.

1564

1565 4. If the `--mimetex` option is used, the [mimeTeX] CGI script will

1566 be called to generate images for each TeX formula. This should

1567 work in all browsers. The `--mimetex` option takes an optional URL

1568 as argument. If no URL is specified, it will be assumed that the

1569 mimeTeX CGI script is at `/cgi-bin/mimetex.cgi`.

1570

1571 5. If the `--gladtex` option is used, TeX formulas will be enclosed

1572 in `<eq>` tags in the HTML output. The resulting `htex` file may then

1573 be processed by [gladTeX], which will produce image files for each

1574 formula and an `html` file with links to these images. So, the

1575 procedure is:

1576

1577 pandoc -s --gladtex myfile.txt -o myfile.htex

1578 gladtex -d myfile-images myfile.htex

1579 # produces myfile.html and images in myfile-images

1580

1581 6. If the `--webtex` option is used, TeX formulas will be converted

1582 to `<img>` tags that link to an external script that converts

1583 formulas to images. The formula will be URL-encoded and concatenated

1584 with the URL provided. If no URL is specified, the Google Chart

1585 API will be used (`http://chart.apis.google.com/chart?cht=tx&chl=`).

1586

1587

1588Raw HTML

1589--------

1590

1591Markdown allows you to insert raw HTML (or DocBook) anywhere in a document

1592(except verbatim contexts, where `<`, `>`, and `&` are interpreted

1593literally).

1594

1595The raw HTML is passed through unchanged in HTML, S5, Slidy, DZSlides, EPUB,

1596Markdown, and Textile output, and suppressed in other formats.

1597

1598*Pandoc extension*.

1599

1600Standard markdown allows you to include HTML "blocks": blocks

1601of HTML between balanced tags that are separated from the surrounding text

1602with blank lines, and start and end at the left margin. Within

1603these blocks, everything is interpreted as HTML, not markdown;

1604so (for example), `*` does not signify emphasis.

1605

1606Pandoc behaves this way when `--strict` is specified; but by default,

1607pandoc interprets material between HTML block tags as markdown.

1608Thus, for example, Pandoc will turn

1609

1610 <table>

1611 <tr>

1612 <td>*one*</td>

1613 <td>[a link](http://google.com)</td>

1614 </tr>

1615 </table>

1616

1617into

1618

1619 <table>

1620 <tr>

1621 <td><em>one</em></td>

1622 <td><a href="http://google.com">a link</a></td>

1623 </tr>

1624 </table>

1625

1626whereas `Markdown.pl` will preserve it as is.

1627

1628There is one exception to this rule: text between `<script>` and

1629`<style>` tags is not interpreted as markdown.

1630

1631This departure from standard markdown should make it easier to mix

1632markdown with HTML block elements. For example, one can surround

1633a block of markdown text with `<div>` tags without preventing it

1634from being interpreted as markdown.

1635

1636Raw TeX

1637-------

1638

1639*Pandoc extension*.

1640

1641In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be

1642included in a document. Inline TeX commands will be preserved and passed

1643unchanged to the LaTeX and ConTeXt writers. Thus, for example, you can use

1644LaTeX to include BibTeX citations:

1645

1646 This result was proved in \cite{jones.1967}.

1647

1648Note that in LaTeX environments, like

1649

1650 \begin{tabular}{|l|l|}\hline

1651 Age & Frequency \\ \hline

1652 18--25 & 15 \\

1653 26--35 & 33 \\

1654 36--45 & 22 \\ \hline

1655 \end{tabular}

1656

1657the material between the begin and end tags will be interpreted as raw

1658LaTeX, not as markdown.

1659

1660Inline LaTeX is ignored in output formats other than Markdown, LaTeX,

1661and ConTeXt.

1662

1663### Macros ###

1664

1665For output formats other than LaTeX, pandoc will parse LaTeX `\newcommand` and

1666`\renewcommand` definitions and apply the resulting macros to all LaTeX

1667math. So, for example, the following will work in all output formats,

1668not just LaTeX:

1669

1670 \newcommand{\tuple}[1]{\langle #1 \rangle}

1671

1672 $\tuple{a, b, c}$

1673

1674In LaTeX output, the `\newcommand` definition will simply be passed

1675unchanged to the output.

1676

1677

1678Links

1679-----

1680

1681Markdown allows links to be specified in several ways.

1682

1683### Automatic links ###

1684

1685If you enclose a URL or email address in pointy brackets, it

1686will become a link:

1687

1688 <http://google.com>

1689 <sam@green.eggs.ham>

1690

1691

1692### Inline links ###

1693

1694An inline link consists of the link text in square brackets,

1695followed by the URL in parentheses. (Optionally, the URL can

1696be followed by a link title, in quotes.)

1697

1698 This is an [inline link](/url), and here's [one with

1699 a title](http://fsf.org "click here for a good time!").

1700

1701There can be no space between the bracketed part and the parenthesized part.

1702The link text can contain formatting (such as emphasis), but the title cannot.

1703

1704

1705### Reference links ###

1706

1707An *explicit* reference link has two parts, the link itself and the link

1708definition, which may occur elsewhere in the document (either

1709before or after the link).

1710

1711The link consists of link text in square brackets, followed by a label in

1712square brackets. (There can be space between the two.) The link definition

1713must begin at the left margin or indented no more than three spaces. It

1714consists of the bracketed label, followed by a colon and a space, followed by

1715the URL, and optionally (after a space) a link title either in quotes or in

1716parentheses.

1717

1718Here are some examples:

1719

1720 [my label 1]: /foo/bar.html "My title, optional"

1721 [my label 2]: /foo

1722 [my label 3]: http://fsf.org (The free software foundation)

1723 [my label 4]: /bar#special 'A title in single quotes'

1724

1725The URL may optionally be surrounded by angle brackets:

1726

1727 [my label 5]: <http://foo.bar.baz>

1728

1729The title may go on the next line:

1730

1731 [my label 3]: http://fsf.org

1732 "The free software foundation"

1733

1734Note that link labels are not case sensitive. So, this will work:

1735

1736 Here is [my link][FOO]

1737

1738 [Foo]: /bar/baz

1739

1740In an *implicit* reference link, the second pair of brackets is

1741empty, or omitted entirely:

1742

1743 See [my website][], or [my website].

1744

1745 [my website]: http://foo.bar.baz

1746

1747

1748Images

1749------

1750

1751A link immediately preceded by a `!` will be treated as an image.

1752The link text will be used as the image's alt text:

1753

1754 ![la lune](lalune.jpg "Voyage to the moon")

1755

1756 ![movie reel]

1757

1758 [movie reel]: movie.gif

1759

1760### Pictures with captions ###

1761

1762*Pandoc extension*.

1763

1764An image occurring by itself in a paragraph will be rendered as

1765a figure with a caption.[^5] (In LaTeX, a figure environment will be

1766used; in HTML, the image will be placed in a `div` with class

1767`figure`, together with a caption in a `p` with class `caption`.)

1768The image's alt text will be used as the caption.

1769

1770 ![This is the caption](/url/of/image.png)

1771

1772[^5]: This feature is not yet implemented for RTF, OpenDocument, or

1773 ODT. In those formats, you'll just get an image in a paragraph by

1774 itself, with no caption.

1775

1776If you just want a regular inline image, just make sure it is not

1777the only thing in the paragraph. One way to do this is to insert a

1778nonbreaking space after the image:

1779

1780 ![This image won't be a figure](/url/of/image.png)\

1781

1782

1783Footnotes

1784---------

1785

1786*Pandoc extension*.

1787

1788Pandoc's markdown allows footnotes, using the following syntax:

1789

1790 Here is a footnote reference,[^1] and another.[^longnote]

1791

1792 [^1]: Here is the footnote.

1793

1794 [^longnote]: Here's one with multiple blocks.

1795

1796 Subsequent paragraphs are indented to show that they

1797 belong to the previous footnote.

1798

1799 { some.code }

1800

1801 The whole paragraph can be indented, or just the first

1802 line. In this way, multi-paragraph footnotes work like

1803 multi-paragraph list items.

1804

1805 This paragraph won't be part of the note, because it

1806 isn't indented.

1807

1808The identifiers in footnote references may not contain spaces, tabs,

1809or newlines. These identifiers are used only to correlate the

1810footnote reference with the note itself; in the output, footnotes

1811will be numbered sequentially.

1812

1813The footnotes themselves need not be placed at the end of the

1814document. They may appear anywhere except inside other block elements

1815(lists, block quotes, tables, etc.).

1816

1817Inline footnotes are also allowed (though, unlike regular notes,

1818they cannot contain multiple paragraphs). The syntax is as follows:

1819

1820 Here is an inline note.^[Inlines notes are easier to write, since

1821 you don't have to pick an identifier and move down to type the

1822 note.]

1823

1824Inline and regular footnotes may be mixed freely.

1825

1826

1827Citations

1828---------

1829

1830*Pandoc extension*.

1831

1832Pandoc can automatically generate citations and a bibliography in a number of

1833styles (using Andrea Rossato's `hs-citeproc`). In order to use this feature,

1834you will need a bibliographic database in one of the following formats:

1835

1836 Format File extension

1837 ------------ --------------

1838 MODS .mods

1839 BibTeX/BibLaTeX .bib

1840 RIS .ris

1841 EndNote .enl

1842 EndNote XML .xml

1843 ISI .wos

1844 MEDLINE .medline

1845 Copac .copac

1846 JSON citeproc .json

1847

1848You will need to specify the bibliography file using the `--bibliography`

1849command-line option (which may be repeated if you have several

1850bibliographies).

1851

1852By default, pandoc will use a Chicago author-date format for citations

1853and references. To use another style, you will need to use the

1854`--csl` option to specify a [CSL] 1.0 style file. A primer on

1855creating and modifying CSL styles can be found at

1856<http://citationstyles.org/downloads/primer.html>.

1857A repository of CSL styles can be found at

1858<https://github.com/citation-style-language/styles>.

1859See also <http://zotero.org/styles> for easy browsing.

1860

1861Citations go inside square brackets and are separated by semicolons.

1862Each citation must have a key, composed of '@' + the citation

1863identifier from the database, and may optionally have a prefix,

1864a locator, and a suffix. Here are some examples:

1865

1866 Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].

1867

1868 Blah blah [@doe99, pp. 33-35, 38-39 and *passim*].

1869

1870 Blah blah [@smith04; @doe99].

1871

1872A minus sign (`-`) before the `@` will suppress mention of

1873the author in the citation. This can be useful when the

1874author is already mentioned in the text:

1875

1876 Smith says blah [-@smith04].

1877

1878You can also write an in-text citation, as follows:

1879

1880 @smith04 says blah.

1881

1882 @smith04 [p. 33] says blah.

1883

1884If the style calls for a list of works cited, it will be placed

1885at the end of the document. Normally, you will want to end your

1886document with an appropriate header:

1887

1888 last paragraph...

1889

1890 # References

1891

1892The bibliography will be inserted after this header.

1893

1894

1895Producing HTML slide shows with Pandoc

1896======================================

1897

1898You can use Pandoc to produce an HTML + javascript slide presentation

1899that can be viewed via a web browser. There are three ways to do this,

1900using [S5], [DZSlides], or [Slidy].

1901

1902Here's the markdown source for a simple slide show, `eating.txt`:

1903

1904 % Eating Habits

1905 % John Doe

1906 % March 22, 2005

1907

1908 # In the morning

1909

1910 - Eat eggs

1911 - Drink coffee

1912

1913 # In the evening

1914

1915 - Eat spaghetti

1916 - Drink wine

1917

1918 --------------------------

1919

1920 ![picture of spaghetti](images/spaghetti.jpg)

1921

1922To produce the slide show, simply type

1923

1924 pandoc -w s5 -s eating.txt > eating.html

1925

1926for S5, or

1927

1928 pandoc -w slidy -s eating.txt > eating.html

1929

1930for Slidy, or

1931

1932 pandoc -w dzslides -s eating.txt > eating.html

1933

1934for DZSlides.

1935

1936A title page is constructed automatically from the document's title

1937block. Each level-one header and horizontal rule begins a new slide.

1938

1939For Slidy and S5, the file produced by pandoc with the `-s/--standalone`

1940option embeds a link to javascripts and CSS files, which are assumed to

1941be available at the relative path `s5/default` (for S5) or at the Slidy

1942website at `w3.org` (for Slidy). (These paths can be changed by setting

1943the `slidy-url` or `s5-url` variables; see `--variable`, above.) For DZSlides,

1944the (relatively short) javascript and css are included in the file by default.

1945

1946You can change the style of the slides by putting customized CSS files

1947in `$DATADIR/s5/default` (for S5) or `$DATADIR/slidy` (for Slidy),

1948where `$DATADIR` is the user data directory (see `--data-dir`, above).

1949The originals may be found in pandoc's system data directory (generally

1950`$CABALDIR/pandoc-VERSION/s5/default`). Pandoc will look there for any

1951files it does not find in the user data directory.

1952

1953The `--self-contained` option can be used to produce a single file that

1954contains all of the data necessary to display the slide show, including

1955linked scripts, stylesheets, images, and videos.

1956

1957Incremental lists

1958-----------------

1959

1960By default, these writers produces lists that display "all at once."

1961If you want your lists to display incrementally (one item at a time),

1962use the `-i` option. If you want a particular list to depart from the

1963default (that is, to display incrementally without the `-i` option and

1964all at once with the `-i` option), put it in a block quote:

1965

1966 > - Eat spaghetti

1967 > - Drink wine

1968

1969In this way incremental and nonincremental lists can be mixed in

1970a single document.

1971

1972Literate Haskell support

1973========================

1974

1975If you append `+lhs` to an appropriate input or output format (`markdown`,

1976`rst`, or `latex` for input or output; `html` for output only), pandoc

1977will treat the document as literate Haskell source. This means that

1978

1979 - In markdown input, "bird track" sections will be parsed as Haskell

1980 code rather than block quotations. Text between `\begin{code}`

1981 and `\end{code}` will also be treated as Haskell code.

1982

1983 - In markdown output, code blocks with class `haskell` will be

1984 rendered using bird tracks, and block quotations will be

1985 indented one space, so they will not be treated as Haskell code.

1986 In addition, headers will be rendered setext-style (with underlines)

1987 rather than atx-style (with '#' characters). (This is because ghc

1988 treats '#' characters in column 1 as introducing line numbers.)

1989

1990 - In restructured text input, "bird track" sections will be parsed

1991 as Haskell code.

1992

1993 - In restructured text output, code blocks with class `haskell` will

1994 be rendered using bird tracks.

1995

1996 - In LaTeX input, text in `code` environments will be parsed as

1997 Haskell code.

1998

1999 - In LaTeX output, code blocks with class `haskell` will be rendered

2000 inside `code` environments.

2001

2002 - In HTML output, code blocks with class `haskell` will be rendered

2003 with class `literatehaskell` and bird tracks.

2004

2005Examples:

2006

2007 pandoc -f markdown+lhs -t html

2008

2009reads literate Haskell source formatted with markdown conventions and writes

2010ordinary HTML (without bird tracks).

2011

2012 pandoc -f markdown+lhs -t html+lhs

2013

2014writes HTML with the Haskell code in bird tracks, so it can be copied

2015and pasted as literate Haskell source.

2016

2017Authors

2018=======

2019

2021[GPL], version 2 or greater. This software carries no warranty of

2022any kind. (See COPYRIGHT for full copyright and warranty notices.)

2023Other contributors include Recai Oktaş, Paulo Tanimoto, Peter Wang,

2024Andrea Rossato, Eric Kow, infinity0x, Luke Plant, shreevatsa.public,

2025Puneeth Chaganti, Paul Rivier, rodja.trappe, Bradley Kuhn, thsutton,

2026Nathan Gass, Jonathan Daugherty, Jérémy Bobbio, Justin Bogner, qerub,

2027Christopher Sawicki, Kelsey Hightower.

2028

2029[markdown]: http://daringfireball.net/projects/markdown/

2030[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html

2031[S5]: http://meyerweb.com/eric/tools/s5/

2032[Slidy]: http://www.w3.org/Talks/Tools/Slidy/

2033[HTML]: http://www.w3.org/TR/html40/

2034[LaTeX]: http://www.latex-project.org/

2035[ConTeXt]: http://www.pragma-ade.nl/

2036[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format

2037[DocBook XML]: http://www.docbook.org/

2038[OpenDocument XML]: http://opendocument.xml.org/

2039[ODT]: http://en.wikipedia.org/wiki/OpenDocument

2040[Textile]: http://redcloth.org/textile

2041[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting

2042[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html

2043[Haskell]: http://www.haskell.org/

2044[GNU Texinfo]: http://www.gnu.org/software/texinfo/

2045[Emacs Org-Mode]: http://orgmode.org

2046[AsciiDoc]: http://www.methods.co.nz/asciidoc/

2047[EPUB]: http://www.idpf.org/

2048[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"

2049[DZSlides]: http://paulrouget.com/dzslides/

2050