From 4442db61559f7e06d69ed88750d43eee477abccf Mon Sep 17 00:00:00 2001
From: Jakub Vrana <jakub.vrana@csfd.cz>
Date: Mon, 28 Sep 2026 20:09:06 +0200
Subject: [PATCH] latte: documented escaping of srcdoc attribute

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 latte/cs/html-attributes.texy | 20 ++++++++++++++++++++
 latte/en/html-attributes.texy | 20 ++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/latte/cs/html-attributes.texy b/latte/cs/html-attributes.texy
index 2ad5566d57..a527c29562 100644
--- a/latte/cs/html-attributes.texy
+++ b/latte/cs/html-attributes.texy
@@ -133,6 +133,26 @@ Stejně jako `class` přijímají i atributy `aria-` pole. To se zpracuje jako s
 ```
 
 
+HTML dokument v atributu srcdoc .{data-version:3.2.0}
+=====================================================
+
+Atribut `srcdoc` elementu `<iframe>` obsahuje celý HTML dokument. Latte proto hodnotu escapuje dvakrát: nejprve jako HTML text a poté jako atribut. Řetězec se v rámu zobrazí jako prostý text a nemůže do něj vložit žádné značky:
+
+```latte
+<iframe srcdoc={$text}></iframe>
+```
+
+Pokud `$text` obsahuje `<b>Ahoj</b>`, vykreslí se:
+
+```latte
+<iframe srcdoc="&amp;lt;b&amp;gt;Ahoj&amp;lt;/b&amp;gt;"></iframe>
+```
+
+Chcete-li vložit důvěryhodné HTML, předejte ho jako objekt `Latte\Runtime\Html`. Jeho značky zůstanou zachovány a escapuje se jen jednou, jako atribut, takže stejný obsah se vykreslí jako `srcdoc="&lt;b&gt;Ahoj&lt;/b&gt;"`.
+
+Předchozí verze vkládaly řetězce jako HTML. Takové hodnoty odhalí [migrační varování |develop#Migrační varování], pokud je hodnotou atributu jediný výraz `{...}`.
+
+
 Typová kontrola
 ===============
 
diff --git a/latte/en/html-attributes.texy b/latte/en/html-attributes.texy
index eed748937e..136df96046 100644
--- a/latte/en/html-attributes.texy
+++ b/latte/en/html-attributes.texy
@@ -133,6 +133,26 @@ Just like `class`, `aria-` attributes also accept an array. It is treated as a s
 ```
 
 
+HTML Documents in srcdoc .{data-version:3.2.0}
+==============================================
+
+The `srcdoc` attribute of `<iframe>` contains a whole HTML document. Latte therefore escapes a value twice: first as HTML text and then as an attribute. A string is displayed in the frame as plain text and cannot inject any markup:
+
+```latte
+<iframe srcdoc={$text}></iframe>
+```
+
+If `$text` is `<b>Hi</b>`, it renders:
+
+```latte
+<iframe srcdoc="&amp;lt;b&amp;gt;Hi&amp;lt;/b&amp;gt;"></iframe>
+```
+
+To insert trusted HTML, pass it as a `Latte\Runtime\Html` object. Its markup is kept and escaped only once, as an attribute, so the same content renders as `srcdoc="&lt;b&gt;Hi&lt;/b&gt;"`.
+
+Previous versions inserted strings as HTML. The [migration warnings |develop#Migration Warnings] point out such values when the entire attribute value is a single `{...}` expression.
+
+
 Type Checking
 =============