README · typeable/pandoc

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

712

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

714

715Reference links

716---------------

717

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

719brackets. So, the following links are equivalent:

720

721 1. Here's my [link]

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

723

724 [link]: linky.com

725

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

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

728

729Footnotes

730---------

731

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

733

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

735

736 [^1]: Here is the footnote.

737

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

739

740 Subsequent paragraphs are indented to show that they

741 belong to the previous footnote.

742

743 { some.code }

744

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

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

747 multi-paragraph list items.

748

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

750

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

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

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

754will be numbered sequentially.

755

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

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

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

759

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

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

762

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

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

765 note.]

766

767Inline and regular footnotes may be mixed freely.

768

769Tables

770------

771

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

773a fixed-width font, such as Courier.

774

775Simple tables look like this:

776

777 Right Left Center Default

778 ------- ------ ---------- -------

779 12 12 12 12

780 123 123 123 123

781 1 1 1 1

782

783 Table: Demonstration of simple table syntax.

784

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

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

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

788

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

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

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

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

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

794 the column is centered.

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

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

797

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

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

800

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

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

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

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

805

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

807to end the table. For example:

808

809 ------- ------ ---------- -------

810 12 12 12 12

811 123 123 123 123

812 1 1 1 1

813 ------- ------ ---------- -------

814

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

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

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

818

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

820of text. Here is an example:

821

822 -------------------------------------------------------------

823 Centered Default Right Left

824 Header Aligned Aligned Aligned

825 ----------- ------- --------------- -------------------------

826 First row 12.0 Example of a row that

827 spans multiple lines.

828

829 Second row 5.0 Here's another one. Note

830 the blank line between

831 rows.

832 -------------------------------------------------------------

833

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

835 multiple lines.

836

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

838

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

840 (unless the headers are omitted).

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

842 - The rows must be separated by blank lines.

843

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

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

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

847output, try widening it in the markdown source.

848

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

850

851 ----------- ------- --------------- -------------------------

852 First row 12.0 Example of a row that

853 spans multiple lines.

854

855 Second row 5.0 Here's another one. Note

856 the blank line between

857 rows.

858 -------------------------------------------------------------

859

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

861

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

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

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

865

866Delimited Code blocks

867---------------------

868

869In addition to standard indented code blocks, Pandoc supports

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

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

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

873is treated as code. No indentation is necessary:

874

875 ~~~~~~~

876 {code here}

877 ~~~~~~~

878

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

880from surrounding text by blank lines.

881

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

883row of tildes at the start and end:

884

885 ~~~~~~~~~~~~~~~~

886 ~~~~~~~~~~

887 code including tildes

888 ~~~~~~~~~~

889 ~~~~~~~~~~~~~~~~

890

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

892this syntax:

893

894 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}

895 qsort [] = []

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

897 qsort (filter (>= x) xs)

898 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

899

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

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

902

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

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

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

906

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

908code block above will appear as follows:

909

910 <pre class="haskell">

911 <code>

912 ...

913 </code>

914 </pre>

915

916Images with captions

917--------------------

918

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

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

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

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

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

924

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

926

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

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

929 itself, with no caption.

930

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

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

933nonbreaking space after the image:

934

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

936

937Title blocks

938------------

939

940If the file begins with a title block

941

942 % title

943 % author(s) (separated by semicolons)

944 % date

945

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

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

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

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

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

951

952 %

953 % Author

954

955 % My title

956 %

957 % June 15, 2006

958

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

960begin with leading space, thus:

961

962 % My title

963 on multiple lines

964

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

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

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

968

969 % Author One

970 Author Two

971

972 % Author One; Author Two

973

974 % Author One;

975 Author Two

976

977The date must fit on one line.

978

979All three metadata fields may contain standard inline formatting

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

981

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

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

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

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

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

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

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

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

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

991be used by itself as the HTML title.

992

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

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

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

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

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

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

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

1000text. Thus,

1001

1002 % PANDOC(1)

1003

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

1005

1006 % PANDOC(1) Pandoc User Manuals

1007

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

1009

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

1011

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

1013

1014Markdown in HTML blocks

1015-----------------------

1016

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

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

1019will turn

1020

1021 <table>

1022 <tr>

1023 <td>*one*</td>

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

1025 </tr>

1026 </table>

1027

1028into

1029

1030 <table>

1031 <tr>

1032 <td><em>one</em></td>

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

1034 </tr>

1035 </table>

1036

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

1038

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

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

1041

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

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

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

1045from being interpreted as markdown.

1046

1047Header identifiers in HTML

1048--------------------------

1049

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

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

1052derive the identifier from the header text,

1053

1054 - Remove all formatting, links, etc.

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

1056 - Replace all spaces and newlines with hyphens.

1057 - Convert all alphabetic characters to lowercase.

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

1059 not begin with a number or punctuation mark).

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

1061

1062Thus, for example,

1063

1064 Header Identifier

1065 ------------------------------------- ---------------------------

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

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

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

1069 3. Applications `applications`

1070 33 `section`

1071

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

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

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

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

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

1077

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

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

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

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

1082

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

1084

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

1086only in HTML.

1087

1088Blank lines before headers and blockquotes

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

1090

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

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

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

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

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

1096example:

1097

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

1099 #5.

1100

1101Math

1102----

1103

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

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

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

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

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

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

1110

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

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

1113between $ characters.

1114

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

1116text role `:math:`, as described

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

1118

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

1120

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

1122

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

1124

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

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

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

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

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

1130

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

1132command-line options selected:

1133

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

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

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

1137 styled differently from the surrounding text if needed.

1138

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

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

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

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

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

1144 verbatim between $ characters.)

1145

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

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

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

1149 it.

1150

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

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

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

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

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

1156

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

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

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

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

1161 procedure is:

1162

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

1164 gladtex -d myfile-images myfile.htex

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

1166

1167Inline TeX

1168----------

1169

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

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

1172include BibTeX citations:

1173

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

1175

1176Note that in LaTeX environments, like

1177

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

1179 Age & Frequency \\ \hline

1180 18--25 & 15 \\

1181 26--35 & 33 \\

1182 36--45 & 22 \\ \hline

1183 \end{tabular}

1184

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

1186LaTeX, not as markdown.

1187

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

1189and ConTeXt.

1190

1191Producing S5 with Pandoc

1192========================

1193

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

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

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

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

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

1199

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

1201

1202 % Eating Habits

1203 % John Doe

1204 % March 22, 2005

1205

1206 # In the morning

1207

1208 - Eat eggs

1209 - Drink coffee

1210

1211 # In the evening

1212

1213 - Eat spaghetti

1214 - Drink wine

1215

1216To produce the slide show, simply type

1217

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

1219

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

1221

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

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

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

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

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

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

1228

1229 > - Eat spaghetti

1230 > - Drink wine

1231

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

1233a single document.

1234

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

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

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

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

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

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

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

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

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

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

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

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

1247option to specify a custom template.

1248

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

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

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

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

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

1254directory.

1255

1256Literate Haskell support

1257========================

1258

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

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

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

1262

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

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

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

1266

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

1268 rendered using bird tracks, and block quotations will be

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

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

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

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

1273

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

1275 as Haskell code.

1276

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

1278 be rendered using bird tracks.

1279

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

1281 Haskell code.

1282

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

1284 inside `code` environments.

1285

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

1287 with class `literatehaskell` and bird tracks.

1288

1289Examples:

1290

1291 pandoc -f markdown+lhs -t html

1292

1293reads literate Haskell source formatted with markdown conventions and writes

1294ordinary HTML (without bird tracks).

1295

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

1297

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

1299and pasted as literate Haskell source.

1300