added a note about auto-escaping and the embed tag

We cannot use the parent template to guess the auto-escaping strategy
either as it can be any valid expression, for which we have the real
value only at runtime (auto-escaping happening at compilation time).

diff --git a/doc/tags/embed.rst b/doc/tags/embed.rst
index e69d65c..b75f557 100644 (file)
--- a/doc/tags/embed.rst
+++ b/doc/tags/embed.rst
@@ -145,4 +145,12 @@ The ``embed`` tag takes the exact same arguments as the ``include`` tag:
         ...
     {% endembed %}
 
+.. warning::
+
+    As embedded templates do not have "names", auto-escaping strategies based
+    on the template "filename" won't work as expected if you change the
+    context (for instance, if you embed a CSS/JavaScript template into an HTML
+    one). In that case, explicitly set the default auto-escaping strategy with
+    the ``autoescape`` tag.
+
 .. seealso:: :doc:`include<../tags/include>`