George Karakostas edited this page Jun 10, 2017 · 27 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

  • break-on-newline: Replace single new line characters with <br> when True.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • toc: The returned HTML string gets a new "toc_html" attribute which is a Table of Contents for the document. (experimental)
  • tables: Tables using the same format as GFM and PHP-Markdown Extra.
  • use-file-vars: Look for an Emacs-style markdown-extras file variable to turn on Extras.
  • wiki-tables: Google Code Wiki table syntax support.
  • xml: Passes one-liner processing instructions and namespaced XML tags. (TODO: wiki page for this)
  • 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.

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!*")

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


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

  Local Variables:
  markdown-extras: code-friendly, footnotes