From 068a2e6cb4d74c1d1ec5d3b5888a7c1e69a41173 Mon Sep 17 00:00:00 2001
From: Andy Blum <andy.blum.01@gmail.com>
Date: Wed, 17 Jun 2026 09:57:25 -0400
Subject: [PATCH] Add documention note about variable scope of override blocks
 in {% embed ... only %}

---
 doc/tags/embed.rst   | 26 +++++++++++++++++++++++++-
 doc/tags/include.rst |  4 ++++
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/doc/tags/embed.rst b/doc/tags/embed.rst
index 17013b9b0..004dc7f89 100644
--- a/doc/tags/embed.rst
+++ b/doc/tags/embed.rst
@@ -73,7 +73,7 @@ two boxes side by side:
     ┌─── page layout ─────────────────────┐
     │                                     │
     │           ┌── block "content" ──┐   │
-    │           │                     │   │    
+    │           │                     │   │
     │           │ ┌ block ┐ ┌ block ┐ │   │
     │           │ │"left" │ │"right"│ │   │
     │           │ │       │ │       │ │   │
@@ -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
diff --git a/doc/tags/include.rst b/doc/tags/include.rst
index 3d2b2e089..10ca371b5 100644
--- a/doc/tags/include.rst
+++ b/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.