diff options
Diffstat (limited to 'docs/index.txt')
| -rw-r--r-- | docs/index.txt | 67 |
1 files changed, 59 insertions, 8 deletions
diff --git a/docs/index.txt b/docs/index.txt index eb245e6..b44f5ae 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -9,12 +9,26 @@ Python-Markdown This is a Python implementation of John Gruber's [Markdown](http://daringfireball.net/projects/markdown/). It is almost completely compliant with the reference implementation, -though there are a few very minor differences. See John's +though there are a few very minor [differences](#differences). See John's [Syntax Documentation](http://daringfireball.net/projects/markdown/syntax) for the syntax rules. See the [installation instructions](install.html) to get started. +Goals +----- + +The Python-Markdown project is developed with the following goals in mind: + +* Maintain a Python 2 *and* Python 3 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 the [syntax rules](http://daringfireball.net/projects/markdown/syntax) + and the behavior of the original (markdown.pl) implementation as reasonably + as possible (see [differences](#differences) for a few exceptions). +* Provide an [Extension API](extensions/api.html) which allows any behaviors of + the parser to be overridden/changed/added. + Features -------- @@ -27,13 +41,6 @@ features: supported by Unicode including bi-directional text. In fact the test suite includes documents written in Russian and Arabic. -* __Middle-Word Emphasis__ - - Python-Markdown defaults to ignoring middle-word emphasis. In other words, - `some_long_filename.txt` will not become `some<em>long</em>filename.txt`. - This can be switched off if desired. See the - [Library Reference](reference.html#smart_emphasis) for details. - * __Extensions__ Various [extensions](extensions/index.html) are provided (including @@ -58,6 +65,50 @@ features: In addition to being a Python Library, a [command line script](cli.html) is available for your convenience. +Differences +----------- + +While Python-Markdown strives to fully implement markdown as described in the +[syntax rules](http://daringfireball.net/projects/markdown/syntax), the rules +can be interpreted in different ways and different implementations +occasionally vary in their behavior (see the +[Babelmark FAQ](http://johnmacfarlane.net/babelmark2/faq.html#what-are-some-examples-of-interesting-divergences-between-implementations) +for some examples). Known and intentional differences found in Python-Markdown +are summarized below: + +* __Middle-Word Emphasis__ + + Python-Markdown defaults to ignoring middle-word emphasis. In other words, + `some_long_filename.txt` will not become `some<em>long</em>filename.txt`. + This can be switched off if desired. See the + [Library Reference](reference.html#smart_emphasis) for details. + +* __Indentation/Tab Length__ + + The [syntax rules](http://daringfireball.net/projects/markdown/syntax#list) + clearly state that when a list item consists of multiple paragraphs, "each + subsequent paragraph in a list item **must** be indented by either 4 spaces + or one tab" (emphasis added). However, many implementations do not enforce + this rule and allow less than 4 spaces of indentation. The implementers of + Python-Markdown consider it a bug to not enforce this rule, and therefore, + subsequent paragraphs of a list **must** be indented by four spaces or one + tab. + + In the event that one would prefer different behavior, + [tab_length](reference.html#tab_length) can be set to whatever length is + desired. Be warned however, as this will affect indentation for all aspects + of the syntax (including code blocks). + +* __Consecutive Lists__ + + While the syntax rules are not clear on this, many implementations (including + the 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 the + foreseeable future. That said, the [Sane List Extension](extensions/sane_lists.html) + is available to provide a less surprising behavior. + + Support ------- |