diff --git a/documentation/docs/98-reference/.generated/compile-warnings.md b/documentation/docs/98-reference/.generated/compile-warnings.md
index f6f2585df23d..3d515305fef7 100644
--- a/documentation/docs/98-reference/.generated/compile-warnings.md
+++ b/documentation/docs/98-reference/.generated/compile-warnings.md
@@ -630,6 +630,32 @@ In some situations a selector may target an element that is not 'visible' to the
Self-closing HTML tags for non-void elements are ambiguous — use `<%name% ...>` rather than `<%name% ... />`
```
+In HTML, there's [no such thing as a self-closing tag](https://jakearchibald.com/2023/against-self-closing-tags-in-html/). While this _looks_ like a self-contained element with some text next to it...
+
+```html
+
+ some text!
+
+```
+
+...a spec-compliant HTML parser (such as a browser) will in fact parse it like this, with the text _inside_ the icon:
+
+```html
+
+ some text!
+
+```
+
+Some templating languages (including Svelte) will 'fix' HTML by turning `` into ``. Others adhere to the spec. Both result in ambiguity and confusion when copy-pasting code between different contexts, and as such Svelte prompts you to resolve the ambiguity directly by having an explicit closing tag.
+
+To automate this, run the dedicated migration:
+
+```bash
+npx sv migrate self-closing-tags
+```
+
+In a future version of Svelte, self-closing tags may be upgraded from a warning to an error.
+
### event_directive_deprecated
```
diff --git a/packages/svelte/messages/compile-warnings/template.md b/packages/svelte/messages/compile-warnings/template.md
index 33e635bdb2c7..c1675e59952b 100644
--- a/packages/svelte/messages/compile-warnings/template.md
+++ b/packages/svelte/messages/compile-warnings/template.md
@@ -34,6 +34,32 @@
> Self-closing HTML tags for non-void elements are ambiguous — use `<%name% ...>` rather than `<%name% ... />`
+In HTML, there's [no such thing as a self-closing tag](https://jakearchibald.com/2023/against-self-closing-tags-in-html/). While this _looks_ like a self-contained element with some text next to it...
+
+```html
+
+ some text!
+
+```
+
+...a spec-compliant HTML parser (such as a browser) will in fact parse it like this, with the text _inside_ the icon:
+
+```html
+
+ some text!
+
+```
+
+Some templating languages (including Svelte) will 'fix' HTML by turning `` into ``. Others adhere to the spec. Both result in ambiguity and confusion when copy-pasting code between different contexts, and as such Svelte prompts you to resolve the ambiguity directly by having an explicit closing tag.
+
+To automate this, run the dedicated migration:
+
+```bash
+npx sv migrate self-closing-tags
+```
+
+In a future version of Svelte, self-closing tags may be upgraded from a warning to an error.
+
## event_directive_deprecated
> Using `on:%name%` to listen to the %name% event is deprecated. Use the event attribute `on%name%` instead