README · typeable/pandoc

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

1193

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

1195

1196

1197### Numbered example lists ###

1198

1199*Pandoc extension*.

1200

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

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

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

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

1205where the last stopped. So, for example:

1206

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

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

1209

1210 Explanation of examples.

1211

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

1213

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

1215document:

1216

1217 (@good) This is a good example.

1218

1219 As (@good) illustrates, ...

1220

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

1222or hyphens.

1223

1224

1225### Compact and loose lists ###

1226

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

1228cases" involving lists. Consider this source:

1229

1230 + First

1231 + Second:

1232 - Fee

1233 - Fie

1234 - Foe

1235

1236 + Third

1237

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

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

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

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

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

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

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

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

1246behavior is consistent with the official markdown syntax description,

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

1248

1249

1250### Ending a list ###

1251

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

1253

1254 - item one

1255 - item two

1256

1257 { my code block }

1258

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

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

1261a code block.

1262

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

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

1265any format:

1266

1267 - item one

1268 - item two

1269

1270

1271

1272 { my code block }

1273

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

1275of one big list:

1276

1277 1. one

1278 2. two

1279 3. three

1280

1281

1282

1283 1. uno

1284 2. dos

1285 3. tres

1286

1287Horizontal rules

1288----------------

1289

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

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

1293 * * * *

1295 ---------------

1298Tables

1299------

1300

1301*Pandoc extension*.

1302

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

1304a fixed-width font, such as Courier.

1305

1306**Simple tables** look like this:

1307

1308 Right Left Center Default

1309 ------- ------ ---------- -------

1310 12 12 12 12

1311 123 123 123 123

1312 1 1 1 1

1313

1314 Table: Demonstration of simple table syntax.

1315

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

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

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

1319

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

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

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

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

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

1325 the column is centered.

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

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

1328

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

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

1331

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

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

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

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

1336before or after the table.

1337

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

1339to end the table. For example:

1340

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

1342 12 12 12 12

1343 123 123 123 123

1344 1 1 1 1

1345 ------- ------ ---------- -------

1346

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

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

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

1350

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

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

1353not supported). Here is an example:

1354

1355 -------------------------------------------------------------

1356 Centered Default Right Left

1357 Header Aligned Aligned Aligned

1358 ----------- ------- --------------- -------------------------

1359 First row 12.0 Example of a row that

1360 spans multiple lines.

1361

1362 Second row 5.0 Here's another one. Note

1363 the blank line between

1364 rows.

1365 -------------------------------------------------------------

1366

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

1368 multiple lines.

1369

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

1371

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

1373 (unless the headers are omitted).

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

1375 - The rows must be separated by blank lines.

1376

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

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

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

1380output, try widening it in the markdown source.

1381

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

1383

1384 ----------- ------- --------------- -------------------------

1385 First row 12.0 Example of a row that

1386 spans multiple lines.

1387

1388 Second row 5.0 Here's another one. Note

1389 the blank line between

1390 rows.

1391 -------------------------------------------------------------

1392

1393 : Here's a multiline table without headers.

1394

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

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

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

1398

1399**Grid tables** look like this:

1400

1401 : Sample grid table.

1402

1403 +---------------+---------------+--------------------+

1404 | Fruit | Price | Advantages |

1405 +===============+===============+====================+

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

1407 | | | - bright color |

1408 +---------------+---------------+--------------------+

1409 | Oranges | $2.10 | - cures scurvy |

1410 | | | - tasty |

1411 +---------------+---------------+--------------------+

1412

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

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

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

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

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

1418

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

1420

1421

1422Title block

1423-----------

1424

1425*Pandoc extension*.

1426

1427If the file begins with a title block

1428

1429 % title

1430 % author(s) (separated by semicolons)

1431 % date

1432

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

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

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

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

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

1438

1439 %

1440 % Author

1441

1442 % My title

1443 %

1444 % June 15, 2006

1445

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

1447begin with leading space, thus:

1448

1449 % My title

1450 on multiple lines

1451

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

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

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

1455

1456 % Author One

1457 Author Two

1458

1459 % Author One; Author Two

1460

1461 % Author One;

1462 Author Two

1463

1464The date must fit on one line.

1465

1466All three metadata fields may contain standard inline formatting

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

1468

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

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

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

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

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

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

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

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

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

1478be used by itself as the HTML title.

1479

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

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

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

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

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

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

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

1487text. Thus,

1488

1489 % PANDOC(1)

1490

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

1492

1493 % PANDOC(1) Pandoc User Manuals

1494

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

1496

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

1498

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

1500

1501

1502Backslash escapes

1503-----------------

1504

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

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

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

1508

1509 *\*hello\**

1510

1511one will get

1512

1513 <em>*hello*</em>

1514

1515instead of

1516

1517 <strong>hello</strong>

1518

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

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

1521

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

1523

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

1525markdown rule will be used.)

1526

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

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

1529`\ `.

1530

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

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

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

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

1535two trailing spaces on a line.

1536

1537Backslash escapes do not work in verbatim contexts.

1538

1539Smart punctuation

1540-----------------

1541

1542*Pandoc extension*.

1543

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

1545correct output, converting straight quotes to curly quotes, `---` to

1546em-dashes, `--` to en-dashes, and `...` to ellipses. Nonbreaking spaces

1547are inserted after certain abbreviations, such as "Mr."

1548

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

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

1551

1552Inline formatting

1553-----------------

1554

1555### Emphasis ###

1556

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

1558

1559 This text is _emphasized with underscores_, and this

1560 is *emphasized with asterisks*.

1561

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

1563

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

1565

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

1567will not trigger emphasis:

1568

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

1570

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

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

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

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

1575

1576 feas*ible*, not feas*able*.

1577

1578

1579### Strikeout ###

1580

1581*Pandoc extension*.

1582

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

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

1585

1586 This ~~is deleted text.~~

1587

1588

1589### Superscripts and subscripts ###

1590

1591*Pandoc extension*.

1592

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

1594characters; subscripts may be written by surrounding the subscripted

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

1596

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

1598

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

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

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

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

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

1604

1605

1606### Verbatim ###

1607

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

1609

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

1611

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

1613

1614 Here is a literal backtick `` ` ``.

1615

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

1617backticks will be ignored.)

1618

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

1620of consecutive backticks (optionally followed by a space)

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

1622preceded by a space).

1623

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

1625work in verbatim contexts:

1626

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

1628

1629

1630Math

1631----

1632

1633*Pandoc extension*.

1634

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

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

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

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

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

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

1641

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

1643depends on the output format:

1644

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

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

1647

1648reStructuredText

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

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

1651

1652AsciiDoc

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

1654

1655Texinfo

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

1657

1658groff man

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

1660

1661MediaWiki

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

1663

1664Textile

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

1666

1667RTF, OpenDocument, ODT

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

1669 and will otherwise appear verbatim.

1670

1671Docbook

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

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

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

1675

1676Docx

1677 ~ It will be rendered using OMML math markup.

1678

1679HTML, Slidy, DZSlides, S5, EPUB

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

1681 command-line options selected:

1682

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

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

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

1686 styled differently from the surrounding text if needed.

1687

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

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

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

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

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

1693 verbatim between $ characters.)

1694

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

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

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

1698 it.

1699

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

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

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

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

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

1705

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

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

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

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

1710 procedure is:

1711

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

1713 gladtex -d myfile-images myfile.htex

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

1715

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

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

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

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

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

1721

1722

1723Raw HTML

1724--------

1725

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

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

1728literally).

1729

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

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

1732

1733*Pandoc extension*.

1734

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

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

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

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

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

1740

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

1742pandoc interprets material between HTML block tags as markdown.

1743Thus, for example, Pandoc will turn

1744

1745 <table>

1746 <tr>

1747 <td>*one*</td>

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

1749 </tr>

1750 </table>

1751

1752into

1753

1754 <table>

1755 <tr>

1756 <td><em>one</em></td>

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

1758 </tr>

1759 </table>

1760

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

1762

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

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

1765

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

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

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

1769from being interpreted as markdown.

1770

1771Raw TeX

1772-------

1773

1774*Pandoc extension*.

1775

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

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

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

1779LaTeX to include BibTeX citations:

1780

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

1782

1783Note that in LaTeX environments, like

1784

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

1786 Age & Frequency \\ \hline

1787 18--25 & 15 \\

1788 26--35 & 33 \\

1789 36--45 & 22 \\ \hline

1790 \end{tabular}

1791

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

1793LaTeX, not as markdown.

1794

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

1796and ConTeXt.

1797

1798### Macros ###

1799

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

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

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

1803not just LaTeX:

1804

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

1806

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

1808

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

1810unchanged to the output.

1811

1812

1813Links

1814-----

1815

1816Markdown allows links to be specified in several ways.

1817

1818### Automatic links ###

1819

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

1821will become a link:

1822

1823 <http://google.com>

1824 <sam@green.eggs.ham>

1825

1826

1827### Inline links ###

1828

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

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

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

1832

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

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

1835

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

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

1838

1839

1840### Reference links ###

1841

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

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

1844before or after the link).

1845

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

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

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

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

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

1851parentheses.

1852

1853Here are some examples:

1854

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

1856 [my label 2]: /foo

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

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

1859

1860The URL may optionally be surrounded by angle brackets:

1861

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

1863

1864The title may go on the next line:

1865

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

1867 "The free software foundation"

1868

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

1870

1871 Here is [my link][FOO]

1872

1873 [Foo]: /bar/baz

1874

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

1876empty, or omitted entirely:

1877

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

1879

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

1881

1882

1883Images

1884------

1885

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

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

1888

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

1890

1891 ![movie reel]

1892

1893 [movie reel]: movie.gif

1894

1895### Pictures with captions ###

1896

1897*Pandoc extension*.

1898

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

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

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

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

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

1904

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

1906

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

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

1909 itself, with no caption.

1910

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

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

1913nonbreaking space after the image:

1914

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

1916

1917

1918Footnotes

1919---------

1920

1921*Pandoc extension*.

1922

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

1924

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

1926

1927 [^1]: Here is the footnote.

1928

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

1930

1931 Subsequent paragraphs are indented to show that they

1932 belong to the previous footnote.

1933

1934 { some.code }

1935

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

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

1938 multi-paragraph list items.

1939

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

1941 isn't indented.

1942

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

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

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

1946will be numbered sequentially.

1947

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

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

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

1951

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

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

1954

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

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

1957 note.]

1958

1959Inline and regular footnotes may be mixed freely.

1960

1961

1962Citations

1963---------

1964

1965*Pandoc extension*.

1966

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

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

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

1970

1971 Format File extension

1972 ------------ --------------

1973 MODS .mods

1974 BibTeX/BibLaTeX .bib

1975 RIS .ris

1976 EndNote .enl

1977 EndNote XML .xml

1978 ISI .wos

1979 MEDLINE .medline

1980 Copac .copac

1981 JSON citeproc .json

1982

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

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

1985bibliographies).

1986

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

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

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

1990creating and modifying CSL styles can be found at

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

1992A repository of CSL styles can be found at

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

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

1995

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

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

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

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

2000

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

2002

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

2004

2005 Blah blah [@smith04; @doe99].

2006

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

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

2009author is already mentioned in the text:

2010

2011 Smith says blah [-@smith04].

2012

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

2014

2015 @smith04 says blah.

2016

2017 @smith04 [p. 33] says blah.

2018

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

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

2021document with an appropriate header:

2022

2023 last paragraph...

2024

2025 # References

2026

2027The bibliography will be inserted after this header.

2028

2029

2030Producing slide shows with Pandoc

2031=================================

2032

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

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

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

2036show using LaTeX [beamer].

2037

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

2039

2040 % Habits

2041 % John Doe

2042 % March 22, 2005

2043

2044 # In the morning

2045

2046 ## Getting up

2047

2048 - Turn off alarm

2049 - Get out of bed

2050

2051 ## Breakfast

2052

2053 - Eat eggs

2054 - Drink coffee

2055

2056 # In the evening

2057

2058 ## Dinner

2059

2060 - Eat spaghetti

2061 - Drink wine

2062

2063 ------------------

2064

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

2066

2067 ## Going to sleep

2068

2069 - Get in bed

2070 - Count sheep

2071

2072To produce the slide show, simply type

2073

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

2075

2076for S5,

2077

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

2079

2080for Slidy,

2081

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

2083

2084for DZSlides, or

2085

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

2087

2088for beamer.

2089

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

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

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

2093

2094Structuring the slide show

2095--------------------------

2096

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

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

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

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

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

2102the `--slide-level` option.

2103

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

2105rules:

2106

2107 * A horizontal rule always starts a new slide.

2108

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

2110

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

2112 headers *within* a slide.

2113

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

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

2116 and help to break the slide show into sections.

2117

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

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

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

2121

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

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

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

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

2126sections, as in the example above.

2127

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

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

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

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

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

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

2134

2135Incremental lists

2136-----------------

2137

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

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

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

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

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

2143

2144 > - Eat spaghetti

2145 > - Drink wine

2146

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

2148a single document.

2149

2150Styling the slides

2151------------------

2152

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

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

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

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

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

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

2159

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

2161be modified there.

2162

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

2164using the `-V` option:

2165

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

2167

2168Literate Haskell support

2169========================

2170

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

2172`rst`, or `latex` for input or output; `beamer`, `html` or `html5` for

2173output only), pandoc will treat the document as literate Haskell source.

2174This means that

2175

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

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

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

2179

2180 - In markdown output, code blocks with classes `haskell` and `literate`

2181 will be rendered using bird tracks, and block quotations will be

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

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

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

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

2186

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

2188 as Haskell code.

2189

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

2191 be rendered using bird tracks.

2192

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

2194 Haskell code.

2195

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

2197 inside `code` environments.

2198

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

2200 with class `literatehaskell` and bird tracks.

2201

2202Examples:

2203

2204 pandoc -f markdown+lhs -t html

2205

2206reads literate Haskell source formatted with markdown conventions and writes

2207ordinary HTML (without bird tracks).

2208

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

2210

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

2212and pasted as literate Haskell source.

2213

2214Authors

2215=======

2216

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

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

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

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

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

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

2224Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2226

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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