8.21 Non-default 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.

8.21.1 Extension: rebase_relative_paths

Rewrite relative paths for Markdown links and images, depending on the path of the file containing the link or image link. For each link or image, pandoc will compute the directory of the containing file, relative to the working directory, and prepend the resulting path to the link or image path.

The use of this extension is best understood by example. Suppose you have a subdirectory for each chapter of a book, chap1, chap2, chap3. Each contains a file text.md and a number of images used in the chapter. You would like to have ![image](spider.jpg) in chap1/text.md refer to chap1/spider.jpg and ![image](spider.jpg) in chap2/text.md refer to chap2/spider.jpg. To do this, use

pandoc chap*/*.md -f markdown+rebase_relative_paths

Without this extension, you would have to use ![image](chap1/spider.jpg) in chap1/text.md and ![image](chap2/spider.jpg) in chap2/text.md. Links with relative paths will be rewritten in the same way as images.

Absolute paths and URLs are not changed. Neither are empty paths or paths consisting entirely of a fragment, e.g., #foo.

Note that relative paths in reference links and images will be rewritten relative to the file containing the link reference definition, not the file containing the reference link or image itself, if these differ.

8.21.2 Extension: mark

To highlight out a section of text, begin and end it with with ==. Thus, for example,

This ==is deleted text.==

8.21.3 Extension: attributes

Allows attributes to be attached to any inline or block-level element when parsing commonmark. The syntax for the attributes is the same as that used in header_attributes.

• Attributes that occur immediately after an inline element affect that element. If they follow a space, then they belong to the space. (Hence, this option subsumes inline_code_attributes and link_attributes.)
• Attributes that occur immediately before a block element, on a line by themselves, affect that element.
• Consecutive attribute specifiers may be used, either for blocks or for inlines. Their attributes will be combined.
• Attributes that occur at the end of the text of a Setext or ATX heading (separated by whitespace from the text) affect the heading element. (Hence, this option subsumes header_attributes.)
• Attributes that occur after the opening fence in a fenced code block affect the code block element. (Hence, this option subsumes fenced_code_attributes.)
• Attributes that occur at the end of a reference link definition affect links that refer to that definition.

Note that pandoc’s AST does not currently allow attributes to be attached to arbitrary elements. Hence a Span or Div container will be added if needed.

8.21.4 Extension: old_dashes

Selects the pandoc <= 1.8.2.1 behavior for parsing smart dashes: - before a numeral is an en-dash, and -- is an em-dash. This option only has an effect if smart is enabled. It is selected automatically for textile input.

8.21.5 Extension: angle_brackets_escapable

Allow < and > to be backslash-escaped, as they can be in GitHub flavored Markdown but not original Markdown. This is implied by pandoc’s default all_symbols_escapable.

8.21.6 Extension: lists_without_preceding_blankline

Allow a list to occur right after a paragraph, with no intervening blank space.

8.21.7 Extension: four_space_rule

Selects the pandoc <= 2.0 behavior for parsing lists, so that four spaces indent are needed for list item continuation paragraphs.

8.21.8 Extension: spaced_reference_links

Allow whitespace between the two components of a reference link, for example,

[foo] [bar].

8.21.9 Extension: hard_line_breaks

Causes all newlines within a paragraph to be interpreted as hard line breaks instead of spaces.

8.21.10 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.

8.21.11 Extension: east_asian_line_breaks

Causes newlines within a paragraph to be ignored, rather than being treated as spaces or as hard line breaks, when they occur between two East Asian wide characters. This is a better choice than ignore_line_breaks for texts that include a mix of East Asian wide characters and other characters.

8.21.12 Extension: emoji

Parses textual emojis like :smile: as Unicode emoticons.

8.21.13 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 [.

8.21.14 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.

8.21.15 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.

8.21.16 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.

8.21.17 Extension: abbreviations

Parses PHP Markdown Extra abbreviation keys, like

*[HTML]: Hypertext 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).

8.21.18 Extension: autolink_bare_uris

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

8.21.19 Extension: mmd_link_attributes

Parses multimarkdown style key-value attributes on link and image references. This extension should not be confused with the link_attributes extension.

This is a reference ![image][ref] with multimarkdown attributes.

[ref]: https://path.to/image "Image title" width=20px height=30px
       id=myId class="myClass1 myClass2"

8.21.20 Extension: mmd_header_identifiers

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

8.21.21 Extension: compact_definition_lists

Activates the definition list syntax of pandoc 1.12.x and earlier. This syntax differs from the one described above under Definition lists in several respects:

• No blank line is required between consecutive items of the definition list.
• To get a “tight” or “compact” list, omit space between consecutive items; the space between a term and its definition does not affect anything.
• Lazy wrapping of paragraphs is not allowed: the entire definition must be indented four spaces.¹

8.21.22 Extension: gutenberg

Use Project Gutenberg conventions for plain output: all-caps for strong emphasis, surround by underscores for regular emphasis, add extra blank space around headings.

8.21.23 Extension: sourcepos

Include source position attributes when parsing commonmark. For elements that accept attributes, a data-pos attribute is added; other elements are placed in a surrounding Div or Span element with a data-pos attribute.

8.21.24 Extension: short_subsuperscripts

Parse multimarkdown style subscripts and superscripts, which start with a ‘~’ or ‘^’ character, respectively, and include the alphanumeric sequence that follows. For example:

x^2 = 4

or

Oxygen is O~2.