1title: Sane Lists Extension 2 3Sane Lists 4========== 5 6Summary 7------- 8 9The Sane Lists extension alters the behavior of the Markdown List syntax 10to be less surprising. 11 12This extension is included in the standard Markdown library. 13 14Syntax 15------ 16 17Sane Lists do not allow the mixing of list types. In other words, an ordered 18list will not continue when an unordered list item is encountered and 19vice versa. For example: 20 21```md 221. Ordered item 1 232. Ordered item 2 24 25* Unordered item 1 26* Unordered item 2 27``` 28 29will result in the following output: 30 31```html 32<ol> 33 <li>Ordered item 1</li> 34 <li>Ordered item 2</li> 35</ol> 36 37<ul> 38 <li>Unordered item 1</li> 39 <li>Unordered item 2</li> 40</ul> 41``` 42 43Whereas the default Markdown behavior would be to generate an unordered list. 44 45Note that, unlike the default Markdown behavior, if a blank line is not 46included between list items, the different list type is ignored completely. 47This corresponds to the behavior of paragraphs. For example: 48 49```md 50A Paragraph. 51* Not a list item. 52 531. Ordered list item. 54* Not a separate list item. 55``` 56 57With this extension the above will result in the following output: 58 59```html 60<p>A Paragraph. 61* Not a list item.</p> 62 63<ol> 64 <li>Ordered list item. 65 * Not a separate list item.</li> 66</ol> 67``` 68 69Sane lists also recognize the number used in ordered lists. Given the following 70list: 71 72```md 734. Apples 745. Oranges 756. Pears 76``` 77 78By default markdown will ignore the fact that the first line started 79with item number "4" and the HTML list will start with a number "1". 80This extension will result in the following HTML output: 81 82```html 83<ol start="4"> 84 <li>Apples</li> 85 <li>Oranges</li> 86 <li>Pears</li> 87</ol> 88``` 89 90In all other ways, Sane Lists should behave as normal Markdown lists. 91 92Usage 93----- 94 95See [Extensions](index.md) for general extension usage. Use `sane_lists` as the 96name of the extension. 97 98This extension does not accept any special configuration options. 99 100A trivial example: 101 102```python 103markdown.markdown(some_text, extensions=['sane_lists']) 104``` 105