Improve documentation of lists in Markdown

1 files changed, 30 insertions, 0 deletions

diff --git a/doc/markdown/markdown.md b/doc/markdown/markdown.md
index 9c7f723c06d..322111ae9e1 100644
--- a/doc/markdown/markdown.md
+++ b/doc/markdown/markdown.md
@@ -343,6 +343,36 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 - Or minuses
 + Or pluses
 
+If a list item contains multiple paragraphs,
+each subsequent paragraph should be indented with four spaces.
+
+```no-highlight
+1.  First ordered list item
+
+    Second paragraph of first item.
+2.  Another item
+```
+
+1.  First ordered list item
+
+    Second paragraph of first item.
+2.  Another item
+
+If the second paragraph isn't indented with four spaces,
+the second list item will be incorrectly labeled as `1`.
+
+```no-highlight
+1. First ordered list item
+
+   Second paragraph of first item.
+2. Another item
+```
+
+1. First ordered list item
+
+   Second paragraph of first item.
+2. Another item
+
 ## Links
 
 There are two ways to create links, inline-style and reference-style.