markdown2 — A fast and complete implementation of Markdown in Python

Note

The documentation for this module is an excerpt of the documentation available on the markdown2 project page on GitHub. Minor edits have been made to make the documentation fit on one page and to remove passages that are not relevant on iOS. Also, only a summary of available extras is included here, for more information on individual extras, please refer to the project page wiki.

Markdown is a light text markup format and a processor to convert that to HTML. The originator describes it as follows:

“Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).”

– http://daringfireball.net/projects/markdown/

This (markdown2) is a fast and complete Python implementation of Markdown. It was written to closely match the behaviour of the original Perl-implemented Markdown.pl. markdown2 also comes with a number of extensions (called “extras”) for things like syntax coloring, tables, header-ids. See the “Extras” section below.

Quick usage:

>>> import markdown2
>>> markdown2.markdown("*boo!*")  # or use `html = markdown_path(PATH)`
u'<p><em>boo!</em></p>\n'

>>> markdowner = Markdown()
>>> markdowner.convert("*boo!*")
u'<p><em>boo!</em></p>\n'
>>> markdowner.convert("**boom!**")
u'<p><strong>boom!</strong></p>\n'

Extras

By default markdown2‘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

• 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” and “code” 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 add <a> tags with an href. See http://en.wikipedia.org/wiki/Nofollow.
• pyshell: Treats unindented Python interactive shell sessions as <code> blocks.
• smarty-pants: Fancy quote, em-dash and ellipsis handling similar to http://daringfireball.net/projects/smartypants/. See old issue 42 for discussion.
• toc: The returned HTML string gets a new “toc_html” attribute which is a Table of Contents for the document. (experimental)
• wiki-tables: Google Code Wiki table syntax support.
• xml: Passes one-liner processing instructions and namespaced XML tags.

How to turn on extras

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

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

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

Functions

markdown2.markdown(text, html4tags=False, tab_width=DEFAULT_TAB_WIDTH, safe_mode=None, extras=None, link_patterns=None, use_file_vars=False)

Convert the markdown-formatted text to html with the given options.

markdown2.markdown_path(path, encoding="utf-8", html4tags=False, tab_width=DEFAULT_TAB_WIDTH, safe_mode=None, extras=None, link_patterns=None, use_file_vars=False)

Same as markdown(), but use the text in a given file as input.