Skip to content

Commit 3e44e43

Browse files
committed
Update documentation for MD032/blanks-around-lists to correct an example and discuss lazy continuation lines (fixes #972).
1 parent d45d7ef commit 3e44e43

File tree

3 files changed

+93
-42
lines changed

3 files changed

+93
-42
lines changed

doc-build/md032.md

+31-14
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,45 @@ followed by a blank line:
33

44
```markdown
55
Some text
6-
* Some
7-
* List
6+
* List item
7+
* List item
88

9-
1. Some
10-
2. List
11-
Some text
9+
1. List item
10+
2. List item
11+
***
1212
```
1313

14-
To fix this, ensure that all lists have a blank line both before and after
15-
(except where the block is at the beginning or end of the document):
14+
In the first case above, text immediately precedes the unordered list. In the
15+
second case above, a thematic break immediately follows the ordered list. To fix
16+
violations of this rule, ensure that all lists have a blank line both before and
17+
after (except when the list is at the very beginning or end of the document):
1618

1719
```markdown
1820
Some text
1921

20-
* Some
21-
* List
22+
* List item
23+
* List item
2224

23-
1. Some
24-
2. List
25+
1. List item
26+
2. List item
2527

26-
Some text
28+
***
29+
```
30+
31+
Note that the following case is **not** a violation of this rule:
32+
33+
```markdown
34+
1. List item
35+
More item 1
36+
2. List item
37+
More item 2
2738
```
2839

29-
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
30-
not parse lists that don't have blank lines before and after them.
40+
Although it is not indented, the text "More item 2" is referred to as a
41+
[lazy continuation line][lazy-continuation] and considered part of the second
42+
list item.
43+
44+
Rationale: In addition to aesthetic reasons, some parsers, including kramdown,
45+
will not parse lists that don't have blank lines before and after them.
46+
47+
[lazy-continuation]: https://spec.commonmark.org/0.30/#lazy-continuation-line

doc/Rules.md

+31-14
Original file line numberDiff line numberDiff line change
@@ -1347,31 +1347,48 @@ followed by a blank line:
13471347

13481348
```markdown
13491349
Some text
1350-
* Some
1351-
* List
1350+
* List item
1351+
* List item
13521352

1353-
1. Some
1354-
2. List
1355-
Some text
1353+
1. List item
1354+
2. List item
1355+
***
13561356
```
13571357

1358-
To fix this, ensure that all lists have a blank line both before and after
1359-
(except where the block is at the beginning or end of the document):
1358+
In the first case above, text immediately precedes the unordered list. In the
1359+
second case above, a thematic break immediately follows the ordered list. To fix
1360+
violations of this rule, ensure that all lists have a blank line both before and
1361+
after (except when the list is at the very beginning or end of the document):
13601362

13611363
```markdown
13621364
Some text
13631365

1364-
* Some
1365-
* List
1366+
* List item
1367+
* List item
13661368

1367-
1. Some
1368-
2. List
1369+
1. List item
1370+
2. List item
13691371

1370-
Some text
1372+
***
13711373
```
13721374

1373-
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
1374-
not parse lists that don't have blank lines before and after them.
1375+
Note that the following case is **not** a violation of this rule:
1376+
1377+
```markdown
1378+
1. List item
1379+
More item 1
1380+
2. List item
1381+
More item 2
1382+
```
1383+
1384+
Although it is not indented, the text "More item 2" is referred to as a
1385+
[lazy continuation line][lazy-continuation] and considered part of the second
1386+
list item.
1387+
1388+
Rationale: In addition to aesthetic reasons, some parsers, including kramdown,
1389+
will not parse lists that don't have blank lines before and after them.
1390+
1391+
[lazy-continuation]: https://spec.commonmark.org/0.30/#lazy-continuation-line
13751392

13761393
<a name="md033"></a>
13771394

doc/md032.md

+31-14
Original file line numberDiff line numberDiff line change
@@ -11,28 +11,45 @@ followed by a blank line:
1111

1212
```markdown
1313
Some text
14-
* Some
15-
* List
14+
* List item
15+
* List item
1616

17-
1. Some
18-
2. List
19-
Some text
17+
1. List item
18+
2. List item
19+
***
2020
```
2121

22-
To fix this, ensure that all lists have a blank line both before and after
23-
(except where the block is at the beginning or end of the document):
22+
In the first case above, text immediately precedes the unordered list. In the
23+
second case above, a thematic break immediately follows the ordered list. To fix
24+
violations of this rule, ensure that all lists have a blank line both before and
25+
after (except when the list is at the very beginning or end of the document):
2426

2527
```markdown
2628
Some text
2729

28-
* Some
29-
* List
30+
* List item
31+
* List item
3032

31-
1. Some
32-
2. List
33+
1. List item
34+
2. List item
3335

34-
Some text
36+
***
37+
```
38+
39+
Note that the following case is **not** a violation of this rule:
40+
41+
```markdown
42+
1. List item
43+
More item 1
44+
2. List item
45+
More item 2
3546
```
3647

37-
Rationale: Aside from aesthetic reasons, some parsers, including kramdown, will
38-
not parse lists that don't have blank lines before and after them.
48+
Although it is not indented, the text "More item 2" is referred to as a
49+
[lazy continuation line][lazy-continuation] and considered part of the second
50+
list item.
51+
52+
Rationale: In addition to aesthetic reasons, some parsers, including kramdown,
53+
will not parse lists that don't have blank lines before and after them.
54+
55+
[lazy-continuation]: https://spec.commonmark.org/0.30/#lazy-continuation-line

0 commit comments

Comments
 (0)