README · typeable/pandoc

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

729

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

731

732Reference links

733---------------

734

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

736brackets. So, the following links are equivalent:

737

738 1. Here's my [link]

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

740

741 [link]: linky.com

742

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

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

745

746Footnotes

747---------

748

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

750

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

752

753 [^1]: Here is the footnote.

754

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

756

757 Subsequent paragraphs are indented to show that they

758 belong to the previous footnote.

759

760 { some.code }

761

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

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

764 multi-paragraph list items.

765

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

767

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

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

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

771will be numbered sequentially.

772

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

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

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

776

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

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

779

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

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

782 note.]

783

784Inline and regular footnotes may be mixed freely.

785

786Tables

787------

788

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

790a fixed-width font, such as Courier.

791

792Simple tables look like this:

793

794 Right Left Center Default

795 ------- ------ ---------- -------

796 12 12 12 12

797 123 123 123 123

798 1 1 1 1

799

800 Table: Demonstration of simple table syntax.

801

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

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

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

805

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

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

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

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

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

811 the column is centered.

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

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

814

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

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

817

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

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

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

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

822

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

824to end the table. For example:

825

826 ------- ------ ---------- -------

827 12 12 12 12

828 123 123 123 123

829 1 1 1 1

830 ------- ------ ---------- -------

831

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

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

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

835

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

837of text. Here is an example:

838

839 -------------------------------------------------------------

840 Centered Default Right Left

841 Header Aligned Aligned Aligned

842 ----------- ------- --------------- -------------------------

843 First row 12.0 Example of a row that

844 spans multiple lines.

845

846 Second row 5.0 Here's another one. Note

847 the blank line between

848 rows.

849 -------------------------------------------------------------

850

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

852 multiple lines.

853

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

855

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

857 (unless the headers are omitted).

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

859 - The rows must be separated by blank lines.

860

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

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

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

864output, try widening it in the markdown source.

865

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

867

868 ----------- ------- --------------- -------------------------

869 First row 12.0 Example of a row that

870 spans multiple lines.

871

872 Second row 5.0 Here's another one. Note

873 the blank line between

874 rows.

875 -------------------------------------------------------------

876

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

878

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

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

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

882

883Delimited Code blocks

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

885

886In addition to standard indented code blocks, Pandoc supports

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

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

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

890is treated as code. No indentation is necessary:

891

892 ~~~~~~~

893 {code here}

894 ~~~~~~~

895

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

897from surrounding text by blank lines.

898

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

900row of tildes at the start and end:

901

902 ~~~~~~~~~~~~~~~~

903 ~~~~~~~~~~

904 code including tildes

905 ~~~~~~~~~~

906 ~~~~~~~~~~~~~~~~

907

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

909this syntax:

910

911 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}

912 qsort [] = []

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

914 qsort (filter (>= x) xs)

915 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

916

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

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

919

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

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

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

923

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

925code block above will appear as follows:

926

927 <pre class="haskell">

928 <code>

929 ...

930 </code>

931 </pre>

932

933Title blocks

934------------

935

936If the file begins with a title block

937

938 % title

939 % author(s) (separated by commas)

940 % date

941

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

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

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

945or all three lines. Each must begin with a % and fit on one line.

946The title may contain standard inline formatting. If you want to

947include an author but no title, or a title and a date but no author,

948you need a blank line:

949

950 % My title

951 %

952 % June 15, 2006

953

954Titles will be written only when the `--standalone` (`-s`) option is

955chosen. In HTML output, titles will appear twice: once in the

956document head -- this is the title that will appear at the top of the

957window in a browser -- and once at the beginning of the document body.

958The title in the document head can have an optional prefix attached

959(`--title-prefix` or `-T` option). The title in the body appears as

960an H1 element with class "title", so it can be suppressed or

961reformatted with CSS. If a title prefix is specified with `-T` and no

962title block appears in the document, the title prefix will be used by

963itself as the HTML title.

964

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

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

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

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

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

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

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

972text. Thus,

973

974 % PANDOC(1)

975

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

977

978 % PANDOC(1) Pandoc User Manuals

979

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

981

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

983

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

985

986Markdown in HTML blocks

987-----------------------

988

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

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

991will turn

992

993 <table>

994 <tr>

995 <td>*one*</td>

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

997 </tr>

998 </table>

999

1000into

1001

1002 <table>

1003 <tr>

1004 <td><em>one</em></td>

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

1006 </tr>

1007 </table>

1008

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

1010

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

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

1013

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

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

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

1017from being interpreted as markdown.

1018

1019Header identifiers in HTML

1020--------------------------

1021

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

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

1024derive the identifier from the header text,

1025

1026 - Remove all formatting, links, etc.

1027 - Remove all punctuation, except underscores, hyphens, periods,

1028 and tildes.

1029 - Replace all spaces and newlines with hyphens.

1030 - Convert all alphabetic characters to lowercase.

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

1032 not begin with a number or punctuation mark).

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

1034

1035Thus, for example,

1036

1037 Header Identifier

1038 ------------------------------------- ---------------------------

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

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

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

1042 3. Applications `applications`

1043 33 `section`

1044

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

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

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

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

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

1050

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

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

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

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

1055

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

1057

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

1059only in HTML.

1060

1061Blank lines before headers and blockquotes

1062------------------------------------------

1063

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

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

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

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

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

1069example:

1070

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

1072 #5.

1073

1074Math

1075----

1076

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

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

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

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

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

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

1083

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

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

1086between $ characters.

1087

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

1089text role `:math:`, as described

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

1091

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

1093

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

1095

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

1097

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

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

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

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

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

1103

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

1105command-line options selected:

1106

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

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

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

1110 styled differently from the surrounding text if needed.

1111

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

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

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

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

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

1117 verbatim between $ characters.)

1118

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

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

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

1122 it.

1123

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

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

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

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

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

1129

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

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

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

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

1134 procedure is:

1135

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

1137 gladtex -d myfile-images myfile.htex # produces myfile.html

1138 # and images in myfile-images

1139

1140Inline TeX

1141----------

1142

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

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

1145include BibTeX citations:

1146

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

1148

1149Note that in LaTeX environments, like

1150

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

1152 Age & Frequency \\ \hline

1153 18--25 & 15 \\

1154 26--35 & 33 \\

1155 36--45 & 22 \\ \hline

1156 \end{tabular}

1157

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

1159LaTeX, not as markdown.

1160

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

1162and ConTeXt.

1163

1164Custom headers

1165==============

1166

1167When run with the "standalone" option (`-s`), `pandoc` creates a

1168standalone file, complete with an appropriate header. To see the

1169default headers used for html and latex, use the following commands:

1170

1171 pandoc -D html

1172

1173 pandoc -D latex

1174

1175If you want to use a different header, just create a file containing

1176it and specify it on the command line as follows:

1177

1178 pandoc --custom-header=MyHeaderFile

1179

1180Producing S5 with Pandoc

1181========================

1182

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

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

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

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

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

1188

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

1190

1191 % Eating Habits

1192 % John Doe

1193 % March 22, 2005

1194

1195 # In the morning

1196

1197 - Eat eggs

1198 - Drink coffee

1199

1200 # In the evening

1201

1202 - Eat spaghetti

1203 - Drink wine

1204

1205To produce the slide show, simply type

1206

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

1208

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

1210

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

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

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

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

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

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

1217

1218 > - Eat spaghetti

1219 > - Drink wine

1220

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

1222a single document.

1223

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

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

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

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

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

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

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

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

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

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

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

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

1236option to specify a custom template.

1237

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

1239in `$HOME/.pandoc/s5/default` (on unix) or

1240`C:\Documents And Settings\USERNAME\Application Data\pandoc\reference.odt`

1241(on Windows). The originals may be found in pandoc's system

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

1243Pandoc will look there for any files it does not find in the user's

1244pandoc data directory.

1245

1246Literate Haskell support

1247========================

1248

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

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

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

1252

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

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

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

1256

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

1258 rendered using bird tracks, and block quotations will be

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

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

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

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

1263

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

1265 as Haskell code.

1266

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

1268 be rendered using bird tracks.

1269

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

1271 Haskell code.

1272

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

1274 inside `code` environments.

1275

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

1277 with class `literatehaskell` and bird tracks.

1278

1279Examples:

1280

1281 pandoc -f markdown+lhs -t html

1282

1283reads literate Haskell source formatted with markdown conventions and writes

1284ordinary HTML (without bird tracks).

1285

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

1287

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

1289and pasted as literate Haskell source.

1290