README · typeable/pandoc

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

711

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

713

714Reference links

715---------------

716

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

718brackets. So, the following links are equivalent:

719

720 1. Here's my [link]

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

722

723 [link]: linky.com

724

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

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

727

728Footnotes

729---------

730

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

732

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

734

735 [^1]: Here is the footnote.

736

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

738

739 Subsequent paragraphs are indented to show that they

740 belong to the previous footnote.

741

742 { some.code }

743

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

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

746 multi-paragraph list items.

747

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

749

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

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

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

753will be numbered sequentially.

754

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

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

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

758

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

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

761

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

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

764 note.]

765

766Inline and regular footnotes may be mixed freely.

767

768Tables

769------

770

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

772a fixed-width font, such as Courier.

773

774Simple tables look like this:

775

776 Right Left Center Default

777 ------- ------ ---------- -------

778 12 12 12 12

779 123 123 123 123

780 1 1 1 1

781

782 Table: Demonstration of simple table syntax.

783

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

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

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

787

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

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

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

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

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

793 the column is centered.

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

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

796

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

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

799

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

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

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

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

804

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

806to end the table. For example:

807

808 ------- ------ ---------- -------

809 12 12 12 12

810 123 123 123 123

811 1 1 1 1

812 ------- ------ ---------- -------

813

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

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

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

817

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

819of text. Here is an example:

820

821 -------------------------------------------------------------

822 Centered Default Right Left

823 Header Aligned Aligned Aligned

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

825 First row 12.0 Example of a row that

826 spans multiple lines.

827

828 Second row 5.0 Here's another one. Note

829 the blank line between

830 rows.

831 -------------------------------------------------------------

832

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

834 multiple lines.

835

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

837

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

839 (unless the headers are omitted).

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

841 - The rows must be separated by blank lines.

842

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

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

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

846output, try widening it in the markdown source.

847

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

849

850 ----------- ------- --------------- -------------------------

851 First row 12.0 Example of a row that

852 spans multiple lines.

853

854 Second row 5.0 Here's another one. Note

855 the blank line between

856 rows.

857 -------------------------------------------------------------

858

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

860

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

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

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

864

865Delimited Code blocks

866---------------------

867

868In addition to standard indented code blocks, Pandoc supports

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

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

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

872is treated as code. No indentation is necessary:

873

874 ~~~~~~~

875 {code here}

876 ~~~~~~~

877

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

879from surrounding text by blank lines.

880

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

882row of tildes at the start and end:

883

884 ~~~~~~~~~~~~~~~~

885 ~~~~~~~~~~

886 code including tildes

887 ~~~~~~~~~~

888 ~~~~~~~~~~~~~~~~

889

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

891this syntax:

892

893 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}

894 qsort [] = []

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

896 qsort (filter (>= x) xs)

897 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

898

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

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

901

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

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

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

905

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

907code block above will appear as follows:

908

909 <pre class="haskell">

910 <code>

911 ...

912 </code>

913 </pre>

914

915Title blocks

916------------

917

918If the file begins with a title block

919

920 % title

921 % author(s) (separated by commas)

922 % date

923

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

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

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

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

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

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

930you need a blank line:

931

932 % My title

933 %

934 % June 15, 2006

935

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

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

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

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

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

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

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

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

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

945itself as the HTML title.

946

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

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

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

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

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

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

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

954text. Thus,

955

956 % PANDOC(1)

957

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

959

960 % PANDOC(1) Pandoc User Manuals

961

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

963

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

965

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

967

968Markdown in HTML blocks

969-----------------------

970

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

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

973will turn

974

975 <table>

976 <tr>

977 <td>*one*</td>

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

979 </tr>

980 </table>

981

982into

983

984 <table>

985 <tr>

986 <td><em>one</em></td>

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

988 </tr>

989 </table>

990

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

992

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

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

995

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

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

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

999from being interpreted as markdown.

1000

1001Header identifiers in HTML

1002--------------------------

1003

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

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

1006derive the identifier from the header text,

1007

1008 - Remove all formatting, links, etc.

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

1010 and tildes.

1011 - Replace all spaces and newlines with hyphens.

1012 - Convert all alphabetic characters to lowercase.

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

1014 not begin with a number or punctuation mark).

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

1016

1017Thus, for example,

1018

1019 Header Identifier

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

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

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

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

1024 3. Applications `applications`

1025 33 `section`

1026

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

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

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

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

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

1032

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

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

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

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

1037

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

1039

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

1041only in HTML.

1042

1043Blank lines before headers and blockquotes

1044------------------------------------------

1045

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

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

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

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

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

1051example:

1052

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

1054 #5.

1055

1056Math

1057----

1058

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

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

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

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

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

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

1065

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

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

1068between $ characters.

1069

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

1071text role `:math:`, as described

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

1073

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

1075

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

1077

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

1079

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

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

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

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

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

1085

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

1087command-line options selected:

1088

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

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

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

1092 styled differently from the surrounding text if needed.

1093

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

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

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

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

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

1099 verbatim between $ characters.)

1100

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

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

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

1104 it.

1105

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

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

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

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

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

1111

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

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

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

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

1116 procedure is:

1117

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

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

1120 # and images in myfile-images

1121

1122Inline TeX

1123----------

1124

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

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

1127include BibTeX citations:

1128

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

1130

1131Note that in LaTeX environments, like

1132

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

1134 Age & Frequency \\ \hline

1135 18--25 & 15 \\

1136 26--35 & 33 \\

1137 36--45 & 22 \\ \hline

1138 \end{tabular}

1139

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

1141LaTeX, not as markdown.

1142

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

1144and ConTeXt.

1145

1146Custom headers

1147==============

1148

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

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

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

1152

1153 pandoc -D html

1154

1155 pandoc -D latex

1156

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

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

1159

1160 pandoc --custom-header=MyHeaderFile

1161

1162Producing S5 with Pandoc

1163========================

1164

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

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

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

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

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

1170

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

1172

1173 % Eating Habits

1174 % John Doe

1175 % March 22, 2005

1176

1177 # In the morning

1178

1179 - Eat eggs

1180 - Drink coffee

1181

1182 # In the evening

1183

1184 - Eat spaghetti

1185 - Drink wine

1186

1187To produce the slide show, simply type

1188

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

1190

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

1192

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

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

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

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

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

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

1199

1200 > - Eat spaghetti

1201 > - Drink wine

1202

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

1204a single document.

1205

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

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

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

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

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

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

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

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

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

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

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

1217Alternatively, you may use `-s` together with the `-C/--custom-header`

1218option.

1219

1220Literate Haskell support

1221========================

1222

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

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

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

1226

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

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

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

1230

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

1232 rendered using bird tracks, and block quotations will be

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

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

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

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

1237

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

1239 as Haskell code.

1240

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

1242 be rendered using bird tracks.

1243

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

1245 Haskell code.

1246

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

1248 inside `code` environments.

1249

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

1251 with class `literatehaskell` and bird tracks.

1252

1253Examples:

1254

1255 pandoc -f markdown+lhs -t html

1256

1257reads literate Haskell source formatted with markdown conventions and writes

1258ordinary HTML (without bird tracks).

1259

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

1261

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

1263and pasted as literate Haskell source.

1264