From b348ff1a10aca42016a995f1477c63e3aa2690a4 Mon Sep 17 00:00:00 2001
From: Raniere Silva <raniere@ime.unicamp.br>
Date: Fri, 26 Jun 2015 19:37:22 -0300
Subject: [PATCH] Improve documentation of lists in Markdown

---
 doc/markdown/markdown.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

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.