README · typeable/pandoc

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

1085

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

1087

1088

1089### Numbered example lists ###

1090

1091*Pandoc extension*.

1092

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

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

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

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

1097where the last stopped. So, for example:

1098

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

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

1101

1102 Explanation of examples.

1103

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

1105

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

1107document:

1108

1109 (@good) This is a good example.

1110

1111 As (@good) illustrates, ...

1112

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

1114or hyphens.

1115

1116

1117### Compact and loose lists ###

1118

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

1120cases" involving lists. Consider this source:

1121

1122 + First

1123 + Second:

1124 - Fee

1125 - Fie

1126 - Foe

1127

1128 + Third

1129

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

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

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

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

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

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

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

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

1138behavior is consistent with the official markdown syntax description,

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

1140

1141

1142### Ending a list ###

1143

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

1145

1146 - item one

1147 - item two

1148

1149 { my code block }

1150

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

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

1153a code block.

1154

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

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

1157any format:

1158

1159 - item one

1160 - item two

1161

1162

1163

1164 { my code block }

1165

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

1167of one big list:

1168

1169 1. one

1170 2. two

1171 3. three

1172

1173

1174

1175 a. uno

1176 b. dos

1177 c. tres

1178

1179

1180Horizontal rules

1181----------------

1182

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

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

1186 * * * *

1188 ---------------

1191Tables

1192------

1193

1194*Pandoc extension*.

1195

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

1197a fixed-width font, such as Courier.

1198

1199**Simple tables** look like this:

1200

1201 Right Left Center Default

1202 ------- ------ ---------- -------

1203 12 12 12 12

1204 123 123 123 123

1205 1 1 1 1

1206

1207 Table: Demonstration of simple table syntax.

1208

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

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

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

1212

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

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

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

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

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

1218 the column is centered.

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

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

1221

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

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

1224

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

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

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

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

1229before or after the table.

1230

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

1232to end the table. For example:

1233

1234 ------- ------ ---------- -------

1235 12 12 12 12

1236 123 123 123 123

1237 1 1 1 1

1238 ------- ------ ---------- -------

1239

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

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

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

1243

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

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

1246not supported). Here is an example:

1247

1248 -------------------------------------------------------------

1249 Centered Default Right Left

1250 Header Aligned Aligned Aligned

1251 ----------- ------- --------------- -------------------------

1252 First row 12.0 Example of a row that

1253 spans multiple lines.

1254

1255 Second row 5.0 Here's another one. Note

1256 the blank line between

1257 rows.

1258 -------------------------------------------------------------

1259

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

1261 multiple lines.

1262

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

1264

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

1266 (unless the headers are omitted).

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

1268 - The rows must be separated by blank lines.

1269

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

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

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

1273output, try widening it in the markdown source.

1274

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

1276

1277 ----------- ------- --------------- -------------------------

1278 First row 12.0 Example of a row that

1279 spans multiple lines.

1280

1281 Second row 5.0 Here's another one. Note

1282 the blank line between

1283 rows.

1284 -------------------------------------------------------------

1285

1286 : Here's a multiline table without headers.

1287

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

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

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

1291

1292**Grid tables** look like this:

1293

1294 : Sample grid table.

1295

1296 +---------------+---------------+--------------------+

1297 | Fruit | Price | Advantages |

1298 +===============+===============+====================+

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

1300 | | | - bright color |

1301 +---------------+---------------+--------------------+

1302 | Oranges | $2.10 | - cures scurvy |

1303 | | | - tasty |

1304 +---------------+---------------+--------------------+

1305

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

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

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

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

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

1311

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

1313

1314

1315Title block

1316-----------

1317

1318*Pandoc extension*.

1319

1320If the file begins with a title block

1321

1322 % title

1323 % author(s) (separated by semicolons)

1324 % date

1325

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

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

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

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

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

1331

1332 %

1333 % Author

1334

1335 % My title

1336 %

1337 % June 15, 2006

1338

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

1340begin with leading space, thus:

1341

1342 % My title

1343 on multiple lines

1344

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

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

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

1348

1349 % Author One

1350 Author Two

1351

1352 % Author One; Author Two

1353

1354 % Author One;

1355 Author Two

1356

1357The date must fit on one line.

1358

1359All three metadata fields may contain standard inline formatting

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

1361

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

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

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

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

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

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

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

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

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

1371be used by itself as the HTML title.

1372

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

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

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

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

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

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

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

1380text. Thus,

1381

1382 % PANDOC(1)

1383

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

1385

1386 % PANDOC(1) Pandoc User Manuals

1387

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

1389

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

1391

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

1393

1394

1395Backslash escapes

1396-----------------

1397

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

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

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

1401

1402 *\*hello\**

1403

1404one will get

1405

1406 <em>*hello*</em>

1407

1408instead of

1409

1410 <strong>hello</strong>

1411

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

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

1414

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

1416

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

1418markdown rule will be used.)

1419

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

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

1422`\ `.

1423

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

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

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

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

1428two trailing spaces on a line.

1429

1430Backslash escapes do not work in verbatim contexts.

1431

1432Smart punctuation

1433-----------------

1434

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

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

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

1438certain abbreviations, such as "Mr."

1439

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

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

1442

1443Inline formatting

1444-----------------

1445

1446### Emphasis ###

1447

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

1449

1450 This text is _emphasized with underscores_, and this

1451 is *emphasized with asterisks*.

1452

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

1454

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

1456

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

1458will not trigger emphasis:

1459

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

1461

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

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

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

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

1466

1467 feas*ible*, not feas*able*.

1468

1469

1470### Strikeout ###

1471

1472*Pandoc extension*.

1473

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

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

1476

1477 This ~~is deleted text.~~

1478

1479

1480### Superscripts and subscripts ###

1481

1482*Pandoc extension*.

1483

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

1485characters; subscripts may be written by surrounding the subscripted

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

1487

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

1489

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

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

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

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

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

1495

1496

1497### Verbatim ###

1498

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

1500

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

1502

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

1504

1505 Here is a literal backtick `` ` ``.

1506

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

1508backticks will be ignored.)

1509

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

1511of consecutive backticks (optionally followed by a space)

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

1513preceded by a space).

1514

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

1516work in verbatim contexts:

1517

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

1519

1520

1521Math

1522----

1523

1524*Pandoc extension*.

1525

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

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

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

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

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

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

1532

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

1534depends on the output format:

1535

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

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

1538

1539reStructuredText

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

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

1542

1543AsciiDoc

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

1545

1546Texinfo

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

1548

1549groff man

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

1551

1552MediaWiki

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

1554

1555Textile

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

1557

1558RTF, DocBook, OpenDocument, ODT

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

1560 and will otherwise appear verbatim.

1561

1562HTML, Slidy, DZSlides, S5, EPUB

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

1564 command-line options selected:

1565

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

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

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

1569 styled differently from the surrounding text if needed.

1570

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

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

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

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

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

1576 verbatim between $ characters.)

1577

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

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

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

1581 it.

1582

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

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

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

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

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

1588

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

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

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

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

1593 procedure is:

1594

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

1596 gladtex -d myfile-images myfile.htex

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

1598

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

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

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

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

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

1604

1605

1606Raw HTML

1607--------

1608

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

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

1611literally).

1612

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

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

1615

1616*Pandoc extension*.

1617

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

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

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

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

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

1623

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

1625pandoc interprets material between HTML block tags as markdown.

1626Thus, for example, Pandoc will turn

1627

1628 <table>

1629 <tr>

1630 <td>*one*</td>

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

1632 </tr>

1633 </table>

1634

1635into

1636

1637 <table>

1638 <tr>

1639 <td><em>one</em></td>

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

1641 </tr>

1642 </table>

1643

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

1645

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

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

1648

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

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

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

1652from being interpreted as markdown.

1653

1654Raw TeX

1655-------

1656

1657*Pandoc extension*.

1658

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

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

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

1662LaTeX to include BibTeX citations:

1663

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

1665

1666Note that in LaTeX environments, like

1667

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

1669 Age & Frequency \\ \hline

1670 18--25 & 15 \\

1671 26--35 & 33 \\

1672 36--45 & 22 \\ \hline

1673 \end{tabular}

1674

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

1676LaTeX, not as markdown.

1677

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

1679and ConTeXt.

1680

1681### Macros ###

1682

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

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

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

1686not just LaTeX:

1687

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

1689

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

1691

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

1693unchanged to the output.

1694

1695

1696Links

1697-----

1698

1699Markdown allows links to be specified in several ways.

1700

1701### Automatic links ###

1702

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

1704will become a link:

1705

1706 <http://google.com>

1707 <sam@green.eggs.ham>

1708

1709

1710### Inline links ###

1711

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

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

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

1715

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

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

1718

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

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

1721

1722

1723### Reference links ###

1724

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

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

1727before or after the link).

1728

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

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

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

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

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

1734parentheses.

1735

1736Here are some examples:

1737

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

1739 [my label 2]: /foo

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

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

1742

1743The URL may optionally be surrounded by angle brackets:

1744

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

1746

1747The title may go on the next line:

1748

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

1750 "The free software foundation"

1751

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

1753

1754 Here is [my link][FOO]

1755

1756 [Foo]: /bar/baz

1757

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

1759empty, or omitted entirely:

1760

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

1762

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

1764

1765

1766Images

1767------

1768

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

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

1771

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

1773

1774 ![movie reel]

1775

1776 [movie reel]: movie.gif

1777

1778### Pictures with captions ###

1779

1780*Pandoc extension*.

1781

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

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

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

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

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

1787

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

1789

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

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

1792 itself, with no caption.

1793

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

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

1796nonbreaking space after the image:

1797

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

1799

1800

1801Footnotes

1802---------

1803

1804*Pandoc extension*.

1805

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

1807

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

1809

1810 [^1]: Here is the footnote.

1811

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

1813

1814 Subsequent paragraphs are indented to show that they

1815 belong to the previous footnote.

1816

1817 { some.code }

1818

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

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

1821 multi-paragraph list items.

1822

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

1824 isn't indented.

1825

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

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

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

1829will be numbered sequentially.

1830

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

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

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

1834

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

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

1837

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

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

1840 note.]

1841

1842Inline and regular footnotes may be mixed freely.

1843

1844

1845Citations

1846---------

1847

1848*Pandoc extension*.

1849

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

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

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

1853

1854 Format File extension

1855 ------------ --------------

1856 MODS .mods

1857 BibTeX/BibLaTeX .bib

1858 RIS .ris

1859 EndNote .enl

1860 EndNote XML .xml

1861 ISI .wos

1862 MEDLINE .medline

1863 Copac .copac

1864 JSON citeproc .json

1865

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

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

1868bibliographies).

1869

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

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

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

1873creating and modifying CSL styles can be found at

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

1875A repository of CSL styles can be found at

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

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

1878

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

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

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

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

1883

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

1885

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

1887

1888 Blah blah [@smith04; @doe99].

1889

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

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

1892author is already mentioned in the text:

1893

1894 Smith says blah [-@smith04].

1895

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

1897

1898 @smith04 says blah.

1899

1900 @smith04 [p. 33] says blah.

1901

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

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

1904document with an appropriate header:

1905

1906 last paragraph...

1907

1908 # References

1909

1910The bibliography will be inserted after this header.

1911

1912

1913Producing slide shows with Pandoc

1914=================================

1915

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

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

1918using [S5], [DZSlides], or [Slidy]. You can also produce a PDF slide

1919show using [LaTeX beamer]: just pass the `--beamer` option to

1920`markdown2pdf`.

1921

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

1923

1924 % Eating Habits

1925 % John Doe

1926 % March 22, 2005

1927

1928 # In the morning

1929

1930 - Eat eggs

1931 - Drink coffee

1932

1933 # In the evening

1934

1935 - Eat spaghetti

1936 - Drink wine

1937

1938 --------------------------

1939

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

1941

1942To produce the slide show, simply type

1943

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

1945

1946for S5, or

1947

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

1949

1950for Slidy, or

1951

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

1953

1954for DZSlides.

1955

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

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

1958(If beamer is used, all headers begin a new slide.)

1959

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

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

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

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

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

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

1966

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

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

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

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

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

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

1973

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

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

1976linked scripts, stylesheets, images, and videos.

1977

1978Incremental lists

1979-----------------

1980

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

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

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

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

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

1986

1987 > - Eat spaghetti

1988 > - Drink wine

1989

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

1991a single document.

1992

1993Literate Haskell support

1994========================

1995

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

1997`rst`, or `latex` for input or output; `html` or `html5` for output only),

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

1999

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

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

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

2003

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

2005 rendered using bird tracks, and block quotations will be

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

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

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

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

2010

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

2012 as Haskell code.

2013

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

2015 be rendered using bird tracks.

2016

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

2018 Haskell code.

2019

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

2021 inside `code` environments.

2022

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

2024 with class `literatehaskell` and bird tracks.

2025

2026Examples:

2027

2028 pandoc -f markdown+lhs -t html

2029

2030reads literate Haskell source formatted with markdown conventions and writes

2031ordinary HTML (without bird tracks).

2032

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

2034

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

2036and pasted as literate Haskell source.

2037

2038Authors

2039=======

2040

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

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

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

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

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

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

2048Christopher Sawicki, Kelsey Hightower.

2049

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

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

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

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

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

2055[XHTML]: http://www.w3.org/TR/xhtml1/

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

2057[LaTeX beamer]: http://www.tex.ac.uk/CTAN/macros/latex/contrib/beamer

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2073