Python-Markdown¶

This is a Python implementation of John Gruber’sMarkdown.It is almost completely compliant with the reference implementation,though there are a few very minordifferences. See John’sSyntax Documentationfor the syntax rules.

To get started, see theinstallation instructions, thelibraryreference, and thecommand line interface.

Goals¶

The Python-Markdown project is developed with the following goals in mind:

• Maintain a Python library (with an optional CLI wrapper) suited to use in web server environments (never raise an exception, never write to stdout, etc.) as an implementation of the markdown parser that follows thesyntax rules and the behavior of the original (markdown.pl) implementation as reasonably as possible (seedifferences for a few exceptions).

• Provide anExtension API which makes it possible to change and/or extend the behavior of the parser.

Features¶

In addition to the basic markdown syntax, Python-Markdown supports the followingfeatures:

• International Input

  Python-Markdown will acceptinput in any languagesupported by Unicode including bi-directional text. In fact the test suiteincludes documents written in Russian and Arabic.

• Extensions

  Variousextensions are provided (includingextra) to change and/or extend the base syntax.Additionally, a publicExtension API is availableto write your own extensions.

• Output Formats

  Python-Markdown can output documents with either HTML or XHTML style tags.See theLibrary Reference for details.

• Command Line Interface

  In addition to being a Python Library, acommand line script is available for your convenience.

Differences¶

While Python-Markdown strives to fully implement markdown as described in thesyntax rules, the rulescan be interpreted in different ways and different implementationsoccasionally vary in their behavior (see theBabelmark FAQfor some examples). Known and intentional differences found in Python-Markdownare summarized below:

• Middle-Word Emphasis

  Python-Markdown defaults to ignoring middle-word emphasis (and strongemphasis). In other words,some_long_filename.txt will not becomesome<em>long</em>filename.txt. This can be switched off if desired. SeetheLegacy EM Extension for details.

• Indentation/Tab Length

  Thesyntax rulesclearly state that when a list item consists of multiple paragraphs, “eachsubsequent paragraph in a list itemmust be indented by either 4 spacesor one tab” (emphasis added). However, many implementations do not enforcethis rule and allow less than 4 spaces of indentation. The implementers ofPython-Markdown consider it a bug to not enforce this rule.

  This applies to any block level elements nested in a list, includingparagraphs, sub-lists, blockquotes, code blocks, etc. Theymust alwaysbe indented by at least four spaces (or one tab) for each level of nesting.

  In the event that one would prefer different behavior,tab_length can be set to whatever length isdesired. Be warned however, as this will affect indentation for all aspectsof the syntax (including root level code blocks). Alternatively, athird party extension may offer a solution that meets your needs.

• Consecutive Lists

  While the syntax rules are not clear on this, many implementations (includingthe original) do not end one list and start a second list when the list marker(asterisks, pluses, hyphens, and numbers) changes. For consistency,Python-Markdown maintains the same behavior with no plans to change in theforeseeable future. That said, theSane List Extensionis available to provide a less surprising behavior.

Support¶

You may report bugs, ask for help, and discuss various other issues on thebug tracker.