README · typeable/pandoc

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

983

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

985

986

987### Numbered example lists ###

988

989*Pandoc extension*.

990

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

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

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

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

995where the last stopped. So, for example:

996

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

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

999

1000 Explanation of examples.

1001

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

1003

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

1005document:

1006

1007 (@good) This is a good example.

1008

1009 As (@good) illustrates, ...

1010

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

1012or hyphens.

1013

1014

1015### Compact and loose lists ###

1016

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

1018cases" involving lists. Consider this source:

1019

1020 + First

1021 + Second:

1022 - Fee

1023 - Fie

1024 - Foe

1025

1026 + Third

1027

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

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

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

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

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

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

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

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

1036behavior is consistent with the official markdown syntax description,

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

1038

1039

1040### Ending a list ###

1041

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

1043

1044 - item one

1045 - item two

1046

1047 { my code block }

1048

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

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

1051a code block.

1052

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

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

1055any format:

1056

1057 - item one

1058 - item two

1059

1060

1061

1062 { my code block }

1063

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

1065of one big list:

1066

1067 1. one

1068 2. two

1069 3. three

1070

1071

1072

1073 a. uno

1074 b. dos

1075 c. tres

1076

1077

1078Horizontal rules

1079----------------

1080

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

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

1084 * * * *

1086 ---------------

1089Tables

1090------

1091

1092*Pandoc extension*.

1093

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

1095a fixed-width font, such as Courier.

1096

1097**Simple tables** look like this:

1098

1099 Right Left Center Default

1100 ------- ------ ---------- -------

1101 12 12 12 12

1102 123 123 123 123

1103 1 1 1 1

1104

1105 Table: Demonstration of simple table syntax.

1106

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

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

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

1110

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

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

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

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

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

1116 the column is centered.

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

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

1119

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

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

1122

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

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

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

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

1127before or after the table.

1128

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

1130to end the table. For example:

1131

1132 ------- ------ ---------- -------

1133 12 12 12 12

1134 123 123 123 123

1135 1 1 1 1

1136 ------- ------ ---------- -------

1137

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

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

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

1141

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

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

1144not supported). Here is an example:

1145

1146 -------------------------------------------------------------

1147 Centered Default Right Left

1148 Header Aligned Aligned Aligned

1149 ----------- ------- --------------- -------------------------

1150 First row 12.0 Example of a row that

1151 spans multiple lines.

1152

1153 Second row 5.0 Here's another one. Note

1154 the blank line between

1155 rows.

1156 -------------------------------------------------------------

1157

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

1159 multiple lines.

1160

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

1162

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

1164 (unless the headers are omitted).

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

1166 - The rows must be separated by blank lines.

1167

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

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

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

1171output, try widening it in the markdown source.

1172

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

1174

1175 ----------- ------- --------------- -------------------------

1176 First row 12.0 Example of a row that

1177 spans multiple lines.

1178

1179 Second row 5.0 Here's another one. Note

1180 the blank line between

1181 rows.

1182 -------------------------------------------------------------

1183

1184 : Here's a multiline table without headers.

1185

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

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

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

1189

1190**Grid tables** look like this:

1191

1192 : Sample grid table.

1193

1194 +---------------+---------------+--------------------+

1195 | Fruit | Price | Advantages |

1196 +===============+===============+====================+

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

1198 | | | - bright color |

1199 +---------------+---------------+--------------------+

1200 | Oranges | $2.10 | - cures scurvy |

1201 | | | - tasty |

1202 +---------------+---------------+--------------------+

1203

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

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

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

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

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

1209

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

1211

1212

1213Title block

1214-----------

1215

1216*Pandoc extension*.

1217

1218If the file begins with a title block

1219

1220 % title

1221 % author(s) (separated by semicolons)

1222 % date

1223

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

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

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

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

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

1229

1230 %

1231 % Author

1232

1233 % My title

1234 %

1235 % June 15, 2006

1236

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

1238begin with leading space, thus:

1239

1240 % My title

1241 on multiple lines

1242

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

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

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

1246

1247 % Author One

1248 Author Two

1249

1250 % Author One; Author Two

1251

1252 % Author One;

1253 Author Two

1254

1255The date must fit on one line.

1256

1257All three metadata fields may contain standard inline formatting

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

1259

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

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

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

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

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

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

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

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

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

1269be used by itself as the HTML title.

1270

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

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

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

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

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

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

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

1278text. Thus,

1279

1280 % PANDOC(1)

1281

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

1283

1284 % PANDOC(1) Pandoc User Manuals

1285

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

1287

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

1289

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

1291

1292

1293Backslash escapes

1294-----------------

1295

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

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

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

1299

1300 *\*hello\**

1301

1302one will get

1303

1304 <em>*hello*</em>

1305

1306instead of

1307

1308 <strong>hello</strong>

1309

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

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

1312

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

1314

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

1316markdown rule will be used.)

1317

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

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

1320`\ `.

1321

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

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

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

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

1326two trailing spaces on a line.

1327

1328Backslash escapes do not work in verbatim contexts.

1329

1330Smart punctuation

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

1332

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

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

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

1336certain abbreviations, such as "Mr."

1337

1338Inline formatting

1339-----------------

1340

1341### Emphasis ###

1342

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

1344

1345 This text is _emphasized with underscores_, and this

1346 is *emphasized with asterisks*.

1347

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

1349

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

1351

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

1353will not trigger emphasis:

1354

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

1356

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

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

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

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

1361

1362 feas*ible*, not feas*able*.

1363

1364

1365### Strikeout ###

1366

1367*Pandoc extension*.

1368

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

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

1371

1372 This ~~is deleted text.~~

1373

1374

1375### Superscripts and subscripts ###

1376

1377*Pandoc extension*.

1378

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

1380characters; subscripts may be written by surrounding the subscripted

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

1382

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

1384

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

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

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

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

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

1390

1391

1392### Verbatim ###

1393

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

1395

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

1397

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

1399

1400 Here is a literal backtick `` ` ``.

1401

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

1403backticks will be ignored.)

1404

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

1406of consecutive backticks (optionally followed by a space)

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

1408preceded by a space).

1409

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

1411work in verbatim contexts:

1412

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

1414

1415

1416Math

1417----

1418

1419*Pandoc extension*.

1420

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

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

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

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

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

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

1427

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

1429depends on the output format:

1430

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

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

1433

1434reStructuredText

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

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

1437

1438Texinfo

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

1440

1441groff man

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

1443

1444MediaWiki

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

1446

1447Textile

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

1449

1450RTF, Docbook, OpenDocument, ODT

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

1452 and will otherwise appear verbatim.

1453

1454HTML, Slidy, S5, EPUB

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

1456 command-line options selected:

1457

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

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

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

1461 styled differently from the surrounding text if needed.

1462

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

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

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

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

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

1468 verbatim between $ characters.)

1469

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

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

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

1473 it.

1474

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

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

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

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

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

1480

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

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

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

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

1485 procedure is:

1486

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

1488 gladtex -d myfile-images myfile.htex

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

1490

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

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

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

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

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

1496

1497

1498Raw HTML

1499--------

1500

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

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

1503literally).

1504

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

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

1507

1508*Pandoc extension*.

1509

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

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

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

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

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

1515

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

1517pandoc interprets material between HTML block tags as markdown.

1518Thus, for example, Pandoc will turn

1519

1520 <table>

1521 <tr>

1522 <td>*one*</td>

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

1524 </tr>

1525 </table>

1526

1527into

1528

1529 <table>

1530 <tr>

1531 <td><em>one</em></td>

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

1533 </tr>

1534 </table>

1535

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

1537

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

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

1540

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

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

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

1544from being interpreted as markdown.

1545

1546

1547Raw TeX

1548-------

1549

1550*Pandoc extension*.

1551

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

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

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

1555LaTeX to include BibTeX citations:

1556

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

1558

1559Note that in LaTeX environments, like

1560

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

1562 Age & Frequency \\ \hline

1563 18--25 & 15 \\

1564 26--35 & 33 \\

1565 36--45 & 22 \\ \hline

1566 \end{tabular}

1567

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

1569LaTeX, not as markdown.

1570

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

1572and ConTeXt.

1573

1574### Macros ###

1575

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

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

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

1579not just LaTeX:

1580

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

1582

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

1584

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

1586unchanged to the output.

1587

1588

1589Links

1590-----

1591

1592Markdown allows links to be specified in several ways.

1593

1594### Automatic links ###

1595

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

1597will become a link:

1598

1599 <http://google.com>

1600 <sam@green.eggs.ham>

1601

1602

1603### Inline links ###

1604

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

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

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

1608

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

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

1611

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

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

1614

1615

1616### Reference links ###

1617

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

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

1620before or after the link).

1621

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

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

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

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

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

1627parentheses.

1628

1629Here are some examples:

1630

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

1632 [my label 2]: /foo

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

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

1635

1636The URL may optionally be surrounded by angle brackets:

1637

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

1639

1640The title may go on the next line:

1641

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

1643 "The free software foundation"

1644

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

1646

1647 Here is [my link][FOO]

1648

1649 [Foo]: /bar/baz

1650

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

1652empty, or omitted entirely:

1653

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

1655

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

1657

1658

1659Images

1660------

1661

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

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

1664

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

1666

1667 ![movie reel]

1668

1669 [movie reel]: movie.gif

1670

1671### Pictures with captions ###

1672

1673*Pandoc extension*.

1674

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

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

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

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

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

1680

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

1682

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

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

1685 itself, with no caption.

1686

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

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

1689nonbreaking space after the image:

1690

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

1692

1693

1694Footnotes

1695---------

1696

1697*Pandoc extension*.

1698

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

1700

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

1702

1703 [^1]: Here is the footnote.

1704

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

1706

1707 Subsequent paragraphs are indented to show that they

1708 belong to the previous footnote.

1709

1710 { some.code }

1711

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

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

1714 multi-paragraph list items.

1715

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

1717 isn't indented.

1718

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

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

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

1722will be numbered sequentially.

1723

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

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

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

1727

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

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

1730

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

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

1733 note.]

1734

1735Inline and regular footnotes may be mixed freely.

1736

1737

1738Citations

1739---------

1740

1741*Pandoc extension*.

1742

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

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

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

1746

1747 Format File extension

1748 ------------ --------------

1749 MODS .mods

1750 BibTeX .bib

1751 BibLaTeX .bbx

1752 RIS .ris

1753 EndNote .enl

1754 EndNote XML .xml

1755 ISI .wos

1756 MEDLINE .medline

1757 Copac .copac

1758 JSON citeproc .json

1759

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

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

1762bibliographies).

1763

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

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

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

1767creating and modifying CSL styles can be found at

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

1769A repository of CSL styles can be found at

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

1771

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

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

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

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

1776

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

1778

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

1780

1781 Blah blah [@smith04; @doe99].

1782

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

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

1785author is already mentioned in the text:

1786

1787 Smith says blah [-@smith04].

1788

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

1790

1791 @smith04 says blah.

1792

1793 @smith04 [p. 33] says blah.

1794

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

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

1797document with an appropriate header:

1798

1799 last paragraph...

1800

1801 # References

1802

1803The bibliography will be inserted after this header.

1804

1805

1806Producing HTML slide shows with Pandoc

1807======================================

1808

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

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

1811using [S5] or [Slidy].

1812

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

1814

1815 % Eating Habits

1816 % John Doe

1817 % March 22, 2005

1818

1819 # In the morning

1820

1821 - Eat eggs

1822 - Drink coffee

1823

1824 # In the evening

1825

1826 - Eat spaghetti

1827 - Drink wine

1828

1829 --------------------------

1830

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

1832

1833To produce the slide show, simply type

1834

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

1836

1837for S5, or

1838

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

1840

1841for Slidy.

1842

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

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

1845

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

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

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

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

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

1851it may be used offline.

1852

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

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

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

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

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

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

1859

1860Incremental lists

1861-----------------

1862

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

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

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

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

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

1868

1869 > - Eat spaghetti

1870 > - Drink wine

1871

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

1873a single document.

1874

1875Literate Haskell support

1876========================

1877

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

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

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

1881

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

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

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

1885

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

1887 rendered using bird tracks, and block quotations will be

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

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

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

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

1892

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

1894 as Haskell code.

1895

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

1897 be rendered using bird tracks.

1898

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

1900 Haskell code.

1901

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

1903 inside `code` environments.

1904

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

1906 with class `literatehaskell` and bird tracks.

1907

1908Examples:

1909

1910 pandoc -f markdown+lhs -t html

1911

1912reads literate Haskell source formatted with markdown conventions and writes

1913ordinary HTML (without bird tracks).

1914

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

1916

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

1918and pasted as literate Haskell source.

1919

1920Authors

1921=======

1922

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

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

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

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

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

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

1930

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1950