README · typeable/pandoc

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

714

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

716

717Reference links

718---------------

719

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

721brackets. So, the following links are equivalent:

722

723 1. Here's my [link]

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

725

726 [link]: linky.com

727

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

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

730

731Footnotes

732---------

733

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

735

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

737

738 [^1]: Here is the footnote.

739

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

741

742 Subsequent paragraphs are indented to show that they

743 belong to the previous footnote.

744

745 { some.code }

746

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

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

749 multi-paragraph list items.

750

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

752

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

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

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

756will be numbered sequentially.

757

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

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

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

761

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

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

764

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

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

767 note.]

768

769Inline and regular footnotes may be mixed freely.

770

771Tables

772------

773

774Two kinds of tables may be used. Both kinds presuppose the use of

775a fixed-width font, such as Courier.

776

777Simple tables look like this:

778

779 Right Left Center Default

780 ------- ------ ---------- -------

781 12 12 12 12

782 123 123 123 123

783 1 1 1 1

784

785 Table: Demonstration of simple table syntax.

786

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

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

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

790

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

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

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

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

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

796 the column is centered.

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

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

799

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

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

802

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

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

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

806`Table:`, which will be stripped off.

807

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

809to end the table. For example:

810

811 ------- ------ ---------- -------

812 12 12 12 12

813 123 123 123 123

814 1 1 1 1

815 ------- ------ ---------- -------

816

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

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

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

820

821Multiline tables allow headers and table rows to span multiple lines

822of text. Here is an example:

823

824 -------------------------------------------------------------

825 Centered Default Right Left

826 Header Aligned Aligned Aligned

827 ----------- ------- --------------- -------------------------

828 First row 12.0 Example of a row that

829 spans multiple lines.

830

831 Second row 5.0 Here's another one. Note

832 the blank line between

833 rows.

834 -------------------------------------------------------------

835

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

837 multiple lines.

838

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

840

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

842 (unless the headers are omitted).

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

844 - The rows must be separated by blank lines.

845

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

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

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

849output, try widening it in the markdown source.

850

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

852

853 ----------- ------- --------------- -------------------------

854 First row 12.0 Example of a row that

855 spans multiple lines.

856

857 Second row 5.0 Here's another one. Note

858 the blank line between

859 rows.

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

861

862 Table: Here's a multiline table without headers.

863

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

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

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

867

868Delimited Code blocks

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

870

871In addition to standard indented code blocks, Pandoc supports

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

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

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

875is treated as code. No indentation is necessary:

876

877 ~~~~~~~

878 {code here}

879 ~~~~~~~

880

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

882from surrounding text by blank lines.

883

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

885row of tildes at the start and end:

886

887 ~~~~~~~~~~~~~~~~

888 ~~~~~~~~~~

889 code including tildes

890 ~~~~~~~~~~

891 ~~~~~~~~~~~~~~~~

892

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

894this syntax:

895

896 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}

897 qsort [] = []

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

899 qsort (filter (>= x) xs)

900 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

901

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

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

904

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

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

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

908

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

910code block above will appear as follows:

911

912 <pre class="haskell">

913 <code>

914 ...

915 </code>

916 </pre>

917

918Images with captions

919--------------------

920

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

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

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

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

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

926

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

928

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

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

931 itself, with no caption.

932

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

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

935nonbreaking space after the image:

936

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

938

939Title blocks

940------------

941

942If the file begins with a title block

943

944 % title

945 % author(s) (separated by semicolons)

946 % date

947

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

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

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

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

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

953

954 %

955 % Author

956

957 % My title

958 %

959 % June 15, 2006

960

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

962begin with leading space, thus:

963

964 % My title

965 on multiple lines

966

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

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

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

970

971 % Author One

972 Author Two

973

974 % Author One; Author Two

975

976 % Author One;

977 Author Two

978

979The date must fit on one line.

980

981All three metadata fields may contain standard inline formatting

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

983

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

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

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

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

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

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

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

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

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

993be used by itself as the HTML title.

994

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

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

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

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

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

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

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

1002text. Thus,

1003

1004 % PANDOC(1)

1005

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

1007

1008 % PANDOC(1) Pandoc User Manuals

1009

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

1011

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

1013

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

1015

1016Markdown in HTML blocks

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

1018

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

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

1021will turn

1022

1023 <table>

1024 <tr>

1025 <td>*one*</td>

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

1027 </tr>

1028 </table>

1029

1030into

1031

1032 <table>

1033 <tr>

1034 <td><em>one</em></td>

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

1036 </tr>

1037 </table>

1038

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

1040

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

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

1043

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

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

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

1047from being interpreted as markdown.

1048

1049Header identifiers in HTML

1050--------------------------

1051

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

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

1054derive the identifier from the header text,

1055

1056 - Remove all formatting, links, etc.

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

1058 - Replace all spaces and newlines with hyphens.

1059 - Convert all alphabetic characters to lowercase.

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

1061 not begin with a number or punctuation mark).

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

1063

1064Thus, for example,

1065

1066 Header Identifier

1067 ------------------------------------- ---------------------------

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

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

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

1071 3. Applications `applications`

1072 33 `section`

1073

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

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

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

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

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

1079

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

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

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

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

1084

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

1086

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

1088only in HTML.

1089

1090Blank lines before headers and blockquotes

1091------------------------------------------

1092

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

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

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

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

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

1098example:

1099

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

1101 #5.

1102

1103Math

1104----

1105

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

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

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

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

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

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

1112

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

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

1115between $ characters.

1116

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

1118text role `:math:`, as described

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

1120

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

1122

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

1124

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

1126

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

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

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

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

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

1132

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

1134command-line options selected:

1135

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

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

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

1139 styled differently from the surrounding text if needed.

1140

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

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

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

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

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

1146 verbatim between $ characters.)

1147

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

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

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

1151 it.

1152

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

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

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

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

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

1158

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

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

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

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

1163 procedure is:

1164

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

1166 gladtex -d myfile-images myfile.htex

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

1168

1169Inline TeX

1170----------

1171

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

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

1174include BibTeX citations:

1175

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

1177

1178Note that in LaTeX environments, like

1179

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

1181 Age & Frequency \\ \hline

1182 18--25 & 15 \\

1183 26--35 & 33 \\

1184 36--45 & 22 \\ \hline

1185 \end{tabular}

1186

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

1188LaTeX, not as markdown.

1189

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

1191and ConTeXt.

1192

1193Producing S5 with Pandoc

1194========================

1195

1196Producing an [S5] web-based slide show with Pandoc is easy. A title

1197page is constructed automatically from the document's title block (see

1198above). Each section (with a level-one header) produces a single slide.

1199(Note that if the section is too big, the slide will not fit on the page;

1200S5 is not smart enough to produce multiple pages.)

1201

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

1203

1204 % Eating Habits

1205 % John Doe

1206 % March 22, 2005

1207

1208 # In the morning

1209

1210 - Eat eggs

1211 - Drink coffee

1212

1213 # In the evening

1214

1215 - Eat spaghetti

1216 - Drink wine

1217

1218To produce the slide show, simply type

1219

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

1221

1222and open up `eating.html` in a browser.

1223

1224Note that by default, the S5 writer produces lists that display

1225"all at once." If you want your lists to display incrementally

1226(one item at a time), use the `-i` option. If you want a

1227particular list to depart from the default (that is, to display

1228incrementally without the `-i` option and all at once with the

1229`-i` option), put it in a block quote:

1230

1231 > - Eat spaghetti

1232 > - Drink wine

1233

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

1235a single document.

1236

1237Note: the S5 file produced by pandoc with the `-s/--standalone` option

1238embeds the javascript and CSS required to show the slides. Thus it

1239does not depend on any additional files: you can send the HTML file to

1240others, and they will be able to view the slide show just by opening

1241it. However, if you intend to produce several S5 slide shows, and you

1242are displaying them on your own website, it is better to keep the S5

1243javascript and CSS files separate from the slide shows themselves, so

1244that they may be cached. The best approach in this case is to use pandoc

1245without the `-s` option to produce the body of the S5 document, which

1246can then be inserted into an HTML template that links to the javascript

1247and CSS files required by S5. (See the instructions on the S5 website.)

1248Alternatively, you may use `-s` together with the `--template`

1249option to specify a custom template.

1250

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

1252in `$DATADIR/s5/default`, where `$DATADIR` is the user data directory

1253(see `--data-dir`, above). The originals may be found in pandoc's system

1254data directory (generally `$CABALDIR/pandoc-VERSION/s5/default`). Pandoc

1255will look there for any files it does not find in the user data

1256directory.

1257

1258Literate Haskell support

1259========================

1260

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

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

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

1264

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

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

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

1268

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

1270 rendered using bird tracks, and block quotations will be

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

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

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

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

1275

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

1277 as Haskell code.

1278

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

1280 be rendered using bird tracks.

1281

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

1283 Haskell code.

1284

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

1286 inside `code` environments.

1287

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

1289 with class `literatehaskell` and bird tracks.

1290

1291Examples:

1292

1293 pandoc -f markdown+lhs -t html

1294

1295reads literate Haskell source formatted with markdown conventions and writes

1296ordinary HTML (without bird tracks).

1297

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

1299

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

1301and pasted as literate Haskell source.

1302