README · typeable/pandoc

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

1188

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

1190

1191

1192### Numbered example lists ###

1193

1194*Pandoc extension*.

1195

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

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

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

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

1200where the last stopped. So, for example:

1201

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

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

1204

1205 Explanation of examples.

1206

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

1208

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

1210document:

1211

1212 (@good) This is a good example.

1213

1214 As (@good) illustrates, ...

1215

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

1217or hyphens.

1218

1219

1220### Compact and loose lists ###

1221

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

1223cases" involving lists. Consider this source:

1224

1225 + First

1226 + Second:

1227 - Fee

1228 - Fie

1229 - Foe

1230

1231 + Third

1232

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

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

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

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

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

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

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

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

1241behavior is consistent with the official markdown syntax description,

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

1243

1244

1245### Ending a list ###

1246

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

1248

1249 - item one

1250 - item two

1251

1252 { my code block }

1253

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

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

1256a code block.

1257

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

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

1260any format:

1261

1262 - item one

1263 - item two

1264

1265

1266

1267 { my code block }

1268

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

1270of one big list:

1271

1272 1. one

1273 2. two

1274 3. three

1275

1276

1277

1278 a. uno

1279 b. dos

1280 c. tres

1281

1282

1283Horizontal rules

1284----------------

1285

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

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

1289 * * * *

1291 ---------------

1294Tables

1295------

1296

1297*Pandoc extension*.

1298

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

1300a fixed-width font, such as Courier.

1301

1302**Simple tables** look like this:

1303

1304 Right Left Center Default

1305 ------- ------ ---------- -------

1306 12 12 12 12

1307 123 123 123 123

1308 1 1 1 1

1309

1310 Table: Demonstration of simple table syntax.

1311

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

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

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

1315

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

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

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

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

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

1321 the column is centered.

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

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

1324

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

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

1327

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

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

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

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

1332before or after the table.

1333

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

1335to end the table. For example:

1336

1337 ------- ------ ---------- -------

1338 12 12 12 12

1339 123 123 123 123

1340 1 1 1 1

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

1342

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

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

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

1346

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

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

1349not supported). Here is an example:

1350

1351 -------------------------------------------------------------

1352 Centered Default Right Left

1353 Header Aligned Aligned Aligned

1354 ----------- ------- --------------- -------------------------

1355 First row 12.0 Example of a row that

1356 spans multiple lines.

1357

1358 Second row 5.0 Here's another one. Note

1359 the blank line between

1360 rows.

1361 -------------------------------------------------------------

1362

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

1364 multiple lines.

1365

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

1367

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

1369 (unless the headers are omitted).

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

1371 - The rows must be separated by blank lines.

1372

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

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

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

1376output, try widening it in the markdown source.

1377

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

1379

1380 ----------- ------- --------------- -------------------------

1381 First row 12.0 Example of a row that

1382 spans multiple lines.

1383

1384 Second row 5.0 Here's another one. Note

1385 the blank line between

1386 rows.

1387 -------------------------------------------------------------

1388

1389 : Here's a multiline table without headers.

1390

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

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

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

1394

1395**Grid tables** look like this:

1396

1397 : Sample grid table.

1398

1399 +---------------+---------------+--------------------+

1400 | Fruit | Price | Advantages |

1401 +===============+===============+====================+

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

1403 | | | - bright color |

1404 +---------------+---------------+--------------------+

1405 | Oranges | $2.10 | - cures scurvy |

1406 | | | - tasty |

1407 +---------------+---------------+--------------------+

1408

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

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

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

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

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

1414

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

1416

1417

1418Title block

1419-----------

1420

1421*Pandoc extension*.

1422

1423If the file begins with a title block

1424

1425 % title

1426 % author(s) (separated by semicolons)

1427 % date

1428

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

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

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

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

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

1434

1435 %

1436 % Author

1437

1438 % My title

1439 %

1440 % June 15, 2006

1441

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

1443begin with leading space, thus:

1444

1445 % My title

1446 on multiple lines

1447

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

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

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

1451

1452 % Author One

1453 Author Two

1454

1455 % Author One; Author Two

1456

1457 % Author One;

1458 Author Two

1459

1460The date must fit on one line.

1461

1462All three metadata fields may contain standard inline formatting

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

1464

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

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

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

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

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

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

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

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

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

1474be used by itself as the HTML title.

1475

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

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

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

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

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

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

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

1483text. Thus,

1484

1485 % PANDOC(1)

1486

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

1488

1489 % PANDOC(1) Pandoc User Manuals

1490

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

1492

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

1494

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

1496

1497

1498Backslash escapes

1499-----------------

1500

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

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

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

1504

1505 *\*hello\**

1506

1507one will get

1508

1509 <em>*hello*</em>

1510

1511instead of

1512

1513 <strong>hello</strong>

1514

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

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

1517

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

1519

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

1521markdown rule will be used.)

1522

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

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

1525`\ `.

1526

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

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

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

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

1531two trailing spaces on a line.

1532

1533Backslash escapes do not work in verbatim contexts.

1534

1535Smart punctuation

1536-----------------

1537

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

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

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

1541certain abbreviations, such as "Mr."

1542

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

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

1545

1546Inline formatting

1547-----------------

1548

1549### Emphasis ###

1550

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

1552

1553 This text is _emphasized with underscores_, and this

1554 is *emphasized with asterisks*.

1555

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

1557

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

1559

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

1561will not trigger emphasis:

1562

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

1564

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

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

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

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

1569

1570 feas*ible*, not feas*able*.

1571

1572

1573### Strikeout ###

1574

1575*Pandoc extension*.

1576

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

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

1579

1580 This ~~is deleted text.~~

1581

1582

1583### Superscripts and subscripts ###

1584

1585*Pandoc extension*.

1586

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

1588characters; subscripts may be written by surrounding the subscripted

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

1590

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

1592

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

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

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

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

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

1598

1599

1600### Verbatim ###

1601

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

1603

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

1605

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

1607

1608 Here is a literal backtick `` ` ``.

1609

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

1611backticks will be ignored.)

1612

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

1614of consecutive backticks (optionally followed by a space)

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

1616preceded by a space).

1617

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

1619work in verbatim contexts:

1620

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

1622

1623

1624Math

1625----

1626

1627*Pandoc extension*.

1628

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

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

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

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

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

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

1635

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

1637depends on the output format:

1638

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

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

1641

1642reStructuredText

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

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

1645

1646AsciiDoc

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

1648

1649Texinfo

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

1651

1652groff man

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

1654

1655MediaWiki

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

1657

1658Textile

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

1660

1661RTF, OpenDocument, ODT

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

1663 and will otherwise appear verbatim.

1664

1665Docbook

1666 ~ If the `--mathml` flag is used, it will be rendered using mathml

1667 in an `inlineequation` or `informalequation` tag. Otherwise it

1668 will be rendered, if possible, using unicode characters.

1669

1670Docx

1671 ~ It will be rendered using OMML math markup.

1672

1673HTML, Slidy, DZSlides, S5, EPUB

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

1675 command-line options selected:

1676

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

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

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

1680 styled differently from the surrounding text if needed.

1681

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

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

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

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

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

1687 verbatim between $ characters.)

1688

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

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

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

1692 it.

1693

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

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

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

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

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

1699

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

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

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

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

1704 procedure is:

1705

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

1707 gladtex -d myfile-images myfile.htex

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

1709

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

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

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

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

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

1715

1716

1717Raw HTML

1718--------

1719

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

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

1722literally).

1723

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

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

1726

1727*Pandoc extension*.

1728

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

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

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

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

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

1734

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

1736pandoc interprets material between HTML block tags as markdown.

1737Thus, for example, Pandoc will turn

1738

1739 <table>

1740 <tr>

1741 <td>*one*</td>

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

1743 </tr>

1744 </table>

1745

1746into

1747

1748 <table>

1749 <tr>

1750 <td><em>one</em></td>

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

1752 </tr>

1753 </table>

1754

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

1756

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

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

1759

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

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

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

1763from being interpreted as markdown.

1764

1765Raw TeX

1766-------

1767

1768*Pandoc extension*.

1769

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

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

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

1773LaTeX to include BibTeX citations:

1774

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

1776

1777Note that in LaTeX environments, like

1778

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

1780 Age & Frequency \\ \hline

1781 18--25 & 15 \\

1782 26--35 & 33 \\

1783 36--45 & 22 \\ \hline

1784 \end{tabular}

1785

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

1787LaTeX, not as markdown.

1788

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

1790and ConTeXt.

1791

1792### Macros ###

1793

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

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

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

1797not just LaTeX:

1798

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

1800

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

1802

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

1804unchanged to the output.

1805

1806

1807Links

1808-----

1809

1810Markdown allows links to be specified in several ways.

1811

1812### Automatic links ###

1813

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

1815will become a link:

1816

1817 <http://google.com>

1818 <sam@green.eggs.ham>

1819

1820

1821### Inline links ###

1822

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

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

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

1826

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

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

1829

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

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

1832

1833

1834### Reference links ###

1835

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

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

1838before or after the link).

1839

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

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

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

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

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

1845parentheses.

1846

1847Here are some examples:

1848

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

1850 [my label 2]: /foo

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

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

1853

1854The URL may optionally be surrounded by angle brackets:

1855

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

1857

1858The title may go on the next line:

1859

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

1861 "The free software foundation"

1862

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

1864

1865 Here is [my link][FOO]

1866

1867 [Foo]: /bar/baz

1868

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

1870empty, or omitted entirely:

1871

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

1873

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

1875

1876

1877Images

1878------

1879

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

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

1882

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

1884

1885 ![movie reel]

1886

1887 [movie reel]: movie.gif

1888

1889### Pictures with captions ###

1890

1891*Pandoc extension*.

1892

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

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

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

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

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

1898

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

1900

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

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

1903 itself, with no caption.

1904

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

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

1907nonbreaking space after the image:

1908

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

1910

1911

1912Footnotes

1913---------

1914

1915*Pandoc extension*.

1916

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

1918

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

1920

1921 [^1]: Here is the footnote.

1922

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

1924

1925 Subsequent paragraphs are indented to show that they

1926 belong to the previous footnote.

1927

1928 { some.code }

1929

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

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

1932 multi-paragraph list items.

1933

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

1935 isn't indented.

1936

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

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

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

1940will be numbered sequentially.

1941

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

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

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

1945

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

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

1948

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

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

1951 note.]

1952

1953Inline and regular footnotes may be mixed freely.

1954

1955

1956Citations

1957---------

1958

1959*Pandoc extension*.

1960

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

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

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

1964

1965 Format File extension

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

1967 MODS .mods

1968 BibTeX/BibLaTeX .bib

1969 RIS .ris

1970 EndNote .enl

1971 EndNote XML .xml

1972 ISI .wos

1973 MEDLINE .medline

1974 Copac .copac

1975 JSON citeproc .json

1976

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

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

1979bibliographies).

1980

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

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

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

1984creating and modifying CSL styles can be found at

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

1986A repository of CSL styles can be found at

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

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

1989

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

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

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

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

1994

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

1996

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

1998

1999 Blah blah [@smith04; @doe99].

2000

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

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

2003author is already mentioned in the text:

2004

2005 Smith says blah [-@smith04].

2006

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

2008

2009 @smith04 says blah.

2010

2011 @smith04 [p. 33] says blah.

2012

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

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

2015document with an appropriate header:

2016

2017 last paragraph...

2018

2019 # References

2020

2021The bibliography will be inserted after this header.

2022

2023

2024Producing slide shows with Pandoc

2025=================================

2026

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

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

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

2030show using LaTeX [beamer].

2031

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

2033

2034 % Habits

2035 % John Doe

2036 % March 22, 2005

2037

2038 # In the morning

2039

2040 ## Getting up

2041

2042 - Turn off alarm

2043 - Get out of bed

2044

2045 ## Breakfast

2046

2047 - Eat eggs

2048 - Drink coffee

2049

2050 # In the evening

2051

2052 ## Dinner

2053

2054 - Eat spaghetti

2055 - Drink wine

2056

2057 ------------------

2058

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

2060

2061 ## Going to sleep

2062

2063 - Get in bed

2064 - Count sheep

2065

2066To produce the slide show, simply type

2067

2068 pandoc -t s5 -s habits.txt -o habits.html

2069

2070for S5,

2071

2072 pandoc -t slidy -s habits.txt -o habits.html

2073

2074for Slidy,

2075

2076 pandoc -t dzslides -s habits.txt -o habits.html

2077

2078for DZSlides, or

2079

2080 pandoc -t beamer habits.txt -o habits.pdf

2081

2082for beamer.

2083

2084With all HTML slide formats, the `--self-contained` option can be used to

2085produce a single file that contains all of the data necessary to display the

2086slide show, including linked scripts, stylesheets, images, and videos.

2087

2088Structuring the slide show

2089--------------------------

2090

2091By default, the *slide level* is the highest header level in

2092the hierarchy that is followed immediately by content, and not another

2093header, somewhere in the document. In the example above, level 1 headers

2094are always followed by level 2 headers, which are followed by content,

2095so 2 is the slide level. This default can be overridden using

2096the `--slide-level` option.

2097

2098The document is carved up into slides according to the following

2099rules:

2100

2101 * A horizontal rule always starts a new slide.

2102

2103 * A header at the slide level always starts a new slide.

2104

2105 * Headers *below* the slide level in the hierarchy create

2106 headers *within* a slide.

2107

2108 * Headers *above* the slide level in the hierarchy create

2109 "title slides," which just contain the section title

2110 and help to break the slide show into sections.

2111

2112 * A title page is constructed automatically from the document's title

2113 block, if present. (In the case of beamer, this can be disabled

2114 by commenting out some lines in the default template.)

2115

2116These rules are designed to support many different styles of slide show. If

2117you don't care about structuring your slides into sections and subsections,

2118you can just use level 1 headers for all each slide. (In that case, level 1

2119will be the slide level.) But you can also structure the slide show into

2120sections, as in the example above.

2121

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

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

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

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

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

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

2128

2129Incremental lists

2130-----------------

2131

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

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

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

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

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

2137

2138 > - Eat spaghetti

2139 > - Drink wine

2140

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

2142a single document.

2143

2144Styling the slides

2145------------------

2146

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

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

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

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

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

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

2153

2154For dzslides, the CSS is included in the HTML file itself, and may

2155be modified there.

2156

2157To style beamer slides, you can specify a beamer "theme" or "colortheme"

2158using the `-V` option:

2159

2160 pandoc -t beamer habits.txt -V theme:Warsaw -o habits.pdf

2161

2162Literate Haskell support

2163========================

2164

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

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

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

2168

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

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

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

2172

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

2174 rendered using bird tracks, and block quotations will be

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

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

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

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

2179

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

2181 as Haskell code.

2182

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

2184 be rendered using bird tracks.

2185

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

2187 Haskell code.

2188

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

2190 inside `code` environments.

2191

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

2193 with class `literatehaskell` and bird tracks.

2194

2195Examples:

2196

2197 pandoc -f markdown+lhs -t html

2198

2199reads literate Haskell source formatted with markdown conventions and writes

2200ordinary HTML (without bird tracks).

2201

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

2203

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

2205and pasted as literate Haskell source.

2206

2207Authors

2208=======

2209

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

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

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

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

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

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

2217Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

2218Latter, Ralf Stephan, Eric Seidel, B. Scott Michel.

2219

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

2245[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx

2246[PDF]: http://www.adobe.com/pdf/