## RAW HTML

Extension: raw_html

Markdown allows you to insert raw HTML (or DocBook) anywhere in a document (except verbatim contexts, where <, >, and & are interpreted literally). (Technically this is not an extension, since standard markdown allows it, but it has been made an extension so that it can be disabled if desired.)

The raw HTML is passed through unchanged in HTML, S5, Slidy, Slideous, DZSlides, EPUB, Markdown, and Textile output, and suppressed in other formats.

Extension: markdown_in_html_blocks

Standard markdown allows you to include HTML "blocks": blocks of HTML between balanced tags that are separated from the surrounding text with blank lines, and start and end at the left margin. Within these blocks, everything is interpreted as HTML, not markdown; so (for example), * does not signify emphasis.

Pandoc behaves this way when the markdown_strict format is used; but by default, pandoc interprets material between HTML block tags as markdown. Thus, for example, Pandoc will turn

• <table>
\	<tr>
\	\	<td>*one*</td>
\	</tr>
</table>



into

• <table>
\	<tr>
\	\	<td><em>one</em></td>
\	</tr>
</table>



whereas Markdown.pl will preserve it as is.

There is one exception to this rule: text between <script> and <style> tags is not interpreted as markdown.

This departure from standard markdown should make it easier to mix markdown with HTML block elements. For example, one can surround a block of markdown text with <div> tags without preventing it from being interpreted as markdown.

## RAW TEX

Extension: raw_tex

In addition to raw HTML, pandoc allows raw LaTeX, TeX, and ConTeXt to be included in a document. Inline TeX commands will be preserved and passed unchanged to the LaTeX and ConTeXt writers. Thus, for example, you can use LaTeX to include BibTeX citations:

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



Note that in LaTeX environments, like

• \begin{tabular}{|l|l|}\hline
Age & Frequency \\ \hline
18--25  & 15 \\
26--35  & 33 \\
36--45  & 22 \\ \hline
\end{tabular}



the material between the begin and end tags will be interpreted as raw LaTeX, not as markdown.

Inline LaTeX is ignored in output formats other than Markdown, LaTeX, and ConTeXt.

## LATEX MACROS

Extension: latex_macros


• \newcommand{\tuple}[1]{\langle #1 \rangle}

$\tuple{a, b, c}$



In LaTeX output, the \newcommand definition will simply be passed unchanged to the output.

Markdown allows links to be specified in several ways.

If you enclose a URL or email address in pointy brackets, it will become a link:

• <http://google.com>
<sam\@green.eggs.ham>



An inline link consists of the link text in square brackets, followed by the URL in parentheses. (Optionally, the URL can be followed by a link title, in quotes.)

• This is an [inline link](/url), and here$aq]s [one with a title](http://fsf.org "click here for a good time!").  There can be no space between the bracketed part and the parenthesized part. The link text can contain formatting (such as emphasis), but the title cannot. ### Reference links An explicit reference link has two parts, the link itself and the link definition, which may occur elsewhere in the document (either before or after the link). The link consists of link text in square brackets, followed by a label in square brackets. (There can be space between the two.) The link definition consists of the bracketed label, followed by a colon and a space, followed by the URL, and optionally (after a space) a link title either in quotes or in parentheses. Here are some examples: • [my label 1]: /foo/bar.html "My title, optional" [my label 2]: /foo [my label 3]: http://fsf.org (The free software foundation) [my label 4]: /bar#special \[aq]A title in single quotes\[aq]  The URL may optionally be surrounded by angle brackets: • [my label 5]: <http://foo.bar.baz>  The title may go on the next line: • [my label 3]: http://fsf.org "The free software foundation"  Note that link labels are not case sensitive. So, this will work: • Here is [my link][FOO] [Foo]: /bar/baz  In an implicit reference link, the second pair of brackets is empty, or omitted entirely: • See [my website][], or [my website]. [my website]: http://foo.bar.baz  Note: In Markdown.pl and most other markdown implementations, reference link definitions cannot occur in nested constructions such as list items or block quotes. Pandoc lifts this arbitrary seeming restriction. So the following is fine in pandoc, though not in most other implementations: • > My block [quote]. > > [quote]: /foo  ### Internal links To link to another section of the same document, use the automatically generated identifier (see Header identifiers in HTML, LaTeX, and ConTeXt, below). For example: • See the [Introduction](#introduction).  or • See the [Introduction]. [Introduction]: #introduction  Internal links are currently supported for HTML formats (including HTML slide shows and EPUB), LaTeX, and ConTeXt. ## IMAGES A link immediately preceded by a ! will be treated as an image. The link text will be used as the image\[aq]s alt text: • ![la lune](lalune.jpg "Voyage to the moon") ![movie reel] [movie reel]: movie.gif  ### Pictures with captions Extension: implicit_figures An image occurring by itself in a paragraph will be rendered as a figure with a caption.[4] (In LaTeX, a figure environment will be used; in HTML, the image will be placed in a div with class figure, together with a caption in a p with class caption.) The image\[aq]s alt text will be used as the caption. • ![This is the caption](/url/of/image.png)  If you just want a regular inline image, just make sure it is not the only thing in the paragraph. One way to do this is to insert a nonbreaking space after the image: • ![This image won\[aq]t be a figure](/url/of/image.png)\  ## FOOTNOTES Extension: footnotes Pandoc\[aq]s markdown allows footnotes, using the following syntax: • Here is a footnote reference,[^1] and another.[^longnote] [^1]: Here is the footnote. [^longnote]: Here\[aq]s one with multiple blocks. Subsequent paragraphs are indented to show that they belong to the previous footnote. { some.code } The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items. This paragraph won\[aq]t be part of the note, because it isn\[aq]t indented.  The identifiers in footnote references may not contain spaces, tabs, or newlines. These identifiers are used only to correlate the footnote reference with the note itself; in the output, footnotes will be numbered sequentially. The footnotes themselves need not be placed at the end of the document. They may appear anywhere except inside other block elements (lists, block quotes, tables, etc.). Extension: inline_notes Inline footnotes are also allowed (though, unlike regular notes, they cannot contain multiple paragraphs). The syntax is as follows: • Here is an inline note.^[Inlines notes are easier to write, since you don\[aq]t have to pick an identifier and move down to type the note.]  Inline and regular footnotes may be mixed freely. ## CITATIONS Extension: citations Using an external filter, pandoc-citeproc, pandoc can automatically generate citations and a bibliography in a number of styles. Basic usage is • pandoc --filter pandoc-citeproc myinput.txt  In order to use this feature, you will need to specify a bibliography file using the bibliography metadata field in a YAML metadata section. The bibliography may have any of these formats: Format File extension MODS .mods BibLaTeX .bib BibTeX .bibtex RIS .ris EndNote .enl EndNote XML .xml ISI .wos MEDLINE .medline Copac .copac JSON citeproc .json Note that .bib can generally be used with both BibTeX and BibLaTeX files, but you can use .bibtex to force BibTeX. Alternatively you can use a references field in the document\[aq]s YAML metadata. This should include an array of YAML-encoded references, for example: • --- references: - id: fenner2012a title: One-click science marketing author: - family: Fenner given: Martin container-title: Nature Materials volume: 11 URL: \[aq]http://dx.doi.org/10.1038/nmat3283\[aq] DOI: 10.1038/nmat3283 issue: 4 publisher: Nature Publishing Group page: 261-263 type: article-journal issued: year: 2012 month: 3 ...  (The program mods2yaml, which comes with pandoc-citeproc, can help produce these from a MODS reference collection.) By default, pandoc-citeproc will use a Chicago author-date format for citations and references. To use another style, you will need to specify a CSL 1.0 style file in the csl metadata field. A primer on creating and modifying CSL styles can be found at http://citationstyles.org/downloads/primer.html. A repository of CSL styles can be found at https://github.com/citation-style-language/styles. See also http://zotero.org/styles for easy browsing. Citations go inside square brackets and are separated by semicolons. Each citation must have a key, composed of \[aq]\@\[aq] + the citation identifier from the database, and may optionally have a prefix, a locator, and a suffix. The citation key must begin with a letter or _, and may contain alphanumerics, _, and internal punctuation characters (:.#%&-+?<>~/). Here are some examples: • Blah blah [see \@doe99, pp. 33-35; also \@smith04, ch. 1]. Blah blah [\@doe99, pp. 33-35, 38-39 and *passim*]. Blah blah [\@smith04; \@doe99].  A minus sign (-) before the \@ will suppress mention of the author in the citation. This can be useful when the author is already mentioned in the text: • Smith says blah [-\@smith04].  You can also write an in-text citation, as follows: • \@smith04 says blah. \@smith04 [p. 33] says blah.  If the style calls for a list of works cited, it will be placed at the end of the document. Normally, you will want to end your document with an appropriate header: • last paragraph... # References  The bibliography will be inserted after this header. Note that the unnumbered class will be added to this header, so that the section will not be numbered. If you want to include items in the bibliography without actually citing them in the body text, you can define a dummy nocite metadata field and put the citations there: • --- nocite: | \@item1, \@item2 ... \@item3  In this example, the document will contain a citation for item3 only, but the bibliography will contain entries for item1, item2, and item3. ## NON-PANDOC EXTENSIONS The following markdown syntax extensions are not enabled by default in pandoc, but may be enabled by adding +EXTENSION to the format name, where EXTENSION is the name of the extension. Thus, for example, markdown+hard_line_breaks is markdown with hard line breaks. Extension: lists_without_preceding_blankline Allow a list to occur right after a paragraph, with no intervening blank space. Extension: hard_line_breaks Causes all newlines within a paragraph to be interpreted as hard line breaks instead of spaces. Extension: ignore_line_breaks Causes newlines within a paragraph to be ignored, rather than being treated as spaces or as hard line breaks. This option is intended for use with East Asian languages where spaces are not used between words, but text is divided into lines for readability. Extension: tex_math_single_backslash Causes anything between $$and$$ to be interpreted as inline TeX math, and anything between \[ and$ to be interpreted as display TeX math. Note: a drawback of this extension is that it precludes escaping ( and [.

Extension: tex_math_double_backslash

Causes anything between \$$and \$$ to be interpreted as inline TeX math, and anything between \$and \$ to be interpreted as display TeX math.

Extension: markdown_attribute

By default, pandoc interprets material inside block-level tags as markdown. This extension changes the behavior so that markdown is only parsed inside block-level tags if the tags have the attribute markdown=1.

Extension: mmd_title_block

Enables a MultiMarkdown style title block at the top of the document, for example:

• Title:   My title
Author:  John Doe
Date:    September 1, 2008
Comment: This is a sample mmd title block, with
a field spanning multiple lines.



See the MultiMarkdown documentation for details. If pandoc_title_block or yaml_metadata_block is enabled, it will take precedence over mmd_title_block.

Extension: abbreviations

Parses PHP Markdown Extra abbreviation keys, like

• *[HTML]: Hyper Text Markup Language



Note that the pandoc document model does not support abbreviations, so if this extension is enabled, abbreviation keys are simply skipped (as opposed to being parsed as paragraphs).

Makes all absolute URIs into links, even when not surrounded by pointy braces <...>.

Extension: ascii_identifiers

Causes the identifiers produced by auto_identifiers to be pure ASCII. Accents are stripped off of accented latin letters, and non-latin letters are omitted.

Parses multimarkdown style key-value attributes on link and image references. Note that pandoc\[aq]s internal document model provides nowhere to put these, so they are presently just ignored.

Parses multimarkdown style header identifiers (in square brackets, after the header but before any trailing #s in an ATX header).

## MARKDOWN VARIANTS

In addition to pandoc\[aq]s extended markdown, the following markdown variants are supported:

markdown_phpextra (PHP Markdown Extra)

footnotes, pipe_tables, raw_html, markdown_attribute, fenced_code_blocks, definition_lists, intraword_underscores, header_attributes, abbreviations.

markdown_github (Github-flavored Markdown)

pipe_tables, raw_html, tex_math_single_backslash, fenced_code_blocks, fenced_code_attributes, auto_identifiers, ascii_identifiers, backtick_code_blocks, autolink_bare_uris, intraword_underscores, strikeout, hard_line_breaks

markdown_mmd (MultiMarkdown)

markdown_strict (Markdown.pl)

raw_html

## EXTENSIONS WITH FORMATS OTHER THAN MARKDOWN

Some of the extensions discussed above can be used with formats other than markdown:

\[bu]

auto_identifiers can be used with latex, rst, mediawiki, and textile input (and is used by default).

\[bu]

tex_math_dollars, tex_math_single_backslash, and tex_math_double_backslash can be used with html input. (This is handy for reading web pages formatted using MathJax, for example.)

## NOTES

### [1]

The point of this rule is to ensure that normal paragraphs starting with people\[aq]s initials, like

• B. Russell was an English philosopher.



do not get treated as list items.

This rule will not prevent

• (C) 2007 Joe Smith



from being interpreted as a list item. In this case, a backslash escape can be used:

• (C\) 2007 Joe Smith



### [2]

I have also been influenced by the suggestions of David Wheeler.

### [3]

This scheme is due to Michel Fortin, who proposed it on the Markdown discussion list.

### [4]

This feature is not yet implemented for RTF, OpenDocument, or ODT. In those formats, you\[aq]ll just get an image in a paragraph by itself, with no caption.

pandoc (1).