README · typeable/pandoc

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

1075

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

1077

1078

1079### Numbered example lists ###

1080

1081*Pandoc extension*.

1082

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

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

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

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

1087where the last stopped. So, for example:

1088

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

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

1091

1092 Explanation of examples.

1093

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

1095

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

1097document:

1098

1099 (@good) This is a good example.

1100

1101 As (@good) illustrates, ...

1102

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

1104or hyphens.

1105

1106

1107### Compact and loose lists ###

1108

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

1110cases" involving lists. Consider this source:

1111

1112 + First

1113 + Second:

1114 - Fee

1115 - Fie

1116 - Foe

1117

1118 + Third

1119

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

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

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

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

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

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

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

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

1128behavior is consistent with the official markdown syntax description,

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

1130

1131

1132### Ending a list ###

1133

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

1135

1136 - item one

1137 - item two

1138

1139 { my code block }

1140

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

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

1143a code block.

1144

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

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

1147any format:

1148

1149 - item one

1150 - item two

1151

1152

1153

1154 { my code block }

1155

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

1157of one big list:

1158

1159 1. one

1160 2. two

1161 3. three

1162

1163

1164

1165 a. uno

1166 b. dos

1167 c. tres

1168

1169

1170Horizontal rules

1171----------------

1172

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

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

1176 * * * *

1178 ---------------

1181Tables

1182------

1183

1184*Pandoc extension*.

1185

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

1187a fixed-width font, such as Courier.

1188

1189**Simple tables** look like this:

1190

1191 Right Left Center Default

1192 ------- ------ ---------- -------

1193 12 12 12 12

1194 123 123 123 123

1195 1 1 1 1

1196

1197 Table: Demonstration of simple table syntax.

1198

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

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

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

1202

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

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

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

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

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

1208 the column is centered.

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

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

1211

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

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

1214

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

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

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

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

1219before or after the table.

1220

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

1222to end the table. For example:

1223

1224 ------- ------ ---------- -------

1225 12 12 12 12

1226 123 123 123 123

1227 1 1 1 1

1228 ------- ------ ---------- -------

1229

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

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

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

1233

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

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

1236not supported). Here is an example:

1237

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

1239 Centered Default Right Left

1240 Header Aligned Aligned Aligned

1241 ----------- ------- --------------- -------------------------

1242 First row 12.0 Example of a row that

1243 spans multiple lines.

1244

1245 Second row 5.0 Here's another one. Note

1246 the blank line between

1247 rows.

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

1249

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

1251 multiple lines.

1252

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

1254

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

1256 (unless the headers are omitted).

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

1258 - The rows must be separated by blank lines.

1259

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

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

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

1263output, try widening it in the markdown source.

1264

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

1266

1267 ----------- ------- --------------- -------------------------

1268 First row 12.0 Example of a row that

1269 spans multiple lines.

1270

1271 Second row 5.0 Here's another one. Note

1272 the blank line between

1273 rows.

1274 -------------------------------------------------------------

1275

1276 : Here's a multiline table without headers.

1277

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

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

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

1281

1282**Grid tables** look like this:

1283

1284 : Sample grid table.

1285

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

1287 | Fruit | Price | Advantages |

1288 +===============+===============+====================+

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

1290 | | | - bright color |

1291 +---------------+---------------+--------------------+

1292 | Oranges | $2.10 | - cures scurvy |

1293 | | | - tasty |

1294 +---------------+---------------+--------------------+

1295

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

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

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

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

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

1301

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

1303

1304

1305Title block

1306-----------

1307

1308*Pandoc extension*.

1309

1310If the file begins with a title block

1311

1312 % title

1313 % author(s) (separated by semicolons)

1314 % date

1315

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

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

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

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

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

1321

1322 %

1323 % Author

1324

1325 % My title

1326 %

1327 % June 15, 2006

1328

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

1330begin with leading space, thus:

1331

1332 % My title

1333 on multiple lines

1334

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

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

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

1338

1339 % Author One

1340 Author Two

1341

1342 % Author One; Author Two

1343

1344 % Author One;

1345 Author Two

1346

1347The date must fit on one line.

1348

1349All three metadata fields may contain standard inline formatting

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

1351

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

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

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

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

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

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

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

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

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

1361be used by itself as the HTML title.

1362

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

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

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

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

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

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

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

1370text. Thus,

1371

1372 % PANDOC(1)

1373

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

1375

1376 % PANDOC(1) Pandoc User Manuals

1377

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

1379

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

1381

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

1383

1384

1385Backslash escapes

1386-----------------

1387

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

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

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

1391

1392 *\*hello\**

1393

1394one will get

1395

1396 <em>*hello*</em>

1397

1398instead of

1399

1400 <strong>hello</strong>

1401

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

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

1404

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

1406

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

1408markdown rule will be used.)

1409

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

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

1412`\ `.

1413

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

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

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

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

1418two trailing spaces on a line.

1419

1420Backslash escapes do not work in verbatim contexts.

1421

1422Smart punctuation

1423-----------------

1424

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

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

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

1428certain abbreviations, such as "Mr."

1429

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

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

1432

1433Inline formatting

1434-----------------

1435

1436### Emphasis ###

1437

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

1439

1440 This text is _emphasized with underscores_, and this

1441 is *emphasized with asterisks*.

1442

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

1444

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

1446

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

1448will not trigger emphasis:

1449

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

1451

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

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

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

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

1456

1457 feas*ible*, not feas*able*.

1458

1459

1460### Strikeout ###

1461

1462*Pandoc extension*.

1463

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

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

1466

1467 This ~~is deleted text.~~

1468

1469

1470### Superscripts and subscripts ###

1471

1472*Pandoc extension*.

1473

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

1475characters; subscripts may be written by surrounding the subscripted

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

1477

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

1479

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

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

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

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

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

1485

1486

1487### Verbatim ###

1488

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

1490

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

1492

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

1494

1495 Here is a literal backtick `` ` ``.

1496

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

1498backticks will be ignored.)

1499

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

1501of consecutive backticks (optionally followed by a space)

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

1503preceded by a space).

1504

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

1506work in verbatim contexts:

1507

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

1509

1510

1511Math

1512----

1513

1514*Pandoc extension*.

1515

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

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

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

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

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

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

1522

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

1524depends on the output format:

1525

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

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

1528

1529reStructuredText

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

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

1532

1533AsciiDoc

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

1535

1536Texinfo

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

1538

1539groff man

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

1541

1542MediaWiki

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

1544

1545Textile

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

1547

1548RTF, DocBook, OpenDocument, ODT

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

1550 and will otherwise appear verbatim.

1551

1552HTML, Slidy, DZSlides, S5, EPUB

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

1554 command-line options selected:

1555

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

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

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

1559 styled differently from the surrounding text if needed.

1560

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

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

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

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

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

1566 verbatim between $ characters.)

1567

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

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

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

1571 it.

1572

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

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

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

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

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

1578

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

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

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

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

1583 procedure is:

1584

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

1586 gladtex -d myfile-images myfile.htex

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

1588

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

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

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

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

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

1594

1595

1596Raw HTML

1597--------

1598

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

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

1601literally).

1602

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

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

1605

1606*Pandoc extension*.

1607

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

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

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

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

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

1613

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

1615pandoc interprets material between HTML block tags as markdown.

1616Thus, for example, Pandoc will turn

1617

1618 <table>

1619 <tr>

1620 <td>*one*</td>

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

1622 </tr>

1623 </table>

1624

1625into

1626

1627 <table>

1628 <tr>

1629 <td><em>one</em></td>

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

1631 </tr>

1632 </table>

1633

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

1635

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

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

1638

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

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

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

1642from being interpreted as markdown.

1643

1644Raw TeX

1645-------

1646

1647*Pandoc extension*.

1648

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

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

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

1652LaTeX to include BibTeX citations:

1653

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

1655

1656Note that in LaTeX environments, like

1657

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

1659 Age & Frequency \\ \hline

1660 18--25 & 15 \\

1661 26--35 & 33 \\

1662 36--45 & 22 \\ \hline

1663 \end{tabular}

1664

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

1666LaTeX, not as markdown.

1667

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

1669and ConTeXt.

1670

1671### Macros ###

1672

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

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

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

1676not just LaTeX:

1677

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

1679

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

1681

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

1683unchanged to the output.

1684

1685

1686Links

1687-----

1688

1689Markdown allows links to be specified in several ways.

1690

1691### Automatic links ###

1692

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

1694will become a link:

1695

1696 <http://google.com>

1697 <sam@green.eggs.ham>

1698

1699

1700### Inline links ###

1701

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

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

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

1705

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

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

1708

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

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

1711

1712

1713### Reference links ###

1714

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

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

1717before or after the link).

1718

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

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

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

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

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

1724parentheses.

1725

1726Here are some examples:

1727

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

1729 [my label 2]: /foo

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

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

1732

1733The URL may optionally be surrounded by angle brackets:

1734

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

1736

1737The title may go on the next line:

1738

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

1740 "The free software foundation"

1741

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

1743

1744 Here is [my link][FOO]

1745

1746 [Foo]: /bar/baz

1747

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

1749empty, or omitted entirely:

1750

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

1752

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

1754

1755

1756Images

1757------

1758

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

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

1761

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

1763

1764 ![movie reel]

1765

1766 [movie reel]: movie.gif

1767

1768### Pictures with captions ###

1769

1770*Pandoc extension*.

1771

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

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

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

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

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

1777

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

1779

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

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

1782 itself, with no caption.

1783

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

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

1786nonbreaking space after the image:

1787

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

1789

1790

1791Footnotes

1792---------

1793

1794*Pandoc extension*.

1795

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

1797

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

1799

1800 [^1]: Here is the footnote.

1801

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

1803

1804 Subsequent paragraphs are indented to show that they

1805 belong to the previous footnote.

1806

1807 { some.code }

1808

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

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

1811 multi-paragraph list items.

1812

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

1814 isn't indented.

1815

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

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

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

1819will be numbered sequentially.

1820

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

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

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

1824

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

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

1827

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

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

1830 note.]

1831

1832Inline and regular footnotes may be mixed freely.

1833

1834

1835Citations

1836---------

1837

1838*Pandoc extension*.

1839

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

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

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

1843

1844 Format File extension

1845 ------------ --------------

1846 MODS .mods

1847 BibTeX/BibLaTeX .bib

1848 RIS .ris

1849 EndNote .enl

1850 EndNote XML .xml

1851 ISI .wos

1852 MEDLINE .medline

1853 Copac .copac

1854 JSON citeproc .json

1855

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

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

1858bibliographies).

1859

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

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

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

1863creating and modifying CSL styles can be found at

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

1865A repository of CSL styles can be found at

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

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

1868

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

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

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

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

1873

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

1875

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

1877

1878 Blah blah [@smith04; @doe99].

1879

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

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

1882author is already mentioned in the text:

1883

1884 Smith says blah [-@smith04].

1885

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

1887

1888 @smith04 says blah.

1889

1890 @smith04 [p. 33] says blah.

1891

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

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

1894document with an appropriate header:

1895

1896 last paragraph...

1897

1898 # References

1899

1900The bibliography will be inserted after this header.

1901

1902

1903Producing HTML slide shows with Pandoc

1904======================================

1905

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

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

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

1909

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

1911

1912 % Eating Habits

1913 % John Doe

1914 % March 22, 2005

1915

1916 # In the morning

1917

1918 - Eat eggs

1919 - Drink coffee

1920

1921 # In the evening

1922

1923 - Eat spaghetti

1924 - Drink wine

1925

1926 --------------------------

1927

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

1929

1930To produce the slide show, simply type

1931

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

1933

1934for S5, or

1935

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

1937

1938for Slidy, or

1939

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

1941

1942for DZSlides.

1943

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

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

1946

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

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

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

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

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

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

1953

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

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

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

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

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

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

1960

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

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

1963linked scripts, stylesheets, images, and videos.

1964

1965Incremental lists

1966-----------------

1967

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

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

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

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

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

1973

1974 > - Eat spaghetti

1975 > - Drink wine

1976

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

1978a single document.

1979

1980Literate Haskell support

1981========================

1982

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

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

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

1986

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

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

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

1990

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

1992 rendered using bird tracks, and block quotations will be

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

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

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

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

1997

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

1999 as Haskell code.

2000

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

2002 be rendered using bird tracks.

2003

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

2005 Haskell code.

2006

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

2008 inside `code` environments.

2009

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

2011 with class `literatehaskell` and bird tracks.

2012

2013Examples:

2014

2015 pandoc -f markdown+lhs -t html

2016

2017reads literate Haskell source formatted with markdown conventions and writes

2018ordinary HTML (without bird tracks).

2019

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

2021

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

2023and pasted as literate Haskell source.

2024

2025Authors

2026=======

2027

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

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

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

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

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

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

2035Christopher Sawicki, Kelsey Hightower.

2036

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2058