From 11047c3d7eeaeacb0fd0ad353cb68094621a4648 Mon Sep 17 00:00:00 2001
From: Matheo D <32077734+WebMamba@users.noreply.github.com>
Date: Fri, 14 Apr 2023 21:03:25 +0200
Subject: [PATCH] Add docs for the new Twig Component syntax

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

diff --git a/src/TwigComponent/doc/index.rst b/src/TwigComponent/doc/index.rst
index 30ef5b0d09c..f183d384032 100644
--- a/src/TwigComponent/doc/index.rst
+++ b/src/TwigComponent/doc/index.rst
@@ -840,6 +840,86 @@ The ``with`` data is what's mounted on the component object.
 .. note::
 
     Embedded components *cannot* currently be used with LiveComponents.
+    
+Component HTML Syntax
+---------------------
+    
+.. versionadded:: 2.8
+
+    This syntax was been introduced in 2.8 and is still experimental: it may change in the future.
+    
+Twig Components come with an HTML-like syntax to ease the readability of your template:
+
+.. code-block:: html+twig
+
+    <twig:Alert></:Alert>
+    // or use a self-closing tag
+    <twig:Alert/>
+    
+You can pass props to your component by using HTML attributes. Suppose you have the following component:
+
+.. code-block:: html+twig
+
+    // "withActions" property will be set to true
+    <twig:Alert withActions message="hello"></:Alert>
+        
+You can add the ':' prefix to your attribute to indicate that the value 
+should be compiled by Twig
+
+.. code-block:: html+twig
+    
+    <twig:Alert message="hello" :user="user.id"/>
+    
+    // equal to
+    <twig:Alert message="hello" user="{{ user.id }}"/>
+    
+    // and pass object, or table, or anything you imagine
+    <twig:Alert :foo="['col' => ['foo', 'oof']]"/>
+    
+You can pass content directly inside your component.
+
+.. code-block:: html+twig
+
+    <twig:Alert>
+       // any content you want
+       <div>
+           ...
+       </div>
+    </twig:Alert>
+    
+Then in your component template, This becomes a block called content:
+
+.. code-block:: html+twig
+
+    <div class="content">
+         {% block content %}
+            // and the content will appear in here
+         {% endblock %}
+         {% block footer %}
+            ...
+         {% block footer %}
+     </div>    
+    
+In addition to the default block, you can also add named blocks:
+
+.. code-block:: html+twig
+    
+    <twig:Alert message="hello" :user="user.id">
+        <twig:block name="footer">
+            ...
+        </twig:block>
+    </twig:Alert>
+    
+And in your component template you can access your embedded block
+
+.. code-block:: html+twig
+    
+    <div class="content">
+         {% block footer %}
+            ...
+         {% block footer %}
+     </div>
+    
 
 Contributing
 ------------