Skip to content
IbnuAmin edited this page Jul 18, 2024 · 36 revisions

Extras provided by markdown2.py

By default markdown2.py's processing attempts to produce output exactly as defined by http://daringfireball.net/projects/markdown/syntax -- the "Markdown core." However, a few optional extras are also provided.

Implemented Extras

  • admonitions: Enable parsing of RST admonitions.
  • breaks: Control where hard breaks are inserted in the markdown.
  • code-friendly: Disable _ and __ for em and strong.
  • code-color: (DEPRECATED Use fenced-code-blocks extra instead.) Pygments-based syntax coloring of <code> sections.
  • cuddled-lists: Allow lists to be cuddled to the preceding paragraph.
  • fenced-code-blocks: Allows a code block to not have to be indented by fencing it with '```' on a line before and after. Based on http://github.github.com/github-flavored-markdown/ with support for syntax highlighting.
  • footnotes: support footnotes as in use on daringfireball.net and implemented in other Markdown processors (tho not in Markdown.pl v1.0.1).
  • header-ids: Adds "id" attributes to headers. The id value is a slug of the header text.
  • highlightjs-lang: Allows specifying the language which used for syntax highlighting when using fenced-code-blocks and highlightjs.
  • html-classes: Takes a dict mapping html tag names (lowercase) to a string to use for a "class" tag attribute. Currently only supports "pre", "code", "table" and "img" tags. Add an issue if you require this for other tags.
  • latex: Converts inline and block equations wrapped using $...$ or $$...$$ to MathML
  • link-patterns: Auto-link given regex patterns in text (e.g. bug number references, revision number references).
  • markdown-in-html: Allow the use of markdown="1" in a block HTML tag to have markdown processing be done on its contents. Similar to http://michelf.com/projects/php-markdown/extra/#markdown-attr but with some limitations.
  • metadata: Extract metadata from a leading '---'-fenced block.
  • middle-word-em: Allows or disallows emphasis syntax in the middle of words, defaulting to allow. Disabling this means that this_text_here will not be converted to this<em>text</em>here.
  • nofollow: Add rel="nofollow" to all <a> tags with an href. See http://en.wikipedia.org/wiki/Nofollow.
  • numbering: Create counters to number tables, figures, equations and graphs.
  • pyshell: Treats unindented Python interactive shell sessions as <code> blocks. (TODO: wiki page for this)
  • smarty-pants: Fancy quote, em-dash and ellipsis handling similar to http://daringfireball.net/projects/smartypants/. See old issue 42 for discussion. (TODO: wiki page for this)
  • spoiler: A special kind of blockquote commonly hidden behind a click on SO. Syntax per http://meta.stackexchange.com/a/72878.
  • strike: Parse ~~strikethrough~~ formatting.
  • tag-friendly: Requires atx style headers to have a space between the # and the header text. Useful for applications that require twitter style tags to pass through the parser.
  • tables: Tables using the same format as GFM and PHP-Markdown Extra.
  • target-blank-links: Add target="_blank" to all <a> tags with an href. This causes the link to be opened in a new tab upon a click.
  • tg-spoiler: Special spoiler syntax made by telegram, for more info.
  • toc: The returned HTML string gets a new "toc_html" attribute which is a Table of Contents for the document. (experimental)
  • use-file-vars: Look for an Emacs-style markdown-extras file variable to turn on Extras.
  • wavedrom: Support for generating Wavedrom digital timing diagrams
  • wiki-tables: Google Code Wiki table syntax support.
  • xml: Passes one-liner processing instructions and namespaced XML tags. (TODO: wiki page for this)
  • task_list: Allows github-style task lists (i.e. check boxes), see the pull request. (TODO: wiki page for this). Notice: this extra's name task_list has an underscore, not a dash.
  • mermaid: Enables the mermaid support through the related fenced code block.

How to turn on extras

Extras are all off by default and turned on as follows on the command line:

python markdown2.py --extras name1,name2 ...

and via the module interface:

>>> import markdown2
>>> html = markdown2.markdown_path(path, ..., extras=["name1", "name2"])
>>> html = markdown2.markdown("some markdown", ..., extras=["name1", "name2"])

>>> markdowner = Markdown(..., extras=["name1", "name2"])
>>> markdowner.convert("*boo!*")
<em>boo!</em>

To turn on extras which require a arguments like html-classes turn on extras with a dictionary instead of an array:

>>> classesDict = {'img':'yourclassname'}
>>> markdowner  = Markdown(extras={"tables": None, "html-classes":classesDict})

(New in v1.0.1.2) You can also now specify extras via the "markdown-extras" emacs-style local variable in the markdown text:

<!-- markdown-extras: code-friendly, footnotes -->
This markdown text will be converted with the "code-friendly" and "footnotes"
extras enabled.

or:

This markdown text will be converted with the "code-friendly" and "footnotes"
extras enabled.

<!--
  Local Variables:
  markdown-extras: code-friendly, footnotes
  End:
  -->
Clone this wiki locally