README · typeable/pandoc

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

1030

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

1032

1033

1034### Numbered example lists ###

1035

1036*Pandoc extension*.

1037

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

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

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

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

1042where the last stopped. So, for example:

1043

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

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

1046

1047 Explanation of examples.

1048

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

1050

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

1052document:

1053

1054 (@good) This is a good example.

1055

1056 As (@good) illustrates, ...

1057

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

1059or hyphens.

1060

1061

1062### Compact and loose lists ###

1063

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

1065cases" involving lists. Consider this source:

1066

1067 + First

1068 + Second:

1069 - Fee

1070 - Fie

1071 - Foe

1072

1073 + Third

1074

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

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

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

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

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

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

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

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

1083behavior is consistent with the official markdown syntax description,

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

1085

1086

1087### Ending a list ###

1088

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

1090

1091 - item one

1092 - item two

1093

1094 { my code block }

1095

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

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

1098a code block.

1099

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

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

1102any format:

1103

1104 - item one

1105 - item two

1106

1107

1108

1109 { my code block }

1110

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

1112of one big list:

1113

1114 1. one

1115 2. two

1116 3. three

1117

1118

1119

1120 a. uno

1121 b. dos

1122 c. tres

1123

1124

1125Horizontal rules

1126----------------

1127

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

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

1131 * * * *

1133 ---------------

1136Tables

1137------

1138

1139*Pandoc extension*.

1140

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

1142a fixed-width font, such as Courier.

1143

1144**Simple tables** look like this:

1145

1146 Right Left Center Default

1147 ------- ------ ---------- -------

1148 12 12 12 12

1149 123 123 123 123

1150 1 1 1 1

1151

1152 Table: Demonstration of simple table syntax.

1153

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

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

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

1157

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

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

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

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

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

1163 the column is centered.

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

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

1166

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

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

1169

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

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

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

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

1174before or after the table.

1175

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

1177to end the table. For example:

1178

1179 ------- ------ ---------- -------

1180 12 12 12 12

1181 123 123 123 123

1182 1 1 1 1

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

1184

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

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

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

1188

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

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

1191not supported). Here is an example:

1192

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

1194 Centered Default Right Left

1195 Header Aligned Aligned Aligned

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

1197 First row 12.0 Example of a row that

1198 spans multiple lines.

1199

1200 Second row 5.0 Here's another one. Note

1201 the blank line between

1202 rows.

1203 -------------------------------------------------------------

1204

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

1206 multiple lines.

1207

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

1209

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

1211 (unless the headers are omitted).

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

1213 - The rows must be separated by blank lines.

1214

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

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

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

1218output, try widening it in the markdown source.

1219

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

1221

1222 ----------- ------- --------------- -------------------------

1223 First row 12.0 Example of a row that

1224 spans multiple lines.

1225

1226 Second row 5.0 Here's another one. Note

1227 the blank line between

1228 rows.

1229 -------------------------------------------------------------

1230

1231 : Here's a multiline table without headers.

1232

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

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

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

1236

1237**Grid tables** look like this:

1238

1239 : Sample grid table.

1240

1241 +---------------+---------------+--------------------+

1242 | Fruit | Price | Advantages |

1243 +===============+===============+====================+

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

1245 | | | - bright color |

1246 +---------------+---------------+--------------------+

1247 | Oranges | $2.10 | - cures scurvy |

1248 | | | - tasty |

1249 +---------------+---------------+--------------------+

1250

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

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

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

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

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

1256

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

1258

1259

1260Title block

1261-----------

1262

1263*Pandoc extension*.

1264

1265If the file begins with a title block

1266

1267 % title

1268 % author(s) (separated by semicolons)

1269 % date

1270

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

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

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

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

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

1276

1277 %

1278 % Author

1279

1280 % My title

1281 %

1282 % June 15, 2006

1283

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

1285begin with leading space, thus:

1286

1287 % My title

1288 on multiple lines

1289

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

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

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

1293

1294 % Author One

1295 Author Two

1296

1297 % Author One; Author Two

1298

1299 % Author One;

1300 Author Two

1301

1302The date must fit on one line.

1303

1304All three metadata fields may contain standard inline formatting

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

1306

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

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

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

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

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

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

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

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

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

1316be used by itself as the HTML title.

1317

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

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

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

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

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

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

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

1325text. Thus,

1326

1327 % PANDOC(1)

1328

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

1330

1331 % PANDOC(1) Pandoc User Manuals

1332

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

1334

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

1336

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

1338

1339

1340Backslash escapes

1341-----------------

1342

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

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

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

1346

1347 *\*hello\**

1348

1349one will get

1350

1351 <em>*hello*</em>

1352

1353instead of

1354

1355 <strong>hello</strong>

1356

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

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

1359

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

1361

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

1363markdown rule will be used.)

1364

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

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

1367`\ `.

1368

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

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

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

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

1373two trailing spaces on a line.

1374

1375Backslash escapes do not work in verbatim contexts.

1376

1377Smart punctuation

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

1379

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

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

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

1383certain abbreviations, such as "Mr."

1384

1385Inline formatting

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

1387

1388### Emphasis ###

1389

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

1391

1392 This text is _emphasized with underscores_, and this

1393 is *emphasized with asterisks*.

1394

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

1396

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

1398

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

1400will not trigger emphasis:

1401

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

1403

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

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

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

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

1408

1409 feas*ible*, not feas*able*.

1410

1411

1412### Strikeout ###

1413

1414*Pandoc extension*.

1415

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

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

1418

1419 This ~~is deleted text.~~

1420

1421

1422### Superscripts and subscripts ###

1423

1424*Pandoc extension*.

1425

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

1427characters; subscripts may be written by surrounding the subscripted

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

1429

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

1431

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

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

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

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

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

1437

1438

1439### Verbatim ###

1440

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

1442

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

1444

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

1446

1447 Here is a literal backtick `` ` ``.

1448

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

1450backticks will be ignored.)

1451

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

1453of consecutive backticks (optionally followed by a space)

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

1455preceded by a space).

1456

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

1458work in verbatim contexts:

1459

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

1461

1462

1463Math

1464----

1465

1466*Pandoc extension*.

1467

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

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

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

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

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

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

1474

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

1476depends on the output format:

1477

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

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

1480

1481reStructuredText

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

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

1484

1485Texinfo

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

1487

1488groff man

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

1490

1491MediaWiki

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

1493

1494Textile

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

1496

1497RTF, Docbook, OpenDocument, ODT

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

1499 and will otherwise appear verbatim.

1500

1501HTML, Slidy, S5, EPUB

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

1503 command-line options selected:

1504

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

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

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

1508 styled differently from the surrounding text if needed.

1509

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

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

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

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

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

1515 verbatim between $ characters.)

1516

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

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

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

1520 it.

1521

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

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

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

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

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

1527

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

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

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

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

1532 procedure is:

1533

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

1535 gladtex -d myfile-images myfile.htex

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

1537

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

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

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

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

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

1543

1544

1545Raw HTML

1546--------

1547

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

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

1550literally).

1551

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

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

1554

1555*Pandoc extension*.

1556

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

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

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

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

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

1562

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

1564pandoc interprets material between HTML block tags as markdown.

1565Thus, for example, Pandoc will turn

1566

1567 <table>

1568 <tr>

1569 <td>*one*</td>

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

1571 </tr>

1572 </table>

1573

1574into

1575

1576 <table>

1577 <tr>

1578 <td><em>one</em></td>

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

1580 </tr>

1581 </table>

1582

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

1584

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

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

1587

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

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

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

1591from being interpreted as markdown.

1592

1593

1594Raw TeX

1595-------

1596

1597*Pandoc extension*.

1598

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

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

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

1602LaTeX to include BibTeX citations:

1603

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

1605

1606Note that in LaTeX environments, like

1607

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

1609 Age & Frequency \\ \hline

1610 18--25 & 15 \\

1611 26--35 & 33 \\

1612 36--45 & 22 \\ \hline

1613 \end{tabular}

1614

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

1616LaTeX, not as markdown.

1617

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

1619and ConTeXt.

1620

1621### Macros ###

1622

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

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

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

1626not just LaTeX:

1627

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

1629

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

1631

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

1633unchanged to the output.

1634

1635

1636Links

1637-----

1638

1639Markdown allows links to be specified in several ways.

1640

1641### Automatic links ###

1642

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

1644will become a link:

1645

1646 <http://google.com>

1647 <sam@green.eggs.ham>

1648

1649

1650### Inline links ###

1651

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

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

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

1655

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

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

1658

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

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

1661

1662

1663### Reference links ###

1664

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

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

1667before or after the link).

1668

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

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

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

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

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

1674parentheses.

1675

1676Here are some examples:

1677

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

1679 [my label 2]: /foo

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

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

1682

1683The URL may optionally be surrounded by angle brackets:

1684

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

1686

1687The title may go on the next line:

1688

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

1690 "The free software foundation"

1691

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

1693

1694 Here is [my link][FOO]

1695

1696 [Foo]: /bar/baz

1697

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

1699empty, or omitted entirely:

1700

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

1702

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

1704

1705

1706Images

1707------

1708

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

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

1711

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

1713

1714 ![movie reel]

1715

1716 [movie reel]: movie.gif

1717

1718### Pictures with captions ###

1719

1720*Pandoc extension*.

1721

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

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

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

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

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

1727

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

1729

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

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

1732 itself, with no caption.

1733

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

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

1736nonbreaking space after the image:

1737

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

1739

1740

1741Footnotes

1742---------

1743

1744*Pandoc extension*.

1745

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

1747

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

1749

1750 [^1]: Here is the footnote.

1751

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

1753

1754 Subsequent paragraphs are indented to show that they

1755 belong to the previous footnote.

1756

1757 { some.code }

1758

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

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

1761 multi-paragraph list items.

1762

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

1764 isn't indented.

1765

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

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

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

1769will be numbered sequentially.

1770

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

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

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

1774

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

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

1777

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

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

1780 note.]

1781

1782Inline and regular footnotes may be mixed freely.

1783

1784

1785Citations

1786---------

1787

1788*Pandoc extension*.

1789

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

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

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

1793

1794 Format File extension

1795 ------------ --------------

1796 MODS .mods

1797 BibTeX .bib

1798 BibLaTeX .bbx

1799 RIS .ris

1800 EndNote .enl

1801 EndNote XML .xml

1802 ISI .wos

1803 MEDLINE .medline

1804 Copac .copac

1805 JSON citeproc .json

1806

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

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

1809bibliographies).

1810

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

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

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

1814creating and modifying CSL styles can be found at

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

1816A repository of CSL styles can be found at

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

1818

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

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

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

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

1823

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

1825

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

1827

1828 Blah blah [@smith04; @doe99].

1829

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

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

1832author is already mentioned in the text:

1833

1834 Smith says blah [-@smith04].

1835

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

1837

1838 @smith04 says blah.

1839

1840 @smith04 [p. 33] says blah.

1841

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

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

1844document with an appropriate header:

1845

1846 last paragraph...

1847

1848 # References

1849

1850The bibliography will be inserted after this header.

1851

1852

1853Producing HTML slide shows with Pandoc

1854======================================

1855

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

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

1858using [S5] or [Slidy].

1859

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

1861

1862 % Eating Habits

1863 % John Doe

1864 % March 22, 2005

1865

1866 # In the morning

1867

1868 - Eat eggs

1869 - Drink coffee

1870

1871 # In the evening

1872

1873 - Eat spaghetti

1874 - Drink wine

1875

1876 --------------------------

1877

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

1879

1880To produce the slide show, simply type

1881

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

1883

1884for S5, or

1885

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

1887

1888for Slidy.

1889

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

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

1892

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

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

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

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

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

1898it may be used offline.

1899

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

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

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

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

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

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

1906

1907Incremental lists

1908-----------------

1909

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

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

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

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

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

1915

1916 > - Eat spaghetti

1917 > - Drink wine

1918

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

1920a single document.

1921

1922Literate Haskell support

1923========================

1924

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

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

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

1928

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

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

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

1932

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

1934 rendered using bird tracks, and block quotations will be

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

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

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

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

1939

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

1941 as Haskell code.

1942

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

1944 be rendered using bird tracks.

1945

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

1947 Haskell code.

1948

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

1950 inside `code` environments.

1951

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

1953 with class `literatehaskell` and bird tracks.

1954

1955Examples:

1956

1957 pandoc -f markdown+lhs -t html

1958

1959reads literate Haskell source formatted with markdown conventions and writes

1960ordinary HTML (without bird tracks).

1961

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

1963

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

1965and pasted as literate Haskell source.

1966

1967Authors

1968=======

1969

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

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

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

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

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

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

1977

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1997