aboutsummaryrefslogtreecommitdiffstats
path: root/docs/extensions/sane_lists.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/extensions/sane_lists.md')
-rw-r--r--docs/extensions/sane_lists.md75
1 files changed, 75 insertions, 0 deletions
diff --git a/docs/extensions/sane_lists.md b/docs/extensions/sane_lists.md
new file mode 100644
index 0000000..b1c1d06
--- /dev/null
+++ b/docs/extensions/sane_lists.md
@@ -0,0 +1,75 @@
+Sane Lists
+----------
+
+Summary
+-------
+
+The Sane Lists Extension alters the behavior of the Markdown List syntax
+to be less surprising.
+
+This extension is included in the standard Markdown library.
+
+Syntax
+------
+
+Sane Lists do not allow the mixing of list types. In other words, an ordered
+list will not continue when an unordered list item is encountered and
+vice versa. For example:
+
+ 1. Ordered item 1
+ 2. Ordered item 2
+
+ * Unordered item 1
+ * Unordered item 2
+
+will result in the following output:
+
+ <ol>
+ <li>Ordered item 1</li>
+ <li>Ordered item 2</li>
+ </ol>
+
+ <ul>
+ <li>Unordered item 1</li>
+ <li>Unordered item 2</li>
+ </ul>
+
+Whereas the default Markdown behavior would be to generate an unordered list.
+
+Note that, unlike the default Markdown behavior, if a blank line is not
+included between list items, the different list type is ignored completely.
+This corresponds to the behavior of paragraphs. For example:
+
+ A Paragraph.
+ * Not a list item.
+
+ 1. Ordered list item.
+ * Not a separate list item.
+
+With this extension the above will result in the following output:
+
+ <p>A Paragraph.
+ * Not a list item.</p>
+
+ <ol>
+ <li>Ordered list item.
+ * Not a separate list item.</li>
+ </ol>
+
+In all other ways, Sane Lists should behave as normal Markdown lists.
+
+Usage
+-----
+
+From the Python interpreter:
+
+ >>> html = markdown.markdown(text, ['sane_lists'])
+
+To use with other extensions, just add them to the list, like this:
+
+ >>> html = markdown.markdown(text, ['def_list', 'sane_lists'])
+
+The extension can also be called from the command line using Markdown's `-x`
+parameter:
+
+ python -m markdown -x sane_lists source.txt > output.html