From 45f825eec1fc1722e95aa323a54622b099e5b324 Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Sat, 7 Dec 2024 12:30:01 +0100
Subject: [PATCH] [Doc] Mention how to work with Twig macros in Twig Components

---
 src/TwigComponent/doc/index.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst
index aa1de3ade0..5dc1c4dc85 100644
--- a/src/TwigComponent/doc/index.rst
+++ b/src/TwigComponent/doc/index.rst
@@ -365,6 +365,21 @@ You can even give the block default content. See
 :ref:`Passing HTML to Components via Block <embedded-components>`
 for more info.
 
+The only limitation when defining contents inside a component using the HTML syntax
+is that you cannot import macros using the ``_self`` keyword. You must always use
+the full template path:
+
+.. code-block:: html+twig
+
+    <twig:Alert>
+        {# ❌ this won't work #}
+        {% from _self import message_formatter %}
+        {# ✅ this works as expected #}
+        {% from 'some/path/template.html.twig' import message_formatter %}
+
+        {{ message_formatter('...') }}
+    </twig:Alert>
+
 Fetching Services
 -----------------