1title: Python-Markdown 2 3Python-Markdown 4=============== 5 6This is a Python implementation of John Gruber's 7[Markdown](https://daringfireball.net/projects/markdown/). 8It is almost completely compliant with the reference implementation, 9though there are a few very minor [differences](#differences). See John's 10[Syntax Documentation](https://daringfireball.net/projects/markdown/syntax) 11for the syntax rules. 12 13To get started, see the [installation instructions](install.md), the [library 14reference](reference.md), and the [command line interface](cli.md). 15 16Goals 17----- 18 19The Python-Markdown project is developed with the following goals in mind: 20 21* Maintain a Python library (with an optional CLI wrapper) suited to use in web 22 server environments (never raise an exception, never write to stdout, etc.) as 23 an implementation of the markdown parser that follows the 24 [syntax rules](https://daringfireball.net/projects/markdown/syntax) and the 25 behavior of the original (markdown.pl) implementation as reasonably as 26 possible (see [differences](#differences) for a few exceptions). 27 28* Provide an [Extension API](extensions/api.md) which makes it possible 29 to change and/or extend the behavior of the parser. 30 31Features 32-------- 33 34In addition to the basic markdown syntax, Python-Markdown supports the following 35features: 36 37* __International Input__ 38 39 Python-Markdown will accept [input](reference.md#text) in any language 40 supported by Unicode including bi-directional text. In fact the test suite 41 includes documents written in Russian and Arabic. 42 43* __Extensions__ 44 45 Various [extensions](extensions/index.md) are provided (including 46 [extra](extensions/extra.md)) to change and/or extend the base syntax. 47 Additionally, a public [Extension API](extensions/api.md) is available 48 to write your own extensions. 49 50* __Output Formats__ 51 52 Python-Markdown can output documents with either HTML or XHTML style tags. 53 See the [Library Reference](reference.md#output_format) for details. 54 55* __Command Line Interface__ 56 57 In addition to being a Python Library, a 58 [command line script](cli.md) is available for your convenience. 59 60Differences 61----------- 62 63While Python-Markdown strives to fully implement markdown as described in the 64[syntax rules](https://daringfireball.net/projects/markdown/syntax), the rules 65can be interpreted in different ways and different implementations 66occasionally vary in their behavior (see the 67[Babelmark FAQ](https://johnmacfarlane.net/babelmark2/faq.html#what-are-some-examples-of-interesting-divergences-between-implementations) 68for some examples). Known and intentional differences found in Python-Markdown 69are summarized below: 70 71* __Middle-Word Emphasis__ 72 73 Python-Markdown defaults to ignoring middle-word emphasis (and strong 74 emphasis). In other words, `some_long_filename.txt` will not become 75 `some<em>long</em>filename.txt`. This can be switched off if desired. See 76 the [Legacy EM Extension](extensions/legacy_em.md) for details. 77 78* __Indentation/Tab Length__ 79 80 The [syntax rules](https://daringfireball.net/projects/markdown/syntax#list) 81 clearly state that when a list item consists of multiple paragraphs, "each 82 subsequent paragraph in a list item **must** be indented by either 4 spaces 83 or one tab" (emphasis added). However, many implementations do not enforce 84 this rule and allow less than 4 spaces of indentation. The implementers of 85 Python-Markdown consider it a bug to not enforce this rule. 86 87 This applies to any block level elements nested in a list, including 88 paragraphs, sub-lists, blockquotes, code blocks, etc. They **must** always 89 be indented by at least four spaces (or one tab) for each level of nesting. 90 91 In the event that one would prefer different behavior, 92 [tab_length](reference.md#tab_length) can be set to whatever length is 93 desired. Be warned however, as this will affect indentation for all aspects 94 of the syntax (including root level code blocks). Alternatively, a 95 [third party extension] may offer a solution that meets your needs. 96 97* __Consecutive Lists__ 98 99 While the syntax rules are not clear on this, many implementations (including 100 the original) do not end one list and start a second list when the list marker 101 (asterisks, pluses, hyphens, and numbers) changes. For consistency, 102 Python-Markdown maintains the same behavior with no plans to change in the 103 foreseeable future. That said, the [Sane List Extension](extensions/sane_lists.md) 104 is available to provide a less surprising behavior. 105 106Support 107------- 108 109You may report bugs, ask for help, and discuss various other issues on the [bug tracker][]. 110 111[third party extension]: https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions 112[bug tracker]: https://github.com/Python-Markdown/markdown/issues 113