README · typeable/pandoc

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

1200

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

1202

1203

1204### Numbered example lists ###

1205

1206*Pandoc extension*.

1207

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

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

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

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

1212where the last stopped. So, for example:

1213

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

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

1216

1217 Explanation of examples.

1218

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

1220

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

1222document:

1223

1224 (@good) This is a good example.

1225

1226 As (@good) illustrates, ...

1227

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

1229or hyphens.

1230

1231

1232### Compact and loose lists ###

1233

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

1235cases" involving lists. Consider this source:

1236

1237 + First

1238 + Second:

1239 - Fee

1240 - Fie

1241 - Foe

1242

1243 + Third

1244

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

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

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

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

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

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

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

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

1253behavior is consistent with the official markdown syntax description,

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

1255

1256

1257### Ending a list ###

1258

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

1260

1261 - item one

1262 - item two

1263

1264 { my code block }

1265

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

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

1268a code block.

1269

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

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

1272any format:

1273

1274 - item one

1275 - item two

1276

1277

1278

1279 { my code block }

1280

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

1282of one big list:

1283

1284 1. one

1285 2. two

1286 3. three

1287

1288

1289

1290 1. uno

1291 2. dos

1292 3. tres

1293

1294Horizontal rules

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

1296

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

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

1300 * * * *

1302 ---------------

1305Tables

1306------

1307

1308*Pandoc extension*.

1309

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

1311a fixed-width font, such as Courier.

1312

1313**Simple tables** look like this:

1314

1315 Right Left Center Default

1316 ------- ------ ---------- -------

1317 12 12 12 12

1318 123 123 123 123

1319 1 1 1 1

1320

1321 Table: Demonstration of simple table syntax.

1322

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

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

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

1326

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

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

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

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

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

1332 the column is centered.

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

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

1335

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

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

1338

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

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

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

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

1343before or after the table.

1344

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

1346to end the table. For example:

1347

1348 ------- ------ ---------- -------

1349 12 12 12 12

1350 123 123 123 123

1351 1 1 1 1

1352 ------- ------ ---------- -------

1353

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

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

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

1357

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

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

1360not supported). Here is an example:

1361

1362 -------------------------------------------------------------

1363 Centered Default Right Left

1364 Header Aligned Aligned Aligned

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

1366 First row 12.0 Example of a row that

1367 spans multiple lines.

1368

1369 Second row 5.0 Here's another one. Note

1370 the blank line between

1371 rows.

1372 -------------------------------------------------------------

1373

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

1375 multiple lines.

1376

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

1378

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

1380 (unless the headers are omitted).

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

1382 - The rows must be separated by blank lines.

1383

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

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

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

1387output, try widening it in the markdown source.

1388

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

1390

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

1392 First row 12.0 Example of a row that

1393 spans multiple lines.

1394

1395 Second row 5.0 Here's another one. Note

1396 the blank line between

1397 rows.

1398 -------------------------------------------------------------

1399

1400 : Here's a multiline table without headers.

1401

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

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

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

1405

1406**Grid tables** look like this:

1407

1408 : Sample grid table.

1409

1410 +---------------+---------------+--------------------+

1411 | Fruit | Price | Advantages |

1412 +===============+===============+====================+

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

1414 | | | - bright color |

1415 +---------------+---------------+--------------------+

1416 | Oranges | $2.10 | - cures scurvy |

1417 | | | - tasty |

1418 +---------------+---------------+--------------------+

1419

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

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

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

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

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

1425

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

1427

1428

1429Title block

1430-----------

1431

1432*Pandoc extension*.

1433

1434If the file begins with a title block

1435

1436 % title

1437 % author(s) (separated by semicolons)

1438 % date

1439

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

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

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

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

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

1445

1446 %

1447 % Author

1448

1449 % My title

1450 %

1451 % June 15, 2006

1452

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

1454begin with leading space, thus:

1455

1456 % My title

1457 on multiple lines

1458

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

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

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

1462

1463 % Author One

1464 Author Two

1465

1466 % Author One; Author Two

1467

1468 % Author One;

1469 Author Two

1470

1471The date must fit on one line.

1472

1473All three metadata fields may contain standard inline formatting

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

1475

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

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

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

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

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

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

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

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

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

1485be used by itself as the HTML title.

1486

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

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

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

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

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

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

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

1494text. Thus,

1495

1496 % PANDOC(1)

1497

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

1499

1500 % PANDOC(1) Pandoc User Manuals

1501

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

1503

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

1505

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

1507

1508

1509Backslash escapes

1510-----------------

1511

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

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

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

1515

1516 *\*hello\**

1517

1518one will get

1519

1520 <em>*hello*</em>

1521

1522instead of

1523

1524 <strong>hello</strong>

1525

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

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

1528

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

1530

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

1532markdown rule will be used.)

1533

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

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

1536`\ `.

1537

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

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

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

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

1542two trailing spaces on a line.

1543

1544Backslash escapes do not work in verbatim contexts.

1545

1546Smart punctuation

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

1548

1549*Pandoc extension*.

1550

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

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

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

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

1555

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

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

1558

1559Inline formatting

1560-----------------

1561

1562### Emphasis ###

1563

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

1565

1566 This text is _emphasized with underscores_, and this

1567 is *emphasized with asterisks*.

1568

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

1570

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

1572

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

1574will not trigger emphasis:

1575

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

1577

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

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

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

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

1582

1583 feas*ible*, not feas*able*.

1584

1585

1586### Strikeout ###

1587

1588*Pandoc extension*.

1589

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

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

1592

1593 This ~~is deleted text.~~

1594

1595

1596### Superscripts and subscripts ###

1597

1598*Pandoc extension*.

1599

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

1601characters; subscripts may be written by surrounding the subscripted

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

1603

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

1605

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

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

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

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

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

1611

1612

1613### Verbatim ###

1614

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

1616

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

1618

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

1620

1621 Here is a literal backtick `` ` ``.

1622

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

1624backticks will be ignored.)

1625

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

1627of consecutive backticks (optionally followed by a space)

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

1629preceded by a space).

1630

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

1632work in verbatim contexts:

1633

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

1635

1636

1637Math

1638----

1639

1640*Pandoc extension*.

1641

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

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

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

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

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

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

1648

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

1650depends on the output format:

1651

1652Markdown, LaTeX, Org-Mode, ConTeXt

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

1654

1655reStructuredText

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

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

1658

1659AsciiDoc

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

1661

1662Texinfo

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

1664

1665groff man

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

1667

1668MediaWiki

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

1670

1671Textile

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

1673

1674RTF, OpenDocument, ODT

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

1676 and will otherwise appear verbatim.

1677

1678Docbook

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

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

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

1682

1683Docx

1684 ~ It will be rendered using OMML math markup.

1685

1686HTML, Slidy, DZSlides, S5, EPUB

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

1688 command-line options selected:

1689

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

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

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

1693 styled differently from the surrounding text if needed.

1694

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

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

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

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

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

1700 verbatim between $ characters.)

1701

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

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

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

1705 it.

1706

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

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

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

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

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

1712

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

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

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

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

1717 procedure is:

1718

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

1720 gladtex -d myfile-images myfile.htex

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

1722

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

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

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

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

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

1728

1729

1730Raw HTML

1731--------

1732

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

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

1735literally).

1736

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

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

1739

1740*Pandoc extension*.

1741

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

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

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

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

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

1747

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

1749pandoc interprets material between HTML block tags as markdown.

1750Thus, for example, Pandoc will turn

1751

1752 <table>

1753 <tr>

1754 <td>*one*</td>

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

1756 </tr>

1757 </table>

1758

1759into

1760

1761 <table>

1762 <tr>

1763 <td><em>one</em></td>

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

1765 </tr>

1766 </table>

1767

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

1769

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

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

1772

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

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

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

1776from being interpreted as markdown.

1777

1778Raw TeX

1779-------

1780

1781*Pandoc extension*.

1782

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

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

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

1786LaTeX to include BibTeX citations:

1787

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

1789

1790Note that in LaTeX environments, like

1791

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

1793 Age & Frequency \\ \hline

1794 18--25 & 15 \\

1795 26--35 & 33 \\

1796 36--45 & 22 \\ \hline

1797 \end{tabular}

1798

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

1800LaTeX, not as markdown.

1801

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

1803and ConTeXt.

1804

1805### Macros ###

1806

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

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

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

1810not just LaTeX:

1811

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

1813

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

1815

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

1817unchanged to the output.

1818

1819

1820Links

1821-----

1822

1823Markdown allows links to be specified in several ways.

1824

1825### Automatic links ###

1826

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

1828will become a link:

1829

1830 <http://google.com>

1831 <sam@green.eggs.ham>

1832

1833

1834### Inline links ###

1835

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

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

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

1839

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

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

1842

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

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

1845

1846

1847### Reference links ###

1848

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

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

1851before or after the link).

1852

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

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

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

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

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

1858parentheses.

1859

1860Here are some examples:

1861

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

1863 [my label 2]: /foo

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

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

1866

1867The URL may optionally be surrounded by angle brackets:

1868

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

1870

1871The title may go on the next line:

1872

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

1874 "The free software foundation"

1875

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

1877

1878 Here is [my link][FOO]

1879

1880 [Foo]: /bar/baz

1881

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

1883empty, or omitted entirely:

1884

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

1886

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

1888

1889### Internal links

1890

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

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

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

1894For example:

1895

1896 See the [Introduction](#introduction).

1897

1898or

1899

1900 See the [Introduction].

1901

1902 [Introduction]: #introduction

1903

1904Internal links are currently supported for HTML formats (including

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

1906

1907Images

1908------

1909

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

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

1912

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

1914

1915 ![movie reel]

1916

1917 [movie reel]: movie.gif

1918

1919### Pictures with captions ###

1920

1921*Pandoc extension*.

1922

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

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

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

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

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

1928

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

1930

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

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

1933 itself, with no caption.

1934

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

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

1937nonbreaking space after the image:

1938

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

1940

1941

1942Footnotes

1943---------

1944

1945*Pandoc extension*.

1946

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

1948

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

1950

1951 [^1]: Here is the footnote.

1952

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

1954

1955 Subsequent paragraphs are indented to show that they

1956 belong to the previous footnote.

1957

1958 { some.code }

1959

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

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

1962 multi-paragraph list items.

1963

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

1965 isn't indented.

1966

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

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

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

1970will be numbered sequentially.

1971

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

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

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

1975

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

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

1978

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

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

1981 note.]

1982

1983Inline and regular footnotes may be mixed freely.

1984

1985

1986Citations

1987---------

1988

1989*Pandoc extension*.

1990

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

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

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

1994

1995 Format File extension

1996 ------------ --------------

1997 MODS .mods

1998 BibTeX/BibLaTeX .bib

1999 RIS .ris

2000 EndNote .enl

2001 EndNote XML .xml

2002 ISI .wos

2003 MEDLINE .medline

2004 Copac .copac

2005 JSON citeproc .json

2006

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

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

2009bibliographies).

2010

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

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

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

2014creating and modifying CSL styles can be found at

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

2016A repository of CSL styles can be found at

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

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

2019

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

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

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

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

2024

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

2026

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

2028

2029 Blah blah [@smith04; @doe99].

2030

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

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

2033author is already mentioned in the text:

2034

2035 Smith says blah [-@smith04].

2036

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

2038

2039 @smith04 says blah.

2040

2041 @smith04 [p. 33] says blah.

2042

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

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

2045document with an appropriate header:

2046

2047 last paragraph...

2048

2049 # References

2050

2051The bibliography will be inserted after this header.

2052

2053

2054Producing slide shows with Pandoc

2055=================================

2056

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

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

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

2060show using LaTeX [beamer].

2061

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

2063

2064 % Habits

2065 % John Doe

2066 % March 22, 2005

2067

2068 # In the morning

2069

2070 ## Getting up

2071

2072 - Turn off alarm

2073 - Get out of bed

2074

2075 ## Breakfast

2076

2077 - Eat eggs

2078 - Drink coffee

2079

2080 # In the evening

2081

2082 ## Dinner

2083

2084 - Eat spaghetti

2085 - Drink wine

2086

2087 ------------------

2088

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

2090

2091 ## Going to sleep

2092

2093 - Get in bed

2094 - Count sheep

2095

2096To produce the slide show, simply type

2097

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

2099

2100for S5,

2101

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

2103

2104for Slidy,

2105

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

2107

2108for DZSlides, or

2109

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

2111

2112for beamer.

2113

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

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

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

2117

2118Structuring the slide show

2119--------------------------

2120

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

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

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

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

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

2126the `--slide-level` option.

2127

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

2129rules:

2130

2131 * A horizontal rule always starts a new slide.

2132

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

2134

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

2136 headers *within* a slide.

2137

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

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

2140 and help to break the slide show into sections.

2141

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

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

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

2145

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

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

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

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

2150sections, as in the example above.

2151

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

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

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

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

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

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

2158

2159Incremental lists

2160-----------------

2161

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

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

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

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

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

2167

2168 > - Eat spaghetti

2169 > - Drink wine

2170

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

2172a single document.

2173

2174Styling the slides

2175------------------

2176

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

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

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

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

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

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

2183

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

2185be modified there.

2186

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

2188using the `-V` option:

2189

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

2191

2192Literate Haskell support

2193========================

2194

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

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

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

2198This means that

2199

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

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

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

2203

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

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

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

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

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

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

2210

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

2212 as Haskell code.

2213

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

2215 be rendered using bird tracks.

2216

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

2218 Haskell code.

2219

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

2221 inside `code` environments.

2222

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

2224 with class `literatehaskell` and bird tracks.

2225

2226Examples:

2227

2228 pandoc -f markdown+lhs -t html

2229

2230reads literate Haskell source formatted with markdown conventions and writes

2231ordinary HTML (without bird tracks).

2232

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

2234

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

2236and pasted as literate Haskell source.

2237

2238Authors

2239=======

2240

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

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

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

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

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

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

2248Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2250

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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