README · typeable/pandoc

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

767

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

769

770Reference links

771---------------

772

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

774brackets. So, the following links are equivalent:

775

776 1. Here's my [link]

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

778

779 [link]: linky.com

780

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

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

783

784Footnotes

785---------

786

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

788

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

790

791 [^1]: Here is the footnote.

792

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

794

795 Subsequent paragraphs are indented to show that they

796 belong to the previous footnote.

797

798 { some.code }

799

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

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

802 multi-paragraph list items.

803

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

805

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

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

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

809will be numbered sequentially.

810

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

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

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

814

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

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

817

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

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

820 note.]

821

822Inline and regular footnotes may be mixed freely.

823

824Tables

825------

826

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

828a fixed-width font, such as Courier.

829

830**Simple tables** look like this:

831

832 Right Left Center Default

833 ------- ------ ---------- -------

834 12 12 12 12

835 123 123 123 123

836 1 1 1 1

837

838 Table: Demonstration of simple table syntax.

839

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

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

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

843

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

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

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

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

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

849 the column is centered.

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

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

852

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

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

855

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

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

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

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

860before or after the table.

861

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

863to end the table. For example:

864

865 ------- ------ ---------- -------

866 12 12 12 12

867 123 123 123 123

868 1 1 1 1

869 ------- ------ ---------- -------

870

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

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

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

874

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

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

877not supported). Here is an example:

878

879 -------------------------------------------------------------

880 Centered Default Right Left

881 Header Aligned Aligned Aligned

882 ----------- ------- --------------- -------------------------

883 First row 12.0 Example of a row that

884 spans multiple lines.

885

886 Second row 5.0 Here's another one. Note

887 the blank line between

888 rows.

889 -------------------------------------------------------------

890

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

892 multiple lines.

893

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

895

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

897 (unless the headers are omitted).

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

899 - The rows must be separated by blank lines.

900

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

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

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

904output, try widening it in the markdown source.

905

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

907

908 ----------- ------- --------------- -------------------------

909 First row 12.0 Example of a row that

910 spans multiple lines.

911

912 Second row 5.0 Here's another one. Note

913 the blank line between

914 rows.

915 -------------------------------------------------------------

916

917 : Here's a multiline table without headers.

918

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

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

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

922

923**Grid tables** look like this:

924

925 : Sample grid table.

926

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

928 | Fruit | Price | Advantages |

929 +===============+===============+====================+

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

931 | | | - bright color |

932 +---------------+---------------+--------------------+

933 | Oranges | $2.10 | - cures scurvy |

934 | | | - tasty |

935 +---------------+---------------+--------------------+

936

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

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

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

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

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

942

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

944

945Delimited Code blocks

946---------------------

947

948In addition to standard indented code blocks, Pandoc supports

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

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

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

952is treated as code. No indentation is necessary:

953

954 ~~~~~~~

955 {code here}

956 ~~~~~~~

957

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

959from surrounding text by blank lines.

960

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

962row of tildes at the start and end:

963

964 ~~~~~~~~~~~~~~~~

965 ~~~~~~~~~~

966 code including tildes

967 ~~~~~~~~~~

968 ~~~~~~~~~~~~~~~~

969

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

971this syntax:

972

973 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}

974 qsort [] = []

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

976 qsort (filter (>= x) xs)

977 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

978

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

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

981

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

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

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

985

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

987code block above will appear as follows:

988

989 <pre class="haskell">

990 <code>

991 ...

992 </code>

993 </pre>

994

995Images with captions

996--------------------

997

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

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

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

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

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

1003

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

1005

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

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

1008 itself, with no caption.

1009

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

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

1012nonbreaking space after the image:

1013

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

1015

1016Title blocks

1017------------

1018

1019If the file begins with a title block

1020

1021 % title

1022 % author(s) (separated by semicolons)

1023 % date

1024

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

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

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

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

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

1030

1031 %

1032 % Author

1033

1034 % My title

1035 %

1036 % June 15, 2006

1037

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

1039begin with leading space, thus:

1040

1041 % My title

1042 on multiple lines

1043

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

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

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

1047

1048 % Author One

1049 Author Two

1050

1051 % Author One; Author Two

1052

1053 % Author One;

1054 Author Two

1055

1056The date must fit on one line.

1057

1058All three metadata fields may contain standard inline formatting

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

1060

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

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

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

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

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

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

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

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

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

1070be used by itself as the HTML title.

1071

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

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

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

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

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

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

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

1079text. Thus,

1080

1081 % PANDOC(1)

1082

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

1084

1085 % PANDOC(1) Pandoc User Manuals

1086

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

1088

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

1090

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

1092

1093Markdown in HTML blocks

1094-----------------------

1095

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

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

1098will turn

1099

1100 <table>

1101 <tr>

1102 <td>*one*</td>

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

1104 </tr>

1105 </table>

1106

1107into

1108

1109 <table>

1110 <tr>

1111 <td><em>one</em></td>

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

1113 </tr>

1114 </table>

1115

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

1117

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

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

1120

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

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

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

1124from being interpreted as markdown.

1125

1126Header identifiers in HTML

1127--------------------------

1128

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

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

1131derive the identifier from the header text,

1132

1133 - Remove all formatting, links, etc.

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

1135 - Replace all spaces and newlines with hyphens.

1136 - Convert all alphabetic characters to lowercase.

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

1138 not begin with a number or punctuation mark).

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

1140

1141Thus, for example,

1142

1143 Header Identifier

1144 ------------------------------------- ---------------------------

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

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

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

1148 3. Applications `applications`

1149 33 `section`

1150

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

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

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

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

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

1156

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

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

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

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

1161

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

1163

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

1165only in HTML.

1166

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

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

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

1170sections to be manipulated using javascript or treated differently in

1171CSS.

1172

1173Blank lines before headers and blockquotes

1174------------------------------------------

1175

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

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

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

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

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

1181example:

1182

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

1184 #5.

1185

1186Math

1187----

1188

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

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

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

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

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

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

1195

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

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

1198between $ characters.

1199

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

1201text role `:math:`, as described

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

1203

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

1205

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

1207

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

1209

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

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

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

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

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

1215

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

1217command-line options selected:

1218

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

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

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

1222 styled differently from the surrounding text if needed.

1223

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

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

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

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

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

1229 verbatim between $ characters.)

1230

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

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

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

1234 it.

1235

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

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

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

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

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

1241

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

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

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

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

1246 procedure is:

1247

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

1249 gladtex -d myfile-images myfile.htex

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

1251

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

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

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

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

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

1257

1258LaTeX Macros

1259------------

1260

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

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

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

1264not just LaTeX:

1265

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

1267

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

1269

1270Inline TeX

1271----------

1272

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

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

1275include BibTeX citations:

1276

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

1278

1279Note that in LaTeX environments, like

1280

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

1282 Age & Frequency \\ \hline

1283 18--25 & 15 \\

1284 26--35 & 33 \\

1285 36--45 & 22 \\ \hline

1286 \end{tabular}

1287

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

1289LaTeX, not as markdown.

1290

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

1292and ConTeXt.

1293

1294Producing HTML slide shows with Pandoc

1295======================================

1296

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

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

1299using [S5] or [Slidy].

1300

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

1302

1303 % Eating Habits

1304 % John Doe

1305 % March 22, 2005

1306

1307 # In the morning

1308

1309 - Eat eggs

1310 - Drink coffee

1311

1312 # In the evening

1313

1314 - Eat spaghetti

1315 - Drink wine

1316

1317 --------------------------

1318

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

1320

1321To produce the slide show, simply type

1322

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

1324

1325for S5, or

1326

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

1328

1329for Slidy.

1330

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

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

1333

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

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

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

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

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

1339it may be used offline.

1340

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

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

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

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

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

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

1347

1348Incremental lists

1349-----------------

1350

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

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

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

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

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

1356

1357 > - Eat spaghetti

1358 > - Drink wine

1359

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

1361a single document.

1362

1363Literate Haskell support

1364========================

1365

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

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

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

1369

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

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

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

1373

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

1375 rendered using bird tracks, and block quotations will be

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

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

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

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

1380

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

1382 as Haskell code.

1383

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

1385 be rendered using bird tracks.

1386

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

1388 Haskell code.

1389

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

1391 inside `code` environments.

1392

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

1394 with class `literatehaskell` and bird tracks.

1395

1396Examples:

1397

1398 pandoc -f markdown+lhs -t html

1399

1400reads literate Haskell source formatted with markdown conventions and writes

1401ordinary HTML (without bird tracks).

1402

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

1404

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

1406and pasted as literate Haskell source.

1407

1408

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1426