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
 -----------------