README · typeable/pandoc

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

1188

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

1190

1191

1192### Numbered example lists ###

1193

1194*Pandoc extension*.

1195

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

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

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

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

1200where the last stopped. So, for example:

1201

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

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

1204

1205 Explanation of examples.

1206

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

1208

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

1210document:

1211

1212 (@good) This is a good example.

1213

1214 As (@good) illustrates, ...

1215

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

1217or hyphens.

1218

1219

1220### Compact and loose lists ###

1221

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

1223cases" involving lists. Consider this source:

1224

1225 + First

1226 + Second:

1227 - Fee

1228 - Fie

1229 - Foe

1230

1231 + Third

1232

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

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

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

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

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

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

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

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

1241behavior is consistent with the official markdown syntax description,

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

1243

1244

1245### Ending a list ###

1246

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

1248

1249 - item one

1250 - item two

1251

1252 { my code block }

1253

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

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

1256a code block.

1257

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

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

1260any format:

1261

1262 - item one

1263 - item two

1264

1265

1266

1267 { my code block }

1268

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

1270of one big list:

1271

1272 1. one

1273 2. two

1274 3. three

1275

1276

1277

1278 1. uno

1279 2. dos

1280 3. tres

1281

1282Horizontal rules

1283----------------

1284

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

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

1288 * * * *

1290 ---------------

1293Tables

1294------

1295

1296*Pandoc extension*.

1297

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

1299a fixed-width font, such as Courier.

1300

1301**Simple tables** look like this:

1302

1303 Right Left Center Default

1304 ------- ------ ---------- -------

1305 12 12 12 12

1306 123 123 123 123

1307 1 1 1 1

1308

1309 Table: Demonstration of simple table syntax.

1310

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

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

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

1314

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

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

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

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

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

1320 the column is centered.

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

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

1323

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

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

1326

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

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

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

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

1331before or after the table.

1332

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

1334to end the table. For example:

1335

1336 ------- ------ ---------- -------

1337 12 12 12 12

1338 123 123 123 123

1339 1 1 1 1

1340 ------- ------ ---------- -------

1341

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

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

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

1345

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

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

1348not supported). Here is an example:

1349

1350 -------------------------------------------------------------

1351 Centered Default Right Left

1352 Header Aligned Aligned Aligned

1353 ----------- ------- --------------- -------------------------

1354 First row 12.0 Example of a row that

1355 spans multiple lines.

1356

1357 Second row 5.0 Here's another one. Note

1358 the blank line between

1359 rows.

1360 -------------------------------------------------------------

1361

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

1363 multiple lines.

1364

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

1366

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

1368 (unless the headers are omitted).

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

1370 - The rows must be separated by blank lines.

1371

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

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

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

1375output, try widening it in the markdown source.

1376

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

1378

1379 ----------- ------- --------------- -------------------------

1380 First row 12.0 Example of a row that

1381 spans multiple lines.

1382

1383 Second row 5.0 Here's another one. Note

1384 the blank line between

1385 rows.

1386 -------------------------------------------------------------

1387

1388 : Here's a multiline table without headers.

1389

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

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

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

1393

1394**Grid tables** look like this:

1395

1396 : Sample grid table.

1397

1398 +---------------+---------------+--------------------+

1399 | Fruit | Price | Advantages |

1400 +===============+===============+====================+

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

1402 | | | - bright color |

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

1404 | Oranges | $2.10 | - cures scurvy |

1405 | | | - tasty |

1406 +---------------+---------------+--------------------+

1407

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

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

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

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

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

1413

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

1415

1416

1417Title block

1418-----------

1419

1420*Pandoc extension*.

1421

1422If the file begins with a title block

1423

1424 % title

1425 % author(s) (separated by semicolons)

1426 % date

1427

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

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

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

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

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

1433

1434 %

1435 % Author

1436

1437 % My title

1438 %

1439 % June 15, 2006

1440

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

1442begin with leading space, thus:

1443

1444 % My title

1445 on multiple lines

1446

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

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

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

1450

1451 % Author One

1452 Author Two

1453

1454 % Author One; Author Two

1455

1456 % Author One;

1457 Author Two

1458

1459The date must fit on one line.

1460

1461All three metadata fields may contain standard inline formatting

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

1463

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

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

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

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

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

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

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

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

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

1473be used by itself as the HTML title.

1474

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

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

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

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

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

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

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

1482text. Thus,

1483

1484 % PANDOC(1)

1485

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

1487

1488 % PANDOC(1) Pandoc User Manuals

1489

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

1491

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

1493

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

1495

1496

1497Backslash escapes

1498-----------------

1499

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

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

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

1503

1504 *\*hello\**

1505

1506one will get

1507

1508 <em>*hello*</em>

1509

1510instead of

1511

1512 <strong>hello</strong>

1513

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

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

1516

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

1518

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

1520markdown rule will be used.)

1521

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

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

1524`\ `.

1525

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

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

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

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

1530two trailing spaces on a line.

1531

1532Backslash escapes do not work in verbatim contexts.

1533

1534Smart punctuation

1535-----------------

1536

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

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

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

1540certain abbreviations, such as "Mr."

1541

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

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

1544

1545Inline formatting

1546-----------------

1547

1548### Emphasis ###

1549

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

1551

1552 This text is _emphasized with underscores_, and this

1553 is *emphasized with asterisks*.

1554

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

1556

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

1558

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

1560will not trigger emphasis:

1561

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

1563

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

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

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

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

1568

1569 feas*ible*, not feas*able*.

1570

1571

1572### Strikeout ###

1573

1574*Pandoc extension*.

1575

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

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

1578

1579 This ~~is deleted text.~~

1580

1581

1582### Superscripts and subscripts ###

1583

1584*Pandoc extension*.

1585

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

1587characters; subscripts may be written by surrounding the subscripted

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

1589

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

1591

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

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

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

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

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

1597

1598

1599### Verbatim ###

1600

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

1602

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

1604

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

1606

1607 Here is a literal backtick `` ` ``.

1608

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

1610backticks will be ignored.)

1611

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

1613of consecutive backticks (optionally followed by a space)

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

1615preceded by a space).

1616

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

1618work in verbatim contexts:

1619

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

1621

1622

1623Math

1624----

1625

1626*Pandoc extension*.

1627

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

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

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

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

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

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

1634

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

1636depends on the output format:

1637

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

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

1640

1641reStructuredText

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

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

1644

1645AsciiDoc

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

1647

1648Texinfo

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

1650

1651groff man

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

1653

1654MediaWiki

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

1656

1657Textile

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

1659

1660RTF, OpenDocument, ODT

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

1662 and will otherwise appear verbatim.

1663

1664Docbook

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

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

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

1668

1669Docx

1670 ~ It will be rendered using OMML math markup.

1671

1672HTML, Slidy, DZSlides, S5, EPUB

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

1674 command-line options selected:

1675

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

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

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

1679 styled differently from the surrounding text if needed.

1680

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

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

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

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

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

1686 verbatim between $ characters.)

1687

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

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

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

1691 it.

1692

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

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

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

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

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

1698

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

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

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

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

1703 procedure is:

1704

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

1706 gladtex -d myfile-images myfile.htex

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

1708

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

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

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

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

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

1714

1715

1716Raw HTML

1717--------

1718

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

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

1721literally).

1722

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

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

1725

1726*Pandoc extension*.

1727

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

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

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

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

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

1733

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

1735pandoc interprets material between HTML block tags as markdown.

1736Thus, for example, Pandoc will turn

1737

1738 <table>

1739 <tr>

1740 <td>*one*</td>

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

1742 </tr>

1743 </table>

1744

1745into

1746

1747 <table>

1748 <tr>

1749 <td><em>one</em></td>

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

1751 </tr>

1752 </table>

1753

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

1755

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

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

1758

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

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

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

1762from being interpreted as markdown.

1763

1764Raw TeX

1765-------

1766

1767*Pandoc extension*.

1768

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

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

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

1772LaTeX to include BibTeX citations:

1773

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

1775

1776Note that in LaTeX environments, like

1777

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

1779 Age & Frequency \\ \hline

1780 18--25 & 15 \\

1781 26--35 & 33 \\

1782 36--45 & 22 \\ \hline

1783 \end{tabular}

1784

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

1786LaTeX, not as markdown.

1787

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

1789and ConTeXt.

1790

1791### Macros ###

1792

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

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

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

1796not just LaTeX:

1797

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

1799

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

1801

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

1803unchanged to the output.

1804

1805

1806Links

1807-----

1808

1809Markdown allows links to be specified in several ways.

1810

1811### Automatic links ###

1812

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

1814will become a link:

1815

1816 <http://google.com>

1817 <sam@green.eggs.ham>

1818

1819

1820### Inline links ###

1821

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

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

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

1825

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

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

1828

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

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

1831

1832

1833### Reference links ###

1834

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

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

1837before or after the link).

1838

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

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

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

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

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

1844parentheses.

1845

1846Here are some examples:

1847

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

1849 [my label 2]: /foo

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

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

1852

1853The URL may optionally be surrounded by angle brackets:

1854

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

1856

1857The title may go on the next line:

1858

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

1860 "The free software foundation"

1861

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

1863

1864 Here is [my link][FOO]

1865

1866 [Foo]: /bar/baz

1867

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

1869empty, or omitted entirely:

1870

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

1872

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

1874

1875

1876Images

1877------

1878

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

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

1881

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

1883

1884 ![movie reel]

1885

1886 [movie reel]: movie.gif

1887

1888### Pictures with captions ###

1889

1890*Pandoc extension*.

1891

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

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

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

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

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

1897

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

1899

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

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

1902 itself, with no caption.

1903

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

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

1906nonbreaking space after the image:

1907

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

1909

1910

1911Footnotes

1912---------

1913

1914*Pandoc extension*.

1915

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

1917

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

1919

1920 [^1]: Here is the footnote.

1921

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

1923

1924 Subsequent paragraphs are indented to show that they

1925 belong to the previous footnote.

1926

1927 { some.code }

1928

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

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

1931 multi-paragraph list items.

1932

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

1934 isn't indented.

1935

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

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

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

1939will be numbered sequentially.

1940

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

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

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

1944

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

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

1947

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

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

1950 note.]

1951

1952Inline and regular footnotes may be mixed freely.

1953

1954

1955Citations

1956---------

1957

1958*Pandoc extension*.

1959

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

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

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

1963

1964 Format File extension

1965 ------------ --------------

1966 MODS .mods

1967 BibTeX/BibLaTeX .bib

1968 RIS .ris

1969 EndNote .enl

1970 EndNote XML .xml

1971 ISI .wos

1972 MEDLINE .medline

1973 Copac .copac

1974 JSON citeproc .json

1975

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

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

1978bibliographies).

1979

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

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

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

1983creating and modifying CSL styles can be found at

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

1985A repository of CSL styles can be found at

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

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

1988

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

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

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

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

1993

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

1995

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

1997

1998 Blah blah [@smith04; @doe99].

1999

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

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

2002author is already mentioned in the text:

2003

2004 Smith says blah [-@smith04].

2005

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

2007

2008 @smith04 says blah.

2009

2010 @smith04 [p. 33] says blah.

2011

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

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

2014document with an appropriate header:

2015

2016 last paragraph...

2017

2018 # References

2019

2020The bibliography will be inserted after this header.

2021

2022

2023Producing slide shows with Pandoc

2024=================================

2025

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

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

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

2029show using LaTeX [beamer].

2030

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

2032

2033 % Habits

2034 % John Doe

2035 % March 22, 2005

2036

2037 # In the morning

2038

2039 ## Getting up

2040

2041 - Turn off alarm

2042 - Get out of bed

2043

2044 ## Breakfast

2045

2046 - Eat eggs

2047 - Drink coffee

2048

2049 # In the evening

2050

2051 ## Dinner

2052

2053 - Eat spaghetti

2054 - Drink wine

2055

2056 ------------------

2057

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

2059

2060 ## Going to sleep

2061

2062 - Get in bed

2063 - Count sheep

2064

2065To produce the slide show, simply type

2066

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

2068

2069for S5,

2070

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

2072

2073for Slidy,

2074

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

2076

2077for DZSlides, or

2078

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

2080

2081for beamer.

2082

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

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

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

2086

2087Structuring the slide show

2088--------------------------

2089

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

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

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

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

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

2095the `--slide-level` option.

2096

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

2098rules:

2099

2100 * A horizontal rule always starts a new slide.

2101

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

2103

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

2105 headers *within* a slide.

2106

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

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

2109 and help to break the slide show into sections.

2110

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

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

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

2114

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

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

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

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

2119sections, as in the example above.

2120

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

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

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

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

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

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

2127

2128Incremental lists

2129-----------------

2130

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

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

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

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

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

2136

2137 > - Eat spaghetti

2138 > - Drink wine

2139

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

2141a single document.

2142

2143Styling the slides

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

2145

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

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

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

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

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

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

2152

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

2154be modified there.

2155

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

2157using the `-V` option:

2158

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

2160

2161Literate Haskell support

2162========================

2163

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

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

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

2167

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

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

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

2171

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

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

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

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

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

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

2178

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

2180 as Haskell code.

2181

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

2183 be rendered using bird tracks.

2184

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

2186 Haskell code.

2187

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

2189 inside `code` environments.

2190

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

2192 with class `literatehaskell` and bird tracks.

2193

2194Examples:

2195

2196 pandoc -f markdown+lhs -t html

2197

2198reads literate Haskell source formatted with markdown conventions and writes

2199ordinary HTML (without bird tracks).

2200

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

2202

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

2204and pasted as literate Haskell source.

2205

2206Authors

2207=======

2208

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

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

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

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

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

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

2216Christopher Sawicki, Kelsey Hightower, Masayoshi Takahashi, Antoine

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

2218

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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