10 files changed, 415 insertions, 0 deletions

diff --git a/doc/docs/de/doc/advanced/macro.md b/doc/docs/de/doc/advanced/macro.md
index a030aea..d0760b5 100644
--- a/doc/docs/de/doc/advanced/macro.md
+++ b/doc/docs/de/doc/advanced/macro.md
@@ -229,6 +229,62 @@ print "Gültiger Enum-Typ:", $BodyType Static
 
 </YueDisplay>
 
+## Mehrzeiligen Yue-Code erzeugen
+
+Wenn ein Makro mehrzeiligen Yue-Code zurückgibt, ist eine mehrzeilige Zeichenkette in Anführungszeichen nicht zu empfehlen. Verwende stattdessen bevorzugt `-> |`.
+
+Eine Zeichenkette in Anführungszeichen behält den Text wörtlich bei, während ein YAML-Mehrzeilen-String die gemeinsame führende Einrückung entfernt. Dadurch bleiben erzeugte Yue-Blöcke in der Regel stabiler, besonders wenn der erzeugte Code Kommentare oder verschachtelte Blöcke enthält.
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
 ## Argument-Validierung
 
 Du kannst erwartete AST-Knotentypen in der Argumentliste deklarieren und zur Compile-Zeit prüfen, ob die übergebenen Makroargumente den Erwartungen entsprechen.
diff --git a/doc/docs/doc/advanced/macro.md b/doc/docs/doc/advanced/macro.md
index c057f40..935017e 100644
--- a/doc/docs/doc/advanced/macro.md
+++ b/doc/docs/doc/advanced/macro.md
@@ -229,6 +229,62 @@ print "Valid enum type:", $BodyType Static
 
 </YueDisplay>
 
+## Generating Multi-line Yue Code
+
+When a macro returns multi-line Yue code, using a quoted multi-line string is not recommended. Prefer `-> |` instead.
+
+A quoted string keeps the literal text as-is, while a YAML multiline string removes the common leading indentation. This usually makes generated Yue blocks more stable, especially when the generated code contains comments or nested blocks.
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
 ## Argument Validation
 
 You can declare the expected AST node types in the argument list, and check whether the incoming macro arguments meet the expectations at compile time.
diff --git a/doc/docs/id-id/doc/advanced/macro.md b/doc/docs/id-id/doc/advanced/macro.md
index d33ec5b..5f0021b 100644
--- a/doc/docs/id-id/doc/advanced/macro.md
+++ b/doc/docs/id-id/doc/advanced/macro.md
@@ -229,6 +229,62 @@ print "Valid enum type:", $BodyType Static
 
 </YueDisplay>
 
+## Menghasilkan kode Yue multi-baris
+
+Saat macro mengembalikan kode Yue multi-baris, penggunaan string multi-baris di dalam tanda kutip tidak direkomendasikan. Sebaiknya gunakan `-> |`.
+
+String bertanda kutip mempertahankan teks apa adanya, sedangkan string multi-baris YAML menghapus indentasi awal yang sama. Ini biasanya membuat blok Yue yang dihasilkan lebih stabil, terutama ketika kode yang dihasilkan berisi komentar atau blok bertingkat.
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
 ## Validasi Argumen
 
 Anda dapat mendeklarasikan tipe node AST yang diharapkan dalam daftar argumen, dan memeriksa apakah argumen macro yang masuk memenuhi harapan pada waktu kompilasi.
diff --git a/doc/docs/pt-br/doc/advanced/macro.md b/doc/docs/pt-br/doc/advanced/macro.md
index 18d33e0..d1025d1 100644
--- a/doc/docs/pt-br/doc/advanced/macro.md
+++ b/doc/docs/pt-br/doc/advanced/macro.md
@@ -228,6 +228,62 @@ print "Valid enum type:", $BodyType Static
 
 </YueDisplay>
 
+## Gerando código Yue em múltiplas linhas
+
+Quando uma macro retorna código Yue em múltiplas linhas, não é recomendado usar uma string multilinha entre aspas. Prefira `-> |`.
+
+Uma string entre aspas preserva o texto literal, enquanto uma string multilinha estilo YAML remove a indentação inicial comum. Isso normalmente deixa os blocos Yue gerados mais estáveis, especialmente quando o código gerado contém comentários ou blocos aninhados.
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
 ## Validação de argumentos
 
 Você pode declarar os tipos de nós AST esperados na lista de argumentos e verificar se os argumentos da macro recebidos atendem às expectativas em tempo de compilação.
diff --git a/doc/docs/zh/doc/advanced/macro.md b/doc/docs/zh/doc/advanced/macro.md
index 64cfa6d..7027f62 100644
--- a/doc/docs/zh/doc/advanced/macro.md
+++ b/doc/docs/zh/doc/advanced/macro.md
@@ -229,6 +229,62 @@ print "有效的枚举类型:", $BodyType Static
 
 </YueDisplay>
 
+## 生成多行 Yue 代码
+
+&emsp;&emsp;当宏返回多行 Yue 代码时，不推荐使用带引号的多行字符串，建议优先使用 `-> |`。
+
+&emsp;&emsp;带引号的字符串会按字面保留文本；而 YAML 风格多行字符串会移除公共前导缩进。对宏生成的 Yue 代码来说，这通常能让代码块结构更稳定，尤其是在生成代码里包含注释或嵌套块时。
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+<YueDisplay>
+
+```yue
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+</YueDisplay>
+
 ## 宏参数检查
 
 &emsp;&emsp;可以直接在参数列表中声明期望的 AST 节点类型，并在编译时检查传入的宏参数是否符合预期。
diff --git a/doc/yue-de.md b/doc/yue-de.md
index 97063f4..0d4fa7a 100644
--- a/doc/yue-de.md
+++ b/doc/yue-de.md
@@ -183,6 +183,33 @@ print "Gültiger Enum-Typ:", $BodyType Static
 -- print "Kompilierungsfehler bei Enum-Typ:", $BodyType Unknown
 ```
 
+## Mehrzeiligen Yue-Code erzeugen
+
+Wenn ein Makro mehrzeiligen Yue-Code zurückgibt, ist eine mehrzeilige Zeichenkette in Anführungszeichen nicht zu empfehlen. Verwende stattdessen bevorzugt `-> |`.
+
+Eine Zeichenkette in Anführungszeichen behält den Text wörtlich bei, während ein YAML-Mehrzeilen-String die gemeinsame führende Einrückung entfernt. Dadurch bleiben erzeugte Yue-Blöcke in der Regel stabiler, besonders wenn der erzeugte Code Kommentare oder verschachtelte Blöcke enthält.
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
 ## Argument-Validierung
 
 Du kannst erwartete AST-Knotentypen in der Argumentliste deklarieren und zur Compile-Zeit prüfen, ob die übergebenen Makroargumente den Erwartungen entsprechen.
diff --git a/doc/yue-en.md b/doc/yue-en.md
index 8f8370d..2c97b28 100644
--- a/doc/yue-en.md
+++ b/doc/yue-en.md
@@ -183,6 +183,33 @@ print "Valid enum type:", $BodyType Static
 -- print "Compilation error with enum type:", $BodyType Unknown
 ```
 
+## Generating Multi-line Yue Code
+
+When a macro returns multi-line Yue code, using a quoted multi-line string is not recommended. Prefer `-> |` instead.
+
+A quoted string keeps the literal text as-is, while a YAML multiline string removes the common leading indentation. This usually makes generated Yue blocks more stable, especially when the generated code contains comments or nested blocks.
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
 ## Argument Validation
 
 You can declare the expected AST node types in the argument list, and check whether the incoming macro arguments meet the expectations at compile time.
diff --git a/doc/yue-id-id.md b/doc/yue-id-id.md
index 39ba24d..8661ecf 100644
--- a/doc/yue-id-id.md
+++ b/doc/yue-id-id.md
@@ -183,6 +183,33 @@ print "Valid enum type:", $BodyType Static
 -- print "Compilation error with enum type:", $BodyType Unknown
 ```
 
+## Menghasilkan kode Yue multi-baris
+
+Saat macro mengembalikan kode Yue multi-baris, penggunaan string multi-baris di dalam tanda kutip tidak direkomendasikan. Sebaiknya gunakan `-> |`.
+
+String bertanda kutip mempertahankan teks apa adanya, sedangkan string multi-baris YAML menghapus indentasi awal yang sama. Ini biasanya membuat blok Yue yang dihasilkan lebih stabil, terutama ketika kode yang dihasilkan berisi komentar atau blok bertingkat.
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
 ## Validasi Argumen
 
 Anda dapat mendeklarasikan tipe node AST yang diharapkan dalam daftar argumen, dan memeriksa apakah argumen macro yang masuk memenuhi harapan pada waktu kompilasi.
diff --git a/doc/yue-pt-br.md b/doc/yue-pt-br.md
index a0e3268..7bf5ab6 100644
--- a/doc/yue-pt-br.md
+++ b/doc/yue-pt-br.md
@@ -183,6 +183,33 @@ print "Valid enum type:", $BodyType Static
 -- print "Compilation error with enum type:", $BodyType Unknown
 ```
 
+## Gerando código Yue em múltiplas linhas
+
+Quando uma macro retorna código Yue em múltiplas linhas, não é recomendado usar uma string multilinha entre aspas. Prefira `-> |`.
+
+Uma string entre aspas preserva o texto literal, enquanto uma string multilinha estilo YAML remove a indentação inicial comum. Isso normalmente deixa os blocos Yue gerados mais estáveis, especialmente quando o código gerado contém comentários ou blocos aninhados.
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
 ## Validação de argumentos
 
 Você pode declarar os tipos de nós AST esperados na lista de argumentos e verificar se os argumentos da macro recebidos atendem às expectativas em tempo de compilação.
diff --git a/doc/yue-zh.md b/doc/yue-zh.md
index cb44d22..b69fcf6 100644
--- a/doc/yue-zh.md
+++ b/doc/yue-zh.md
@@ -183,6 +183,33 @@ print "有效的枚举类型:", $BodyType Static
 -- print "编译报错的枚举类型:", $BodyType Unknown
 ```
 
+## 生成多行 Yue 代码
+
+&emsp;&emsp;当宏返回多行 Yue 代码时，不推荐使用带引号的多行字符串，建议优先使用 `-> |`。
+
+&emsp;&emsp;带引号的字符串会按字面保留文本；而 YAML 风格多行字符串会移除公共前导缩进。对宏生成的 Yue 代码来说，这通常能让代码块结构更稳定，尤其是在生成代码里包含注释或嵌套块时。
+
+```yuescript
+macro default_conf = (conf) -> "
+  -- useful; only set once
+#{conf}.identity = 'LOVE'
+#{conf}.version = \"11.5\"
+  "
+
+love.conf = (t) ->
+  $default_conf t
+```
+
+```yuescript
+macro default_conf = (conf) -> |
+  -- useful; only set once
+  #{conf}.identity = 'LOVE'
+  #{conf}.version = "11.5"
+
+love.conf = (t) ->
+  $default_conf t
+```
+
 ## 宏参数检查
 
 &emsp;&emsp;可以直接在参数列表中声明期望的 AST 节点类型，并在编译时检查传入的宏参数是否符合预期。