README · typeable/pandoc

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

708

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

710

711Reference links

712---------------

713

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

715brackets. So, the following links are equivalent:

716

717 1. Here's my [link]

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

719

720 [link]: linky.com

721

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

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

724

725Footnotes

726---------

727

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

729

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

731

732 [^1]: Here is the footnote.

733

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

735

736 Subsequent paragraphs are indented to show that they

737 belong to the previous footnote.

738

739 { some.code }

740

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

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

743 multi-paragraph list items.

744

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

746

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

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

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

750will be numbered sequentially.

751

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

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

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

755

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

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

758

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

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

761 note.]

762

763Inline and regular footnotes may be mixed freely.

764

765Tables

766------

767

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

769a fixed-width font, such as Courier.

770

771Simple tables look like this:

772

773 Right Left Center Default

774 ------- ------ ---------- -------

775 12 12 12 12

776 123 123 123 123

777 1 1 1 1

778

779 Table: Demonstration of simple table syntax.

780

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

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

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

784

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

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

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

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

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

790 the column is centered.

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

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

793

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

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

796

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

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

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

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

801

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

803to end the table. For example:

804

805 ------- ------ ---------- -------

806 12 12 12 12

807 123 123 123 123

808 1 1 1 1

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

810

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

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

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

814

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

816of text. Here is an example:

817

818 -------------------------------------------------------------

819 Centered Default Right Left

820 Header Aligned Aligned Aligned

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

822 First row 12.0 Example of a row that

823 spans multiple lines.

824

825 Second row 5.0 Here's another one. Note

826 the blank line between

827 rows.

828 -------------------------------------------------------------

829

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

831 multiple lines.

832

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

834

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

836 (unless the headers are omitted).

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

838 - The rows must be separated by blank lines.

839

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

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

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

843output, try widening it in the markdown source.

844

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

846

847 ----------- ------- --------------- -------------------------

848 First row 12.0 Example of a row that

849 spans multiple lines.

850

851 Second row 5.0 Here's another one. Note

852 the blank line between

853 rows.

854 -------------------------------------------------------------

855

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

857

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

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

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

861

862Delimited Code blocks

863---------------------

864

865In addition to standard indented code blocks, Pandoc supports

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

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

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

869is treated as code. No indentation is necessary:

870

871 ~~~~~~~

872 {code here}

873 ~~~~~~~

874

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

876from surrounding text by blank lines.

877

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

879row of tildes at the start and end:

880

881 ~~~~~~~~~~~~~~~~

882 ~~~~~~~~~~

883 code including tildes

884 ~~~~~~~~~~

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

886

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

888this syntax:

889

890 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.haskell .numberLines}

891 qsort [] = []

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

893 qsort (filter (>= x) xs)

894 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

895

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

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

898

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

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

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

902

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

904code block above will appear as follows:

905

906 <pre class="haskell">

907 <code>

908 ...

909 </code>

910 </pre>

911

912Title blocks

913------------

914

915If the file begins with a title block

916

917 % title

918 % author(s) (separated by commas)

919 % date

920

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

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

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

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

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

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

927you need a blank line:

928

929 % My title

930 %

931 % June 15, 2006

932

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

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

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

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

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

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

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

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

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

942itself as the HTML title.

943

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

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

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

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

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

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

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

951text. Thus,

952

953 % PANDOC(1)

954

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

956

957 % PANDOC(1) Pandoc User Manuals

958

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

960

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

962

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

964

965Markdown in HTML blocks

966-----------------------

967

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

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

970will turn

971

972 <table>

973 <tr>

974 <td>*one*</td>

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

976 </tr>

977 </table>

978

979into

980

981 <table>

982 <tr>

983 <td><em>one</em></td>

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

985 </tr>

986 </table>

987

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

989

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

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

992

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

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

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

996from being interpreted as markdown.

997

998Header identifiers in HTML

999--------------------------

1000

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

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

1003derive the identifier from the header text,

1004

1005 - Remove all formatting, links, etc.

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

1007 and tildes.

1008 - Replace all spaces and newlines with hyphens.

1009 - Convert all alphabetic characters to lowercase.

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

1011 not begin with a number or punctuation mark).

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

1013

1014Thus, for example,

1015

1016 Header Identifier

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

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

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

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

1021 3. Applications `applications`

1022 33 `section`

1023

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

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

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

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

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

1029

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

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

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

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

1034

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

1036

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

1038only in HTML.

1039

1040Blank lines before headers and blockquotes

1041------------------------------------------

1042

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

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

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

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

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

1048example:

1049

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

1051 #5.

1052

1053Math

1054----

1055

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

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

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

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

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

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

1062

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

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

1065between $ characters.

1066

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

1068text role `:math:`, as described

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

1070

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

1072

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

1074

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

1076

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

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

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

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

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

1082

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

1084command-line options selected:

1085

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

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

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

1089 styled differently from the surrounding text if needed.

1090

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

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

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

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

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

1096 verbatim between $ characters.)

1097

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

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

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

1101 it.

1102

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

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

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

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

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

1108

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

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

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

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

1113 procedure is:

1114

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

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

1117 # and images in myfile-images

1118

1119Inline TeX

1120----------

1121

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

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

1124include BibTeX citations:

1125

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

1127

1128Note that in LaTeX environments, like

1129

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

1131 Age & Frequency \\ \hline

1132 18--25 & 15 \\

1133 26--35 & 33 \\

1134 36--45 & 22 \\ \hline

1135 \end{tabular}

1136

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

1138LaTeX, not as markdown.

1139

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

1141and ConTeXt.

1142

1143Custom headers

1144==============

1145

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

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

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

1149

1150 pandoc -D html

1151

1152 pandoc -D latex

1153

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

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

1156

1157 pandoc --custom-header=MyHeaderFile

1158

1159Producing S5 with Pandoc

1160========================

1161

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

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

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

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

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

1167

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

1169

1170 % Eating Habits

1171 % John Doe

1172 % March 22, 2005

1173

1174 # In the morning

1175

1176 - Eat eggs

1177 - Drink coffee

1178

1179 # In the evening

1180

1181 - Eat spaghetti

1182 - Drink wine

1183

1184To produce the slide show, simply type

1185

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

1187

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

1189

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

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

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

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

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

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

1196

1197 > - Eat spaghetti

1198 > - Drink wine

1199

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

1201a single document.

1202

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

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

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

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

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

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

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

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

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

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

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

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

1215option.

1216

1217Literate Haskell support

1218========================

1219

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

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

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

1223

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

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

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

1227

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

1229 rendered using bird tracks, and block quotations will be

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

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

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

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

1234

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

1236 as Haskell code.

1237

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

1239 be rendered using bird tracks.

1240

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

1242 Haskell code.

1243

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

1245 inside `code` environments.

1246

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

1248 with class `literatehaskell` and bird tracks.

1249

1250Examples:

1251

1252 pandoc -f markdown+lhs -t html

1253

1254reads literate Haskell source formatted with markdown conventions and writes

1255ordinary HTML (without bird tracks).

1256

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

1258

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

1260and pasted as literate Haskell source.

1261