From 9459106bea8492f422056d84a8e5c82ddb15fda3 Mon Sep 17 00:00:00 2001
From: gerteck <changerteck@gmail.com>
Date: Thu, 25 Dec 2025 15:23:32 +0800
Subject: [PATCH 1/2] Enhance docs for Nunjucks variables

Add docs for basic usage and escaping syntax
---
 docs/userGuide/syntax/variables.md | 48 ++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/docs/userGuide/syntax/variables.md b/docs/userGuide/syntax/variables.md
index 64ed8c8323..faed2db202 100644
--- a/docs/userGuide/syntax/variables.md
+++ b/docs/userGuide/syntax/variables.md
@@ -11,6 +11,54 @@
 
 MarkBind does not aim to alter the already robust variable features of Nunjucks, but provides several extensions to it.
 
+### Basic Usage of Variables
+
+You can define variables within a page using the {% raw %}`{% set %}`{% endraw %} tag.
+
+{{ icon_example }} Defining and using a `greeting_message` variable:
+
+<!-- Note: Using codeAndOutputCode.md directly because of need to use {% raw %}{% endraw %} -->
+%%CODE:%%
+<div class="indented">
+
+````markdown
+{% raw %}{% set greeting_message = "Hello, it's a fine day!" %}
+{{ greeting_message }}
+{{ greeting_message }}{% endraw %}
+````
+</div>
+
+%%OUTPUT:%%
+<div class="indented">
+
+<box border-left-color="grey" background-color="white">
+
+{% set greeting_message = "Hello, it's a fine day!" %}
+{{ greeting_message }}
+{{ greeting_message }}
+</box>
+</div>
+
+
+<box type="info" seamless>
+
+**Note:** Variable names should consist of alphanumeric characters and underscores only. Avoid using `-` or `.`. Names are also **case-sensitive** by default (e.g. `myVar` and `myvar` are distinct).
+</box>
+
+<div class="indented">
+
+For more advanced usage, you can refer to the official [Nunjucks documentation](https://mozilla.github.io/nunjucks/templating.html).
+
+</div>
+
+#### Escaping Nunjucks Syntax
+
+If you need to display Nunjucks syntax like {% raw %}`{% ... %}`{% endraw %} literally without processing it, you can wrap it in a {% raw %}`{% raw %}` and `{% endraw %}`{% endraw %} block.
+
+
+{{ icon_example }} `I want to display {% raw %}{% raw %}{% something here %}{% endraw %}{% endraw %}.` {{ icon_arrow_right }} I want to display {% raw %}{% something here %}{% endraw %}.
+
+
 ### Global Variables
 
 **Global variables are to be defined in the `_markbind/variables.md` file.** Each variable must have an `name` and the value can be any MarkBind-compliant code fragment. The `name` should not contain `-` and `.`. For example, `search-option` and `search.options` are not allowed.

From c165ee158c1b29169421f420de6ce9810c392b68 Mon Sep 17 00:00:00 2001
From: gerteck <changerteck@gmail.com>
Date: Thu, 25 Dec 2025 15:32:00 +0800
Subject: [PATCH 2/2] Update docs

---
 docs/userGuide/syntax/variables.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/userGuide/syntax/variables.md b/docs/userGuide/syntax/variables.md
index faed2db202..886d63cbcd 100644
--- a/docs/userGuide/syntax/variables.md
+++ b/docs/userGuide/syntax/variables.md
@@ -53,7 +53,7 @@ For more advanced usage, you can refer to the official [Nunjucks documentation](
 
 #### Escaping Nunjucks Syntax
 
-If you need to display Nunjucks syntax like {% raw %}`{% ... %}`{% endraw %} literally without processing it, you can wrap it in a {% raw %}`{% raw %}` and `{% endraw %}`{% endraw %} block.
+If you need to display Nunjucks syntax like {% raw %}`{% ... %}`{% endraw %} literally without processing it, you can enclose it within a {% raw %}`{% raw %}...{% endraw %}`{% endraw %} block.
 
 
 {{ icon_example }} `I want to display {% raw %}{% raw %}{% something here %}{% endraw %}{% endraw %}.` {{ icon_arrow_right }} I want to display {% raw %}{% something here %}{% endraw %}.