Debian Codegraph @

docs/extensions/sane_lists.md

raw
1 title: Sane Lists Extension
2
3 Sane Lists
4 ==========
5
6 Summary
7 -------
8
9 The Sane Lists extension alters the behavior of the Markdown List syntax
10 to be less surprising.
11
12 This extension is included in the standard Markdown library.
13
14 Syntax
15 ------
16
17 Sane Lists do not allow the mixing of list types. In other words, an ordered
18 list will not continue when an unordered list item is encountered and
19 vice versa. For example:
20
21 ```md
22 1. Ordered item 1
23 2. Ordered item 2
24
25 * Unordered item 1
26 * Unordered item 2
27 ```
28
29 will 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
43 Whereas the default Markdown behavior would be to generate an unordered list.
44
45 Note that, unlike the default Markdown behavior, if a blank line is not
46 included between list items, the different list type is ignored completely.
47 This corresponds to the behavior of paragraphs. For example:
48
49 ```md
50 A Paragraph.
51 * Not a list item.
52
53 1. Ordered list item.
54 * Not a separate list item.
55 ```
56
57 With 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
69 Sane lists also recognize the number used in ordered lists. Given the following
70 list:
71
72 ```md
73 4. Apples
74 5. Oranges
75 6. Pears
76 ```
77
78 By default markdown will ignore the fact that the first line started
79 with item number "4" and the HTML list will start with a number "1".
80 This 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
90 In all other ways, Sane Lists should behave as normal Markdown lists.
91
92 Usage
93 -----
94
95 See [Extensions](index.md) for general extension usage. Use `sane_lists` as the
96 name of the extension.
97
98 This extension does not accept any special configuration options.
99
100 A trivial example:
101
102 ```python
103 markdown.markdown(some_text, extensions=['sane_lists'])
104 ```