Add documention note about variable scope of override blocks in {% embed ... only %}

doc/tags/embed.rst

@@ -164,6 +164,30 @@ The ``embed`` tag takes the exact same arguments as the ``include`` tag:
         ...
     {% endembed %}
 
+.. note::
+
+    Blocks you override inside an ``embed`` are evaluated in the embedded
+    template's context, not the context of the template containing the
+    ``embed`` tag. As with ``include``, embedded templates have access to the
+    variables of the active context. You can disable access to the context by
+    appending the ``only`` keyword. This prevents override blocks
+    from accessing the surrounding context, so any variable they need must also
+    be passed explicitly through ``with``:
+
+    .. code-block:: twig
+
+        {% set name = 'Fabien' %}
+
+        {# "name" is undefined inside the block #}
+        {% embed "base" only %}
+            {% block content %}{{ name }}{% endblock %}
+        {% endembed %}
+
+        {# "name" is passed explicitly and is available #}
+        {% embed "base" with {'name': name} only %}
+            {% block content %}{{ name }}{% endblock %}
+        {% endembed %}
+
 .. warning::
 
     As embedded templates do not have "names", auto-escaping strategies based

doc/tags/include.rst

@@ -108,3 +108,7 @@ inclusion. The first template that exists will be included:
 
 If ``ignore missing`` is given, it will fall back to rendering nothing if none
 of the templates exist, otherwise it will throw an exception.
+
+.. seealso::
+
+    :doc:`embed<../tags/embed>` allows you to include another template's contents like ``include``, but also allows you to override blocks defined inside the included template.