README · typeable/pandoc

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

1020

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

1022

1023

1024### Numbered example lists ###

1025

1026*Pandoc extension*.

1027

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

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

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

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

1032where the last stopped. So, for example:

1033

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

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

1036

1037 Explanation of examples.

1038

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

1040

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

1042document:

1043

1044 (@good) This is a good example.

1045

1046 As (@good) illustrates, ...

1047

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

1049or hyphens.

1050

1051

1052### Compact and loose lists ###

1053

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

1055cases" involving lists. Consider this source:

1056

1057 + First

1058 + Second:

1059 - Fee

1060 - Fie

1061 - Foe

1062

1063 + Third

1064

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

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

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

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

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

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

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

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

1073behavior is consistent with the official markdown syntax description,

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

1075

1076

1077### Ending a list ###

1078

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

1080

1081 - item one

1082 - item two

1083

1084 { my code block }

1085

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

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

1088a code block.

1089

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

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

1092any format:

1093

1094 - item one

1095 - item two

1096

1097

1098

1099 { my code block }

1100

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

1102of one big list:

1103

1104 1. one

1105 2. two

1106 3. three

1107

1108

1109

1110 a. uno

1111 b. dos

1112 c. tres

1113

1114

1115Horizontal rules

1116----------------

1117

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

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

1121 * * * *

1123 ---------------

1126Tables

1127------

1128

1129*Pandoc extension*.

1130

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

1132a fixed-width font, such as Courier.

1133

1134**Simple tables** look like this:

1135

1136 Right Left Center Default

1137 ------- ------ ---------- -------

1138 12 12 12 12

1139 123 123 123 123

1140 1 1 1 1

1141

1142 Table: Demonstration of simple table syntax.

1143

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

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

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

1147

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

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

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

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

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

1153 the column is centered.

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

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

1156

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

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

1159

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

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

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

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

1164before or after the table.

1165

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

1167to end the table. For example:

1168

1169 ------- ------ ---------- -------

1170 12 12 12 12

1171 123 123 123 123

1172 1 1 1 1

1173 ------- ------ ---------- -------

1174

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

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

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

1178

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

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

1181not supported). Here is an example:

1182

1183 -------------------------------------------------------------

1184 Centered Default Right Left

1185 Header Aligned Aligned Aligned

1186 ----------- ------- --------------- -------------------------

1187 First row 12.0 Example of a row that

1188 spans multiple lines.

1189

1190 Second row 5.0 Here's another one. Note

1191 the blank line between

1192 rows.

1193 -------------------------------------------------------------

1194

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

1196 multiple lines.

1197

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

1199

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

1201 (unless the headers are omitted).

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

1203 - The rows must be separated by blank lines.

1204

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

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

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

1208output, try widening it in the markdown source.

1209

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

1211

1212 ----------- ------- --------------- -------------------------

1213 First row 12.0 Example of a row that

1214 spans multiple lines.

1215

1216 Second row 5.0 Here's another one. Note

1217 the blank line between

1218 rows.

1219 -------------------------------------------------------------

1220

1221 : Here's a multiline table without headers.

1222

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

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

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

1226

1227**Grid tables** look like this:

1228

1229 : Sample grid table.

1230

1231 +---------------+---------------+--------------------+

1232 | Fruit | Price | Advantages |

1233 +===============+===============+====================+

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

1235 | | | - bright color |

1236 +---------------+---------------+--------------------+

1237 | Oranges | $2.10 | - cures scurvy |

1238 | | | - tasty |

1239 +---------------+---------------+--------------------+

1240

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

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

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

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

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

1246

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

1248

1249

1250Title block

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

1252

1253*Pandoc extension*.

1254

1255If the file begins with a title block

1256

1257 % title

1258 % author(s) (separated by semicolons)

1259 % date

1260

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

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

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

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

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

1266

1267 %

1268 % Author

1269

1270 % My title

1271 %

1272 % June 15, 2006

1273

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

1275begin with leading space, thus:

1276

1277 % My title

1278 on multiple lines

1279

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

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

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

1283

1284 % Author One

1285 Author Two

1286

1287 % Author One; Author Two

1288

1289 % Author One;

1290 Author Two

1291

1292The date must fit on one line.

1293

1294All three metadata fields may contain standard inline formatting

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

1296

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

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

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

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

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

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

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

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

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

1306be used by itself as the HTML title.

1307

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

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

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

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

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

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

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

1315text. Thus,

1316

1317 % PANDOC(1)

1318

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

1320

1321 % PANDOC(1) Pandoc User Manuals

1322

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

1324

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

1326

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

1328

1329

1330Backslash escapes

1331-----------------

1332

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

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

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

1336

1337 *\*hello\**

1338

1339one will get

1340

1341 <em>*hello*</em>

1342

1343instead of

1344

1345 <strong>hello</strong>

1346

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

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

1349

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

1351

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

1353markdown rule will be used.)

1354

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

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

1357`\ `.

1358

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

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

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

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

1363two trailing spaces on a line.

1364

1365Backslash escapes do not work in verbatim contexts.

1366

1367Smart punctuation

1368-----------------

1369

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

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

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

1373certain abbreviations, such as "Mr."

1374

1375Inline formatting

1376-----------------

1377

1378### Emphasis ###

1379

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

1381

1382 This text is _emphasized with underscores_, and this

1383 is *emphasized with asterisks*.

1384

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

1386

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

1388

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

1390will not trigger emphasis:

1391

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

1393

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

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

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

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

1398

1399 feas*ible*, not feas*able*.

1400

1401

1402### Strikeout ###

1403

1404*Pandoc extension*.

1405

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

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

1408

1409 This ~~is deleted text.~~

1410

1411

1412### Superscripts and subscripts ###

1413

1414*Pandoc extension*.

1415

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

1417characters; subscripts may be written by surrounding the subscripted

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

1419

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

1421

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

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

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

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

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

1427

1428

1429### Verbatim ###

1430

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

1432

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

1434

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

1436

1437 Here is a literal backtick `` ` ``.

1438

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

1440backticks will be ignored.)

1441

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

1443of consecutive backticks (optionally followed by a space)

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

1445preceded by a space).

1446

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

1448work in verbatim contexts:

1449

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

1451

1452

1453Math

1454----

1455

1456*Pandoc extension*.

1457

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

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

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

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

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

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

1464

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

1466depends on the output format:

1467

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

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

1470

1471reStructuredText

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

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

1474

1475Texinfo

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

1477

1478groff man

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

1480

1481MediaWiki

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

1483

1484Textile

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

1486

1487RTF, Docbook, OpenDocument, ODT

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

1489 and will otherwise appear verbatim.

1490

1491HTML, Slidy, S5, EPUB

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

1493 command-line options selected:

1494

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

1496 characters, as with RTF, Docbook, and OpenDocument output. Formulas

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

1498 styled differently from the surrounding text if needed.

1499

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

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

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

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

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

1505 verbatim between $ characters.)

1506

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

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

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

1510 it.

1511

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

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

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

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

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

1517

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

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

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

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

1522 procedure is:

1523

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

1525 gladtex -d myfile-images myfile.htex

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

1527

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

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

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

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

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

1533

1534

1535Raw HTML

1536--------

1537

1538Markdown allows you to insert raw HTML anywhere in a document

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

1540literally).

1541

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

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

1544

1545*Pandoc extension*.

1546

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

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

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

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

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

1552

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

1554pandoc interprets material between HTML block tags as markdown.

1555Thus, for example, Pandoc will turn

1556

1557 <table>

1558 <tr>

1559 <td>*one*</td>

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

1561 </tr>

1562 </table>

1563

1564into

1565

1566 <table>

1567 <tr>

1568 <td><em>one</em></td>

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

1570 </tr>

1571 </table>

1572

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

1574

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

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

1577

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

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

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

1581from being interpreted as markdown.

1582

1583

1584Raw TeX

1585-------

1586

1587*Pandoc extension*.

1588

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

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

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

1592LaTeX to include BibTeX citations:

1593

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

1595

1596Note that in LaTeX environments, like

1597

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

1599 Age & Frequency \\ \hline

1600 18--25 & 15 \\

1601 26--35 & 33 \\

1602 36--45 & 22 \\ \hline

1603 \end{tabular}

1604

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

1606LaTeX, not as markdown.

1607

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

1609and ConTeXt.

1610

1611### Macros ###

1612

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

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

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

1616not just LaTeX:

1617

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

1619

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

1621

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

1623unchanged to the output.

1624

1625

1626Links

1627-----

1628

1629Markdown allows links to be specified in several ways.

1630

1631### Automatic links ###

1632

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

1634will become a link:

1635

1636 <http://google.com>

1637 <sam@green.eggs.ham>

1638

1639

1640### Inline links ###

1641

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

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

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

1645

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

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

1648

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

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

1651

1652

1653### Reference links ###

1654

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

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

1657before or after the link).

1658

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

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

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

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

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

1664parentheses.

1665

1666Here are some examples:

1667

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

1669 [my label 2]: /foo

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

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

1672

1673The URL may optionally be surrounded by angle brackets:

1674

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

1676

1677The title may go on the next line:

1678

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

1680 "The free software foundation"

1681

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

1683

1684 Here is [my link][FOO]

1685

1686 [Foo]: /bar/baz

1687

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

1689empty, or omitted entirely:

1690

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

1692

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

1694

1695

1696Images

1697------

1698

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

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

1701

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

1703

1704 ![movie reel]

1705

1706 [movie reel]: movie.gif

1707

1708### Pictures with captions ###

1709

1710*Pandoc extension*.

1711

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

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

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

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

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

1717

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

1719

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

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

1722 itself, with no caption.

1723

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

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

1726nonbreaking space after the image:

1727

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

1729

1730

1731Footnotes

1732---------

1733

1734*Pandoc extension*.

1735

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

1737

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

1739

1740 [^1]: Here is the footnote.

1741

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

1743

1744 Subsequent paragraphs are indented to show that they

1745 belong to the previous footnote.

1746

1747 { some.code }

1748

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

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

1751 multi-paragraph list items.

1752

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

1754 isn't indented.

1755

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

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

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

1759will be numbered sequentially.

1760

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

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

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

1764

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

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

1767

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

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

1770 note.]

1771

1772Inline and regular footnotes may be mixed freely.

1773

1774

1775Citations

1776---------

1777

1778*Pandoc extension*.

1779

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

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

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

1783

1784 Format File extension

1785 ------------ --------------

1786 MODS .mods

1787 BibTeX .bib

1788 BibLaTeX .bbx

1789 RIS .ris

1790 EndNote .enl

1791 EndNote XML .xml

1792 ISI .wos

1793 MEDLINE .medline

1794 Copac .copac

1795 JSON citeproc .json

1796

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

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

1799bibliographies).

1800

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

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

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

1804creating and modifying CSL styles can be found at

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

1806A repository of CSL styles can be found at

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

1808

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

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

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

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

1813

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

1815

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

1817

1818 Blah blah [@smith04; @doe99].

1819

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

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

1822author is already mentioned in the text:

1823

1824 Smith says blah [-@smith04].

1825

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

1827

1828 @smith04 says blah.

1829

1830 @smith04 [p. 33] says blah.

1831

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

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

1834document with an appropriate header:

1835

1836 last paragraph...

1837

1838 # References

1839

1840The bibliography will be inserted after this header.

1841

1842

1843Producing HTML slide shows with Pandoc

1844======================================

1845

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

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

1848using [S5] or [Slidy].

1849

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

1851

1852 % Eating Habits

1853 % John Doe

1854 % March 22, 2005

1855

1856 # In the morning

1857

1858 - Eat eggs

1859 - Drink coffee

1860

1861 # In the evening

1862

1863 - Eat spaghetti

1864 - Drink wine

1865

1866 --------------------------

1867

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

1869

1870To produce the slide show, simply type

1871

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

1873

1874for S5, or

1875

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

1877

1878for Slidy.

1879

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

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

1882

1883The file produced by pandoc with the `-s/--standalone` option embeds a

1884link to javascripts and CSS files, which are assumed to be available at

1885the relative path `ui/default` (for S5) or at the Slidy website at

1886`w3.org` (for Slidy). If the `--offline` option is specified, the

1887scripts and CSS will be included directly in the generated file, so that

1888it may be used offline.

1889

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

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

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

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

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

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

1896

1897Incremental lists

1898-----------------

1899

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

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

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

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

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

1905

1906 > - Eat spaghetti

1907 > - Drink wine

1908

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

1910a single document.

1911

1912Literate Haskell support

1913========================

1914

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

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

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

1918

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

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

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

1922

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

1924 rendered using bird tracks, and block quotations will be

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

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

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

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

1929

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

1931 as Haskell code.

1932

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

1934 be rendered using bird tracks.

1935

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

1937 Haskell code.

1938

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

1940 inside `code` environments.

1941

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

1943 with class `literatehaskell` and bird tracks.

1944

1945Examples:

1946

1947 pandoc -f markdown+lhs -t html

1948

1949reads literate Haskell source formatted with markdown conventions and writes

1950ordinary HTML (without bird tracks).

1951

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

1953

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

1955and pasted as literate Haskell source.

1956

1957Authors

1958=======

1959

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

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

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

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

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

1966Nathan Gass, Jonathan Daugherty, Jérémy Bobbio, Justin Bogner.

1967

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1984[Emacs Org-Mode]: http://org-mode.org

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

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

1987