From 70a9725f3b3b8f9cfda7010778b65fbc52f774b2 Mon Sep 17 00:00:00 2001
From: Chan Yu Cheng <e0560244@u.nus.edu>
Date: Sun, 2 Apr 2023 14:11:43 +0800
Subject: [PATCH] Add documentation that markdown is not rendered when
 including variables

---
 docs/userGuide/syntax/includes.md | 56 +++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/docs/userGuide/syntax/includes.md b/docs/userGuide/syntax/includes.md
index 43c41ab6f3..0a26af83a7 100644
--- a/docs/userGuide/syntax/includes.md
+++ b/docs/userGuide/syntax/includes.md
@@ -61,6 +61,62 @@ The `<include>` mechanism can be used inside any MarkBind source file (even insi
 </span>
 </include>
 
+<panel header="Markdown not rendered when including a variable">
+
+When trying to include a variable, markdown is not rendered.
+
+To fix this, either replace the markdown with html tags if possible or replace the `include` with the fragment.
+
+{{ icon_example }}
+
+<box>
+
+Include fragment in file "index.md":
+```html 
+<variable id="fragment-id">
+  
+  ### I am a header
+</variable>
+```
+
+Code that uses include fragment:
+```html
+<include src="index.md#fragment-id" />
+```
+
+The markdown will not render correctly and instead will appear as text '### I am a header'.
+</box>
+
+To fix this, either replace the markdown with html tags if possible or replace the `include` with the fragment.
+
+{{ icon_example }} Replacing markdown with html tags:
+
+<box>
+
+Include fragment in file "index.md":
+```html 
+<variable id="fragment-id">
+  <h3>I am a header<h3>
+</variable>
+```
+
+Code that uses include fragment:
+```html
+<include src="index.md#fragment-id" />
+```
+</box>
+
+{{ icon_example }} Replacing the `include` with the fragment:
+
+<box>
+Code that is supposed to use include fragment:
+
+```html
+### I am a header
+```
+</box>
+</panel>
+
 **Attributes:**
 * **`src`**: specify the source file path.
 * **`inline`** (optional): make the included result an inline element. (wrapped in `<span>` tag). e.g.,