README · typeable/pandoc

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

762

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

764

765Reference links

766---------------

767

768Pandoc allows implicit reference links with just a single set of

769brackets. So, the following links are equivalent:

770

771 1. Here's my [link]

772 2. Here's my [link][]

773

774 [link]: linky.com

775

776(Note: Pandoc works this way even if `--strict` is specified, because

777`Markdown.pl` 1.0.2b7 allows single-bracket links.)

778

779Footnotes

780---------

781

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

783

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

785

786 [^1]: Here is the footnote.

787

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

789

790 Subsequent paragraphs are indented to show that they

791 belong to the previous footnote.

792

793 { some.code }

794

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

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

797 multi-paragraph list items.

798

799 This paragraph won't be part of the note, because it isn't indented.

800

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

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

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

804will be numbered sequentially.

805

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

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

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

809

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

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

812

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

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

815 note.]

816

817Inline and regular footnotes may be mixed freely.

818

819Tables

820------

821

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

823a fixed-width font, such as Courier.

824

825**Simple tables** look like this:

826

827 Right Left Center Default

828 ------- ------ ---------- -------

829 12 12 12 12

830 123 123 123 123

831 1 1 1 1

832

833 Table: Demonstration of simple table syntax.

834

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

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

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

838

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

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

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

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

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

844 the column is centered.

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

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

847

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

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

850

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

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

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

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

855before or after the table.

856

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

858to end the table. For example:

859

860 ------- ------ ---------- -------

861 12 12 12 12

862 123 123 123 123

863 1 1 1 1

864 ------- ------ ---------- -------

865

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

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

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

869

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

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

872not supported). Here is an example:

873

874 -------------------------------------------------------------

875 Centered Default Right Left

876 Header Aligned Aligned Aligned

877 ----------- ------- --------------- -------------------------

878 First row 12.0 Example of a row that

879 spans multiple lines.

880

881 Second row 5.0 Here's another one. Note

882 the blank line between

883 rows.

884 -------------------------------------------------------------

885

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

887 multiple lines.

888

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

890

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

892 (unless the headers are omitted).

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

894 - The rows must be separated by blank lines.

895

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

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

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

899output, try widening it in the markdown source.

900

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

902

903 ----------- ------- --------------- -------------------------

904 First row 12.0 Example of a row that

905 spans multiple lines.

906

907 Second row 5.0 Here's another one. Note

908 the blank line between

909 rows.

910 -------------------------------------------------------------

911

912 : Here's a multiline table without headers.

913

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

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

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

917

918**Grid tables** look like this:

919

920 : Sample grid table.

921

922 +---------------+---------------+--------------------+

923 | Fruit | Price | Advantages |

924 +===============+===============+====================+

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

926 | | | - bright color |

927 +---------------+---------------+--------------------+

928 | Oranges | $2.10 | - cures scurvy |

929 | | | - tasty |

930 +---------------+---------------+--------------------+

931

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

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

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

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

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

937

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

939

940Delimited Code blocks

941---------------------

942

943In addition to standard indented code blocks, Pandoc supports

944*delimited* code blocks. These begin with a row of three or more

945tildes (`~`) and end with a row of tildes that must be at least

946as long as the starting row. Everything between the tilde-lines

947is treated as code. No indentation is necessary:

948

949 ~~~~~~~

950 {code here}

951 ~~~~~~~

952

953Like regular code blocks, delimited code blocks must be separated

954from surrounding text by blank lines.

955

956If the code itself contains a row of tildes, just use a longer

957row of tildes at the start and end:

958

959 ~~~~~~~~~~~~~~~~

960 ~~~~~~~~~~

961 code including tildes

962 ~~~~~~~~~~

963 ~~~~~~~~~~~~~~~~

964

965Optionally, you may specify the language of the code block using

966this syntax:

967

968 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}

969 qsort [] = []

970 qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++

971 qsort (filter (>= x) xs)

972 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

973

974Some output formats can use this information to do syntax highlighting.

975Currently, the only output format that uses this information is HTML.

976

977If pandoc has been compiled with syntax highlighting support, then the

978code block above will appear highlighted, with numbered lines. (To see

979which languages are supported, do `pandoc --version`.)

980

981If pandoc has not been compiled with syntax highlighting support, the

982code block above will appear as follows:

983

984 <pre class="haskell">

985 <code>

986 ...

987 </code>

988 </pre>

989

990Images with captions

991--------------------

992

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

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

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

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

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

998

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

1000

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

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

1003 itself, with no caption.

1004

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

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

1007nonbreaking space after the image:

1008

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

1010

1011Title blocks

1012------------

1013

1014If the file begins with a title block

1015

1016 % title

1017 % author(s) (separated by semicolons)

1018 % date

1019

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

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

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

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

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

1025

1026 %

1027 % Author

1028

1029 % My title

1030 %

1031 % June 15, 2006

1032

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

1034begin with leading space, thus:

1035

1036 % My title

1037 on multiple lines

1038

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

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

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

1042

1043 % Author One

1044 Author Two

1045

1046 % Author One; Author Two

1047

1048 % Author One;

1049 Author Two

1050

1051The date must fit on one line.

1052

1053All three metadata fields may contain standard inline formatting

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

1055

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

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

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

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

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

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

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

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

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

1065be used by itself as the HTML title.

1066

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

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

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

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

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

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

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

1074text. Thus,

1075

1076 % PANDOC(1)

1077

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

1079

1080 % PANDOC(1) Pandoc User Manuals

1081

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

1083

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

1085

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

1087

1088Markdown in HTML blocks

1089-----------------------

1090

1091While standard markdown leaves HTML blocks exactly as they are, Pandoc

1092treats text between HTML tags as markdown. Thus, for example, Pandoc

1093will turn

1094

1095 <table>

1096 <tr>

1097 <td>*one*</td>

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

1099 </tr>

1100 </table>

1101

1102into

1103

1104 <table>

1105 <tr>

1106 <td><em>one</em></td>

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

1108 </tr>

1109 </table>

1110

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

1112

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

1114`</script>` tags is not interpreted as markdown.

1115

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

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

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

1119from being interpreted as markdown.

1120

1121Header identifiers in HTML

1122--------------------------

1123

1124Each header element in pandoc's HTML output is given a unique

1125identifier. This identifier is based on the text of the header. To

1126derive the identifier from the header text,

1127

1128 - Remove all formatting, links, etc.

1129 - Remove all punctuation, except underscores, hyphens, and periods.

1130 - Replace all spaces and newlines with hyphens.

1131 - Convert all alphabetic characters to lowercase.

1132 - Remove everything up to the first letter (identifiers may

1133 not begin with a number or punctuation mark).

1134 - If nothing is left after this, use the identifier `section`.

1135

1136Thus, for example,

1137

1138 Header Identifier

1139 ------------------------------------- ---------------------------

1140 Header identifiers in HTML `header-identifiers-in-html`

1141 *Dogs*?--in *my* house? `dogs--in-my-house`

1142 [HTML], [S5], or [RTF]? `html-s5-or-rtf`

1143 3. Applications `applications`

1144 33 `section`

1145

1146These rules should, in most cases, allow one to determine the identifier

1147from the header text. The exception is when several headers have the

1148same text; in this case, the first will get an identifier as described

1149above; the second will get the same identifier with `-1` appended; the

1150third with `-2`; and so on.

1151

1152These identifiers are used to provide link targets in the table of

1153contents generated by the `--toc|--table-of-contents` option. They

1154also make it easy to provide links from one section of a document to

1155another. A link to this section, for example, might look like this:

1156

1157 See the section on [header identifiers](#header-identifiers-in-html).

1158

1159Note, however, that this method of providing links to sections works

1160only in HTML.

1161

1162If the `--section-divs` option is specified, then each section will

1163be wrapped in a `div`, and the identifier will be attached to the

1164enclosing `<div>` tag rather than the header itself. This allows entire

1165sections to be manipulated using javascript or treated differently in

1166CSS.

1167

1168Blank lines before headers and blockquotes

1169------------------------------------------

1170

1171Standard markdown syntax does not require a blank line before a header

1172or blockquote. Pandoc does require this (except, of course, at the

1173beginning of the document). The reason for the requirement is that

1174it is all too easy for a `>` or `#` to end up at the beginning of a

1175line by accident (perhaps through line wrapping). Consider, for

1176example:

1177

1178 I like several of their flavors of ice cream: #22, for example, and

1179 #5.

1180

1181Math

1182----

1183

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

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

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

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

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

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

1190

1191TeX math will be printed in all output formats. In Markdown,

1192reStructuredText, LaTeX, and ConTeXt output, it will appear verbatim

1193between $ characters.

1194

1195In reStructuredText output, it will be rendered using an interpreted

1196text role `:math:`, as described

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

1198

1199In Texinfo output, it will be rendered inside a `@math` command.

1200

1201In groff man output, it will be rendered verbatim without $'s.

1202

1203In MediaWiki output, it will be rendered inside `<math>` tags.

1204

1205In Textile output, it will be rendered inside `<span class="math">` tags.

1206

1207In RTF, Docbook, and OpenDocument output, it will be rendered, as far as

1208possible, using unicode characters, and will otherwise appear verbatim.

1209Unknown commands and symbols, and commands that cannot be dealt with

1210this way (like `\frac`), will be rendered verbatim. So the results may

1211be a mix of raw TeX code and properly rendered unicode math.

1212

1213In HTML, Slidy, and S5 output, the way math is rendered will depend on the

1214command-line options selected:

1215

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

1217 characters, as with RTF, Docbook, and OpenDocument output. Formulas

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

1219 styled differently from the surrounding text if needed.

1220

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

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

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

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

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

1226 verbatim between $ characters.)

1227

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

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

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

1231 it.

1232

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

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

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

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

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

1238

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

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

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

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

1243 procedure is:

1244

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

1246 gladtex -d myfile-images myfile.htex

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

1248

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

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

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

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

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

1254

1255LaTeX Macros

1256------------

1257

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

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

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

1261not just LaTeX:

1262

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

1264

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

1266

1267Inline TeX

1268----------

1269

1270Inline TeX commands will be preserved and passed unchanged to the

1271LaTeX and ConTeXt writers. Thus, for example, you can use LaTeX to

1272include BibTeX citations:

1273

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

1275

1276Note that in LaTeX environments, like

1277

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

1279 Age & Frequency \\ \hline

1280 18--25 & 15 \\

1281 26--35 & 33 \\

1282 36--45 & 22 \\ \hline

1283 \end{tabular}

1284

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

1286LaTeX, not as markdown.

1287

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

1289and ConTeXt.

1290

1291Producing HTML slide shows with Pandoc

1292======================================

1293

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

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

1296using [S5] or [Slidy].

1297

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

1299

1300 % Eating Habits

1301 % John Doe

1302 % March 22, 2005

1303

1304 # In the morning

1305

1306 - Eat eggs

1307 - Drink coffee

1308

1309 # In the evening

1310

1311 - Eat spaghetti

1312 - Drink wine

1313

1314 --------------------------

1315

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

1317

1318To produce the slide show, simply type

1319

1320 pandoc -w s5 -s eating.txt > eating.html

1321

1322for S5, or

1323

1324 pandoc -w slidy -s eating.txt > eating.html

1325

1326for Slidy.

1327

1328A title page is constructed automatically from the document's title

1329block. Each level-one header and horizontal rule begins a new slide.

1330

1331The file produced by pandoc with the `-s/--standalone` option embeds a

1332link to javascripts and CSS files, which are assumed to be available at

1333the relative path `ui/default` (for S5) or at the Slidy website at

1334`w3.org` (for Slidy). If the `--offline` option is specified, the

1335scripts and CSS will be included directly in the generated file, so that

1336it may be used offline.

1337

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

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

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

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

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

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

1344

1345Incremental lists

1346-----------------

1347

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

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

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

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

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

1353

1354 > - Eat spaghetti

1355 > - Drink wine

1356

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

1358a single document.

1359

1360Literate Haskell support

1361========================

1362

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

1364`rst`, or `latex` for input or output; `html` for output only), pandoc

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

1366

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

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

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

1370

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

1372 rendered using bird tracks, and block quotations will be

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

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

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

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

1377

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

1379 as Haskell code.

1380

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

1382 be rendered using bird tracks.

1383

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

1385 Haskell code.

1386

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

1388 inside `code` environments.

1389

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

1391 with class `literatehaskell` and bird tracks.

1392

1393Examples:

1394

1395 pandoc -f markdown+lhs -t html

1396

1397reads literate Haskell source formatted with markdown conventions and writes

1398ordinary HTML (without bird tracks).

1399

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

1401

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

1403and pasted as literate Haskell source.

1404

1405

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1424