[Doc] Add some explanation about mixing Twig and HTML syntax in nested components

src/TwigComponent/doc/index.rst

@@ -271,6 +271,8 @@ You can control the template used via the ``AsTwigComponent`` attribute:
 You can also configure the default template directory for an entire
 namespace. See :ref:`Configuration <configuration>`.
 
+.. _component_html_syntax:
+
 Component HTML Syntax
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -1585,11 +1587,44 @@ listen to ``PreMountEvent`` or ``PostMountEvent``.
 Nested Components
 -----------------
 
-It's totally possible to nest one component into another. When you do
-this, there's nothing special to know: both components render
-independently. If you're using `Live Components`_, then there
-*are* some guidelines related to how the re-rendering of parent and
-child components works. Read `Live Nested Components`_.
+It's totally possible to include components as part of the contents of another
+component. When you do this, all components render independently. The only
+caveat is that you cannot mix the Twig syntax and the :ref:`HTML syntax <component_html_syntax>`
+when using nested components:
+
+.. code-block:: html+twig
+
+    {# ❌ this won't work because it mixes different syntaxes #}
+    <twig:Card>
+        {# ... #}
+
+        {% block footer %}
+            <twig:Button:Primary :isBlock="true">Edit</twig:Button:Primary>
+        {% endblock %}
+    </twig:Card>
+
+    {# ✅ this works because it only uses the HTML syntax #}
+    <twig:Card>
+        {# ... #}
+
+        <twig:block name="footer">
+            <twig:Button:Primary :isBlock="true">Edit</twig:Button:Primary>
+        </twig:block>
+    </twig:Card>
+
+    {# ✅ this also works because it only uses the Twig syntax #}
+    <twig:Card>
+        {# ... #}
+
+        <twig:block name="footer">
+            {% component 'Button:Primary' with {isBlock: true} %}
+                {% block content %}Edit{% endblock %}
+            {% endcomponent %}
+        </twig:block>
+    </twig:Card>
+
+If you're using `Live Components`_, then there *are* some guidelines related to
+how the re-rendering of parent and child components works. Read `Live Nested Components`_.
 
 Configuration
 -------------