README · typeable/pandoc

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

1216

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

1218

1219

1220### Numbered example lists ###

1221

1222*Pandoc extension*.

1223

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

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

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

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

1228where the last stopped. So, for example:

1229

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

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

1232

1233 Explanation of examples.

1234

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

1236

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

1238document:

1239

1240 (@good) This is a good example.

1241

1242 As (@good) illustrates, ...

1243

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

1245or hyphens.

1246

1247

1248### Compact and loose lists ###

1249

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

1251cases" involving lists. Consider this source:

1252

1253 + First

1254 + Second:

1255 - Fee

1256 - Fie

1257 - Foe

1258

1259 + Third

1260

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

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

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

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

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

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

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

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

1269behavior is consistent with the official markdown syntax description,

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

1271

1272

1273### Ending a list ###

1274

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

1276

1277 - item one

1278 - item two

1279

1280 { my code block }

1281

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

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

1284a code block.

1285

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

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

1288any format:

1289

1290 - item one

1291 - item two

1292

1293

1294

1295 { my code block }

1296

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

1298of one big list:

1299

1300 1. one

1301 2. two

1302 3. three

1303

1304

1305

1306 1. uno

1307 2. dos

1308 3. tres

1309

1310Horizontal rules

1311----------------

1312

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

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

1316 * * * *

1318 ---------------

1321Tables

1322------

1323

1324*Pandoc extension*.

1325

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

1327a fixed-width font, such as Courier.

1328

1329**Simple tables** look like this:

1330

1331 Right Left Center Default

1332 ------- ------ ---------- -------

1333 12 12 12 12

1334 123 123 123 123

1335 1 1 1 1

1336

1337 Table: Demonstration of simple table syntax.

1338

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

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

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

1342

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

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

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

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

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

1348 the column is centered.

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

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

1351

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

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

1354

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

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

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

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

1359before or after the table.

1360

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

1362to end the table. For example:

1363

1364 ------- ------ ---------- -------

1365 12 12 12 12

1366 123 123 123 123

1367 1 1 1 1

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

1369

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

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

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

1373

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

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

1376not supported). Here is an example:

1377

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

1379 Centered Default Right Left

1380 Header Aligned Aligned Aligned

1381 ----------- ------- --------------- -------------------------

1382 First row 12.0 Example of a row that

1383 spans multiple lines.

1384

1385 Second row 5.0 Here's another one. Note

1386 the blank line between

1387 rows.

1388 -------------------------------------------------------------

1389

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

1391 multiple lines.

1392

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

1394

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

1396 (unless the headers are omitted).

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

1398 - The rows must be separated by blank lines.

1399

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

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

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

1403output, try widening it in the markdown source.

1404

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

1406

1407 ----------- ------- --------------- -------------------------

1408 First row 12.0 Example of a row that

1409 spans multiple lines.

1410

1411 Second row 5.0 Here's another one. Note

1412 the blank line between

1413 rows.

1414 -------------------------------------------------------------

1415

1416 : Here's a multiline table without headers.

1417

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

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

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

1421

1422**Grid tables** look like this:

1423

1424 : Sample grid table.

1425

1426 +---------------+---------------+--------------------+

1427 | Fruit | Price | Advantages |

1428 +===============+===============+====================+

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

1430 | | | - bright color |

1431 +---------------+---------------+--------------------+

1432 | Oranges | $2.10 | - cures scurvy |

1433 | | | - tasty |

1434 +---------------+---------------+--------------------+

1435

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

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

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

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

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

1441

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

1443

1444

1445Title block

1446-----------

1447

1448*Pandoc extension*.

1449

1450If the file begins with a title block

1451

1452 % title

1453 % author(s) (separated by semicolons)

1454 % date

1455

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

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

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

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

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

1461

1462 %

1463 % Author

1464

1465 % My title

1466 %

1467 % June 15, 2006

1468

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

1470begin with leading space, thus:

1471

1472 % My title

1473 on multiple lines

1474

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

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

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

1478

1479 % Author One

1480 Author Two

1481

1482 % Author One; Author Two

1483

1484 % Author One;

1485 Author Two

1486

1487The date must fit on one line.

1488

1489All three metadata fields may contain standard inline formatting

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

1491

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

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

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

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

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

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

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

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

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

1501be used by itself as the HTML title.

1502

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

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

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

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

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

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

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

1510text. Thus,

1511

1512 % PANDOC(1)

1513

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

1515

1516 % PANDOC(1) Pandoc User Manuals

1517

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

1519

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

1521

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

1523

1524

1525Backslash escapes

1526-----------------

1527

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

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

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

1531

1532 *\*hello\**

1533

1534one will get

1535

1536 <em>*hello*</em>

1537

1538instead of

1539

1540 <strong>hello</strong>

1541

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

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

1544

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

1546

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

1548markdown rule will be used.)

1549

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

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

1552`\ `.

1553

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

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

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

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

1558two trailing spaces on a line.

1559

1560Backslash escapes do not work in verbatim contexts.

1561

1562Smart punctuation

1563-----------------

1564

1565*Pandoc extension*.

1566

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

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

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

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

1571

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

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

1574

1575Inline formatting

1576-----------------

1577

1578### Emphasis ###

1579

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

1581

1582 This text is _emphasized with underscores_, and this

1583 is *emphasized with asterisks*.

1584

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

1586

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

1588

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

1590will not trigger emphasis:

1591

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

1593

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

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

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

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

1598

1599 feas*ible*, not feas*able*.

1600

1601

1602### Strikeout ###

1603

1604*Pandoc extension*.

1605

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

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

1608

1609 This ~~is deleted text.~~

1610

1611

1612### Superscripts and subscripts ###

1613

1614*Pandoc extension*.

1615

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

1617characters; subscripts may be written by surrounding the subscripted

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

1619

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

1621

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

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

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

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

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

1627

1628

1629### Verbatim ###

1630

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

1632

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

1634

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

1636

1637 Here is a literal backtick `` ` ``.

1638

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

1640backticks will be ignored.)

1641

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

1643of consecutive backticks (optionally followed by a space)

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

1645preceded by a space).

1646

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

1648work in verbatim contexts:

1649

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

1651

1652Attributes can be attached to verbatim text, just as with

1653[delimited code blocks](#delimited-code-blocks):

1654

1655 `<$>`{.haskell}

1656

1657Math

1658----

1659

1660*Pandoc extension*.

1661

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

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

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

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

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

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

1668

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

1670depends on the output format:

1671

1672Markdown, LaTeX, Org-Mode, ConTeXt

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

1674

1675reStructuredText

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

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

1678

1679AsciiDoc

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

1681

1682Texinfo

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

1684

1685groff man

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

1687

1688MediaWiki

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

1690

1691Textile

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

1693

1694RTF, OpenDocument, ODT

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

1696 and will otherwise appear verbatim.

1697

1698Docbook

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

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

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

1702

1703Docx

1704 ~ It will be rendered using OMML math markup.

1705

1706HTML, Slidy, Slideous, DZSlides, S5, EPUB

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

1708 command-line options selected:

1709

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

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

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

1713 styled differently from the surrounding text if needed.

1714

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

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

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

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

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

1720 verbatim between $ characters.)

1721

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

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

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

1725 it.

1726

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

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

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

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

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

1732

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

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

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

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

1737 procedure is:

1738

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

1740 gladtex -d myfile-images myfile.htex

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

1742

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

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

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

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

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

1748

1749

1750Raw HTML

1751--------

1752

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

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

1755literally).

1756

1757The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous,

1758DZSlides, EPUB,

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

1760

1761*Pandoc extension*.

1762

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

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

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

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

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

1768

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

1770pandoc interprets material between HTML block tags as markdown.

1771Thus, for example, Pandoc will turn

1772

1773 <table>

1774 <tr>

1775 <td>*one*</td>

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

1777 </tr>

1778 </table>

1779

1780into

1781

1782 <table>

1783 <tr>

1784 <td><em>one</em></td>

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

1786 </tr>

1787 </table>

1788

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

1790

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

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

1793

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

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

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

1797from being interpreted as markdown.

1798

1799Raw TeX

1800-------

1801

1802*Pandoc extension*.

1803

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

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

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

1807LaTeX to include BibTeX citations:

1808

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

1810

1811Note that in LaTeX environments, like

1812

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

1814 Age & Frequency \\ \hline

1815 18--25 & 15 \\

1816 26--35 & 33 \\

1817 36--45 & 22 \\ \hline

1818 \end{tabular}

1819

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

1821LaTeX, not as markdown.

1822

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

1824and ConTeXt.

1825

1826### Macros ###

1827

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

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

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

1831not just LaTeX:

1832

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

1834

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

1836

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

1838unchanged to the output.

1839

1840

1841Links

1842-----

1843

1844Markdown allows links to be specified in several ways.

1845

1846### Automatic links ###

1847

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

1849will become a link:

1850

1851 <http://google.com>

1852 <sam@green.eggs.ham>

1853

1854

1855### Inline links ###

1856

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

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

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

1860

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

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

1863

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

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

1866

1867

1868### Reference links ###

1869

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

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

1872before or after the link).

1873

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

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

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

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

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

1879parentheses.

1880

1881Here are some examples:

1882

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

1884 [my label 2]: /foo

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

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

1887

1888The URL may optionally be surrounded by angle brackets:

1889

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

1891

1892The title may go on the next line:

1893

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

1895 "The free software foundation"

1896

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

1898

1899 Here is [my link][FOO]

1900

1901 [Foo]: /bar/baz

1902

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

1904empty, or omitted entirely:

1905

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

1907

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

1909

1910### Internal links

1911

1912To link to another section of the same document, use the automatically

1913generated identifier (see [Header identifiers in HTML, LaTeX, and

1914ConTeXt](#header-identifiers-in-html-latex-and-context), below).

1915For example:

1916

1917 See the [Introduction](#introduction).

1918

1919or

1920

1921 See the [Introduction].

1922

1923 [Introduction]: #introduction

1924

1925Internal links are currently supported for HTML formats (including

1926HTML slide shows and EPUB), LaTeX, and ConTeXt.

1927

1928Images

1929------

1930

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

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

1933

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

1935

1936 ![movie reel]

1937

1938 [movie reel]: movie.gif

1939

1940### Pictures with captions ###

1941

1942*Pandoc extension*.

1943

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

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

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

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

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

1949

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

1951

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

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

1954 itself, with no caption.

1955

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

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

1958nonbreaking space after the image:

1959

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

1961

1962

1963Footnotes

1964---------

1965

1966*Pandoc extension*.

1967

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

1969

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

1971

1972 [^1]: Here is the footnote.

1973

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

1975

1976 Subsequent paragraphs are indented to show that they

1977 belong to the previous footnote.

1978

1979 { some.code }

1980

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

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

1983 multi-paragraph list items.

1984

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

1986 isn't indented.

1987

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

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

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

1991will be numbered sequentially.

1992

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

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

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

1996

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

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

1999

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

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

2002 note.]

2003

2004Inline and regular footnotes may be mixed freely.

2005

2006

2007Citations

2008---------

2009

2010*Pandoc extension*.

2011

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

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

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

2015

2016 Format File extension

2017 ------------ --------------

2018 MODS .mods

2019 BibTeX/BibLaTeX .bib

2020 RIS .ris

2021 EndNote .enl

2022 EndNote XML .xml

2023 ISI .wos

2024 MEDLINE .medline

2025 Copac .copac

2026 JSON citeproc .json

2027

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

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

2030bibliographies).

2031

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

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

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

2035creating and modifying CSL styles can be found at

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

2037A repository of CSL styles can be found at

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

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

2040

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

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

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

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

2045

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

2047

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

2049

2050 Blah blah [@smith04; @doe99].

2051

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

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

2054author is already mentioned in the text:

2055

2056 Smith says blah [-@smith04].

2057

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

2059

2060 @smith04 says blah.

2061

2062 @smith04 [p. 33] says blah.

2063

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

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

2066document with an appropriate header:

2067

2068 last paragraph...

2069

2070 # References

2071

2072The bibliography will be inserted after this header.

2073

2074

2075Producing slide shows with Pandoc

2076=================================

2077

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

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

2080using [S5], [DZSlides], [Slidy], or [Slideous]. You can also produce a

2081PDF slide show using LaTeX [beamer].

2082

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

2084

2085 % Habits

2086 % John Doe

2087 % March 22, 2005

2088

2089 # In the morning

2090

2091 ## Getting up

2092

2093 - Turn off alarm

2094 - Get out of bed

2095

2096 ## Breakfast

2097

2098 - Eat eggs

2099 - Drink coffee

2100

2101 # In the evening

2102

2103 ## Dinner

2104

2105 - Eat spaghetti

2106 - Drink wine

2107

2108 ------------------

2109

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

2111

2112 ## Going to sleep

2113

2114 - Get in bed

2115 - Count sheep

2116

2117To produce the slide show, simply type

2118

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

2120

2121for S5,

2122

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

2124

2125for Slidy,

2126

2127 pandoc -t slideous -s habits.txt -o habits.html

2128

2129for Slideous,

2130

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

2132

2133for DZSlides, or

2134

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

2136

2137for beamer.

2138

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

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

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

2142

2143Structuring the slide show

2144--------------------------

2145

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

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

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

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

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

2151the `--slide-level` option.

2152

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

2154rules:

2155

2156 * A horizontal rule always starts a new slide.

2157

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

2159

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

2161 headers *within* a slide.

2162

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

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

2165 and help to break the slide show into sections.

2166

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

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

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

2170

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

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

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

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

2175sections, as in the example above.

2176

2177For Slidy, Slideous and S5, the file produced by pandoc with the

2178`-s/--standalone`

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

2180be available at the relative path `s5/default` (for S5) or `slideous`

2181(for Slideous), or at the Slidy

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

2183the `slidy-url`, `slideous-url` or `s5-url` variables; see `--variable`,

2184above.) For DZSlides,

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

2186

2187Incremental lists

2188-----------------

2189

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

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

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

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

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

2195

2196 > - Eat spaghetti

2197 > - Drink wine

2198

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

2200a single document.

2201

2202Styling the slides

2203------------------

2204

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

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

2207or `$DATADIR/slideous` (for Slideous),

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

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

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

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

2212

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

2214be modified there.

2215

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

2217using the `-V` option:

2218

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

2220

2221Literate Haskell support

2222========================

2223

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

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

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

2227This means that

2228

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

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

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

2232

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

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

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

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

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

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

2239

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

2241 as Haskell code.

2242

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

2244 be rendered using bird tracks.

2245

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

2247 Haskell code.

2248

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

2250 inside `code` environments.

2251

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

2253 with class `literatehaskell` and bird tracks.

2254

2255Examples:

2256

2257 pandoc -f markdown+lhs -t html

2258

2259reads literate Haskell source formatted with markdown conventions and writes

2260ordinary HTML (without bird tracks).

2261

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

2263

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

2265and pasted as literate Haskell source.

2266

2267Authors

2268=======

2269

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

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

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

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

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

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

2277Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2279

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

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

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

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

2284[Slideous]: http://goessner.net/articles/slideous/

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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