README · typeable/pandoc

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

1093

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

1095

1096

1097### Numbered example lists ###

1098

1099*Pandoc extension*.

1100

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

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

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

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

1105where the last stopped. So, for example:

1106

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

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

1109

1110 Explanation of examples.

1111

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

1113

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

1115document:

1116

1117 (@good) This is a good example.

1118

1119 As (@good) illustrates, ...

1120

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

1122or hyphens.

1123

1124

1125### Compact and loose lists ###

1126

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

1128cases" involving lists. Consider this source:

1129

1130 + First

1131 + Second:

1132 - Fee

1133 - Fie

1134 - Foe

1135

1136 + Third

1137

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

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

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

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

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

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

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

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

1146behavior is consistent with the official markdown syntax description,

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

1148

1149

1150### Ending a list ###

1151

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

1153

1154 - item one

1155 - item two

1156

1157 { my code block }

1158

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

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

1161a code block.

1162

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

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

1165any format:

1166

1167 - item one

1168 - item two

1169

1170

1171

1172 { my code block }

1173

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

1175of one big list:

1176

1177 1. one

1178 2. two

1179 3. three

1180

1181

1182

1183 a. uno

1184 b. dos

1185 c. tres

1186

1187

1188Horizontal rules

1189----------------

1190

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

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

1194 * * * *

1196 ---------------

1199Tables

1200------

1201

1202*Pandoc extension*.

1203

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

1205a fixed-width font, such as Courier.

1206

1207**Simple tables** look like this:

1208

1209 Right Left Center Default

1210 ------- ------ ---------- -------

1211 12 12 12 12

1212 123 123 123 123

1213 1 1 1 1

1214

1215 Table: Demonstration of simple table syntax.

1216

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

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

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

1220

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

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

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

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

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

1226 the column is centered.

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

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

1229

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

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

1232

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

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

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

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

1237before or after the table.

1238

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

1240to end the table. For example:

1241

1242 ------- ------ ---------- -------

1243 12 12 12 12

1244 123 123 123 123

1245 1 1 1 1

1246 ------- ------ ---------- -------

1247

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

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

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

1251

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

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

1254not supported). Here is an example:

1255

1256 -------------------------------------------------------------

1257 Centered Default Right Left

1258 Header Aligned Aligned Aligned

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 Table: Here's the caption. It, too, may span

1269 multiple lines.

1270

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

1272

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

1274 (unless the headers are omitted).

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

1276 - The rows must be separated by blank lines.

1277

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

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

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

1281output, try widening it in the markdown source.

1282

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

1284

1285 ----------- ------- --------------- -------------------------

1286 First row 12.0 Example of a row that

1287 spans multiple lines.

1288

1289 Second row 5.0 Here's another one. Note

1290 the blank line between

1291 rows.

1292 -------------------------------------------------------------

1293

1294 : Here's a multiline table without headers.

1295

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

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

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

1299

1300**Grid tables** look like this:

1301

1302 : Sample grid table.

1303

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

1305 | Fruit | Price | Advantages |

1306 +===============+===============+====================+

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

1308 | | | - bright color |

1309 +---------------+---------------+--------------------+

1310 | Oranges | $2.10 | - cures scurvy |

1311 | | | - tasty |

1312 +---------------+---------------+--------------------+

1313

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

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

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

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

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

1319

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

1321

1322

1323Title block

1324-----------

1325

1326*Pandoc extension*.

1327

1328If the file begins with a title block

1329

1330 % title

1331 % author(s) (separated by semicolons)

1332 % date

1333

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

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

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

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

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

1339

1340 %

1341 % Author

1342

1343 % My title

1344 %

1345 % June 15, 2006

1346

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

1348begin with leading space, thus:

1349

1350 % My title

1351 on multiple lines

1352

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

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

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

1356

1357 % Author One

1358 Author Two

1359

1360 % Author One; Author Two

1361

1362 % Author One;

1363 Author Two

1364

1365The date must fit on one line.

1366

1367All three metadata fields may contain standard inline formatting

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

1369

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

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

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

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

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

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

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

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

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

1379be used by itself as the HTML title.

1380

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

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

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

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

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

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

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

1388text. Thus,

1389

1390 % PANDOC(1)

1391

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

1393

1394 % PANDOC(1) Pandoc User Manuals

1395

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

1397

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

1399

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

1401

1402

1403Backslash escapes

1404-----------------

1405

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

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

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

1409

1410 *\*hello\**

1411

1412one will get

1413

1414 <em>*hello*</em>

1415

1416instead of

1417

1418 <strong>hello</strong>

1419

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

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

1422

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

1424

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

1426markdown rule will be used.)

1427

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

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

1430`\ `.

1431

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

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

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

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

1436two trailing spaces on a line.

1437

1438Backslash escapes do not work in verbatim contexts.

1439

1440Smart punctuation

1441-----------------

1442

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

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

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

1446certain abbreviations, such as "Mr."

1447

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

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

1450

1451Inline formatting

1452-----------------

1453

1454### Emphasis ###

1455

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

1457

1458 This text is _emphasized with underscores_, and this

1459 is *emphasized with asterisks*.

1460

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

1462

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

1464

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

1466will not trigger emphasis:

1467

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

1469

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

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

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

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

1474

1475 feas*ible*, not feas*able*.

1476

1477

1478### Strikeout ###

1479

1480*Pandoc extension*.

1481

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

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

1484

1485 This ~~is deleted text.~~

1486

1487

1488### Superscripts and subscripts ###

1489

1490*Pandoc extension*.

1491

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

1493characters; subscripts may be written by surrounding the subscripted

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

1495

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

1497

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

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

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

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

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

1503

1504

1505### Verbatim ###

1506

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

1508

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

1510

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

1512

1513 Here is a literal backtick `` ` ``.

1514

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

1516backticks will be ignored.)

1517

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

1519of consecutive backticks (optionally followed by a space)

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

1521preceded by a space).

1522

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

1524work in verbatim contexts:

1525

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

1527

1528

1529Math

1530----

1531

1532*Pandoc extension*.

1533

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

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

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

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

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

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

1540

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

1542depends on the output format:

1543

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

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

1546

1547reStructuredText

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

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

1550

1551AsciiDoc

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

1553

1554Texinfo

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

1556

1557groff man

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

1559

1560MediaWiki

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

1562

1563Textile

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

1565

1566RTF, DocBook, OpenDocument, ODT

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

1568 and will otherwise appear verbatim.

1569

1570HTML, Slidy, DZSlides, S5, EPUB

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

1572 command-line options selected:

1573

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

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

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

1577 styled differently from the surrounding text if needed.

1578

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

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

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

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

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

1584 verbatim between $ characters.)

1585

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

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

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

1589 it.

1590

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

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

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

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

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

1596

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

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

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

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

1601 procedure is:

1602

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

1604 gladtex -d myfile-images myfile.htex

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

1606

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

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

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

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

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

1612

1613

1614Raw HTML

1615--------

1616

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

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

1619literally).

1620

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

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

1623

1624*Pandoc extension*.

1625

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

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

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

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

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

1631

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

1633pandoc interprets material between HTML block tags as markdown.

1634Thus, for example, Pandoc will turn

1635

1636 <table>

1637 <tr>

1638 <td>*one*</td>

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

1640 </tr>

1641 </table>

1642

1643into

1644

1645 <table>

1646 <tr>

1647 <td><em>one</em></td>

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

1649 </tr>

1650 </table>

1651

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

1653

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

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

1656

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

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

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

1660from being interpreted as markdown.

1661

1662Raw TeX

1663-------

1664

1665*Pandoc extension*.

1666

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

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

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

1670LaTeX to include BibTeX citations:

1671

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

1673

1674Note that in LaTeX environments, like

1675

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

1677 Age & Frequency \\ \hline

1678 18--25 & 15 \\

1679 26--35 & 33 \\

1680 36--45 & 22 \\ \hline

1681 \end{tabular}

1682

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

1684LaTeX, not as markdown.

1685

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

1687and ConTeXt.

1688

1689### Macros ###

1690

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

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

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

1694not just LaTeX:

1695

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

1697

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

1699

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

1701unchanged to the output.

1702

1703

1704Links

1705-----

1706

1707Markdown allows links to be specified in several ways.

1708

1709### Automatic links ###

1710

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

1712will become a link:

1713

1714 <http://google.com>

1715 <sam@green.eggs.ham>

1716

1717

1718### Inline links ###

1719

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

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

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

1723

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

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

1726

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

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

1729

1730

1731### Reference links ###

1732

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

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

1735before or after the link).

1736

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

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

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

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

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

1742parentheses.

1743

1744Here are some examples:

1745

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

1747 [my label 2]: /foo

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

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

1750

1751The URL may optionally be surrounded by angle brackets:

1752

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

1754

1755The title may go on the next line:

1756

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

1758 "The free software foundation"

1759

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

1761

1762 Here is [my link][FOO]

1763

1764 [Foo]: /bar/baz

1765

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

1767empty, or omitted entirely:

1768

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

1770

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

1772

1773

1774Images

1775------

1776

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

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

1779

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

1781

1782 ![movie reel]

1783

1784 [movie reel]: movie.gif

1785

1786### Pictures with captions ###

1787

1788*Pandoc extension*.

1789

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

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

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

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

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

1795

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

1797

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

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

1800 itself, with no caption.

1801

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

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

1804nonbreaking space after the image:

1805

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

1807

1808

1809Footnotes

1810---------

1811

1812*Pandoc extension*.

1813

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

1815

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

1817

1818 [^1]: Here is the footnote.

1819

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

1821

1822 Subsequent paragraphs are indented to show that they

1823 belong to the previous footnote.

1824

1825 { some.code }

1826

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

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

1829 multi-paragraph list items.

1830

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

1832 isn't indented.

1833

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

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

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

1837will be numbered sequentially.

1838

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

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

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

1842

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

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

1845

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

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

1848 note.]

1849

1850Inline and regular footnotes may be mixed freely.

1851

1852

1853Citations

1854---------

1855

1856*Pandoc extension*.

1857

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

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

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

1861

1862 Format File extension

1863 ------------ --------------

1864 MODS .mods

1865 BibTeX/BibLaTeX .bib

1866 RIS .ris

1867 EndNote .enl

1868 EndNote XML .xml

1869 ISI .wos

1870 MEDLINE .medline

1871 Copac .copac

1872 JSON citeproc .json

1873

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

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

1876bibliographies).

1877

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

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

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

1881creating and modifying CSL styles can be found at

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

1883A repository of CSL styles can be found at

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

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

1886

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

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

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

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

1891

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

1893

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

1895

1896 Blah blah [@smith04; @doe99].

1897

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

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

1900author is already mentioned in the text:

1901

1902 Smith says blah [-@smith04].

1903

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

1905

1906 @smith04 says blah.

1907

1908 @smith04 [p. 33] says blah.

1909

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

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

1912document with an appropriate header:

1913

1914 last paragraph...

1915

1916 # References

1917

1918The bibliography will be inserted after this header.

1919

1920

1921Producing slide shows with Pandoc

1922=================================

1923

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

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

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

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

1928`markdown2pdf`.

1929

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

1931

1932 % Eating Habits

1933 % John Doe

1934 % March 22, 2005

1935

1936 # In the morning

1937

1938 - Eat eggs

1939 - Drink coffee

1940

1941 # In the evening

1942

1943 - Eat spaghetti

1944 - Drink wine

1945

1946 --------------------------

1947

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

1949

1950To produce the slide show, simply type

1951

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

1953

1954for S5, or

1955

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

1957

1958for Slidy, or

1959

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

1961

1962for DZSlides.

1963

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

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

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

1967

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

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

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

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

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

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

1974

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

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

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

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

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

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

1981

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

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

1984linked scripts, stylesheets, images, and videos.

1985

1986Incremental lists

1987-----------------

1988

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

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

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

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

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

1994

1995 > - Eat spaghetti

1996 > - Drink wine

1997

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

1999a single document.

2000

2001Literate Haskell support

2002========================

2003

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

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

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

2007

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

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

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

2011

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

2013 rendered using bird tracks, and block quotations will be

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

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

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

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

2018

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

2020 as Haskell code.

2021

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

2023 be rendered using bird tracks.

2024

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

2026 Haskell code.

2027

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

2029 inside `code` environments.

2030

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

2032 with class `literatehaskell` and bird tracks.

2033

2034Examples:

2035

2036 pandoc -f markdown+lhs -t html

2037

2038reads literate Haskell source formatted with markdown conventions and writes

2039ordinary HTML (without bird tracks).

2040

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

2042

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

2044and pasted as literate Haskell source.

2045

2046Authors

2047=======

2048

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

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

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

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

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

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

2056Christopher Sawicki, Kelsey Hightower.

2057

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

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

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

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

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

2063[HTML 5]: http://www.w3.org/TR/html5/

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2082[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime