diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md
index 6f1a2da61eb8..0b8410f8cfb8 100644
--- a/site/content/docs/02-template-syntax.md
+++ b/site/content/docs/02-template-syntax.md
@@ -1530,7 +1530,7 @@ The `<svelte:options>` element provides a place to specify per-component compile
 * `immutable={false}` — the default. Svelte will be more conservative about whether or not mutable objects have changed
 * `accessors={true}` — adds getters and setters for the component's props
 * `accessors={false}` — the default
-* `namespace="..."` — the namespace where this component will be used, most commonly "svg"
+* `namespace="..."` — the namespace where this component will be used, most commonly "svg". (Use the "foreign" namespace to opt out of case insensitive attribute names and html specific warnings)
 * `tag="..."` — the name to use when compiling this component as a custom element
 
 ```sv
diff --git a/site/content/docs/04-compile-time.md b/site/content/docs/04-compile-time.md
index 9fa0f9219505..e6e21b69e890 100644
--- a/site/content/docs/04-compile-time.md
+++ b/site/content/docs/04-compile-time.md
@@ -80,7 +80,7 @@ The following options can be passed to the compiler. None are required:
 | `outputFilename` | `null` | A `string` used for your JavaScript sourcemap.
 | `cssOutputFilename` | `null` | A `string` used for your CSS sourcemap.
 | `sveltePath` | `"svelte"` | The location of the `svelte` package. Any imports from `svelte` or `svelte/[module]` will be modified accordingly.
-
+| `namespace`  | `null`     | The namespace of the element if not `html` (eg `mathml`, `svg`, `foreign`).
 
 ---
 
diff --git a/src/compiler/utils/namespaces.ts b/src/compiler/utils/namespaces.ts
index f5d34518f432..1eb492179bfb 100644
--- a/src/compiler/utils/namespaces.ts
+++ b/src/compiler/utils/namespaces.ts
@@ -1,3 +1,5 @@
+// the foreign namespace covers all DOM implementations that aren't html5. It opts out of html5 specific a11y checks 
+// and case insensitive attribute names
 export const foreign = 'https://svelte.dev/docs#svelte_options';
 export const html = 'http://www.w3.org/1999/xhtml';
 export const mathml = 'http://www.w3.org/1998/Math/MathML';