From c126ad3ba97a90cd2a1eed4b75881745ac896bff Mon Sep 17 00:00:00 2001
From: Robin Stocker <robin@nibor.org>
Date: Sat, 13 Sep 2025 10:11:01 +1000
Subject: [PATCH] Add docs to ListItem and its appendChild about tight lists

---
 .../java/org/commonmark/node/ListItem.java     | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/commonmark/src/main/java/org/commonmark/node/ListItem.java b/commonmark/src/main/java/org/commonmark/node/ListItem.java
index e488e8fb..c4d1214e 100644
--- a/commonmark/src/main/java/org/commonmark/node/ListItem.java
+++ b/commonmark/src/main/java/org/commonmark/node/ListItem.java
@@ -2,6 +2,10 @@
 
 /**
  * A child of a {@link ListBlock}, containing other blocks (e.g. {@link Paragraph}, other lists, etc).
+ * <p>
+ * Note that a list item can't directly contain {@link Text}, it needs to be:
+ * {@link ListItem} : {@link Paragraph} : {@link Text}.
+ * If you want a list that is rendered tightly, create a list with {@link ListBlock#setTight(boolean)}.
  *
  * @see <a href="https://spec.commonmark.org/0.31.2/#list-items">CommonMark Spec: List items</a>
  */
@@ -57,4 +61,18 @@ public Integer getContentIndent() {
     public void setContentIndent(Integer contentIndent) {
         this.contentIndent = contentIndent;
     }
+
+    /**
+     * @deprecated list items should only contain block nodes; if you're trying to create a list that is rendered
+     * without paragraphs, use {@link ListBlock#setTight(boolean)} instead.
+     */
+    @Override
+    @Deprecated
+    public void appendChild(Node child) {
+        super.appendChild(child);
+    }
+
+    public void appendChild(Block child) {
+        super.appendChild(child);
+    }
 }