aboutsummaryrefslogtreecommitdiffstats
path: root/docs/index.txt
diff options
context:
space:
mode:
Diffstat (limited to 'docs/index.txt')
-rw-r--r--docs/index.txt67
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
-------