Sanitizer docs

src/components/LeftSidebar/LeftSidebar.astro

@@ -1,11 +1,13 @@
 ---
 import { getLanguageFromURL } from '../../languages';
-import { SIDEBAR } from '../../config';
-const { currentPage } = Astro.props;
+import { SIDEBARS } from '../../config';
+const { currentPage, frontmatter } = Astro.props;
 const currentPageMatch = currentPage.slice(1);
 const langCode = getLanguageFromURL(currentPage);
+const sidebarType = frontmatter.sidebarType ?? 'default';
+
 // SIDEBAR is a flat array. Group it by sections to properly render.
-const sidebarSections = SIDEBAR[langCode].reduce((col, item, i) => {
+const sidebarSections = SIDEBARS[sidebarType][langCode].reduce((col, item, i) => {
 	// If the first item is not a section header, create a new container section.
 	if (i === 0) {
 		if (!item.header) {

src/config.ts

@@ -31,26 +31,40 @@ export const GITHUB_EDIT_URL = `https://github.com/${GITHUB_REPO}/blob/main/`;
 //   apiKey: 'XXXXXXXXXX',
 // }
 
-export const SIDEBAR = {
-	en: [
-		{ text: '', header: true },
-		{ text: 'Mission', link: 'en/docs/mission' },
-		{ text: 'Projects', link: 'en/projects' },
-		{ text: 'Roles', link: 'https://github.com/email-markup-consortium/email-markup-consortium/blob/main/roles-and-responsibilities.md' },
-		{ text: 'Code of Conduct', link: 'https://github.com/email-markup-consortium/email-markup-consortium/blob/main/code-of-conduct.md' },
-
-		{ text: 'Help', header: true },
-		{ text: 'Contribute', link: 'en/how-to-help' },
-		{ text: 'Sponsor', link: 'en/sponsors' },
-
-		{ text: 'Docs', header: true },
-		{ text: 'Glossary', link: 'en/docs/glossary' },
-		{ text: 'Vision', link: 'en/docs/vision' },
-		{ text: 'Benefits', link: 'en/docs/benefits' },
-		{ text: 'Compliant Standards', link: 'en/docs/compliant-standards' },
-
-		{ text: 'Reports', header: true },
-		{ text: 'Accessibility', link: 'en/reports/accessibility' },
-		{ text: 'Email Clients', link: 'en/reports/email-clients' },
-	],
+export const SIDEBARS = {
+	default: {
+		en: [
+			{ text: '', header: true },
+			{ text: 'Mission', link: 'en/docs/mission' },
+			{ text: 'Projects', link: 'en/projects' },
+			{ text: 'Roles', link: 'https://github.com/email-markup-consortium/email-markup-consortium/blob/main/roles-and-responsibilities.md' },
+			{ text: 'Code of Conduct', link: 'https://github.com/email-markup-consortium/email-markup-consortium/blob/main/code-of-conduct.md' },
+
+			{ text: 'Help', header: true },
+			{ text: 'Contribute', link: 'en/how-to-help' },
+			{ text: 'Sponsor', link: 'en/sponsors' },
+
+			{ text: 'Docs', header: true },
+			{ text: 'Glossary', link: 'en/docs/glossary' },
+			{ text: 'Vision', link: 'en/docs/vision' },
+			{ text: 'Benefits', link: 'en/docs/benefits' },
+			{ text: 'Compliant Standards', link: 'en/docs/compliant-standards' },
+
+			{ text: 'Reports', header: true },
+			{ text: 'Accessibility', link: 'en/reports/accessibility' },
+			{ text: 'Email Clients', link: 'en/reports/email-clients' }
+		],
+	},
+
+	sanitizer: {
+		en: [
+			{ text: '', header: true },
+			{ text: 'Back', link: 'en/docs/' },
+
+			{ text: 'Sanitizer', header: true },
+			{ text: 'Intro', link: 'en/docs/sanitizer' },
+			{ text: 'Handling', link: 'en/docs/sanitizer/handling' },
+			{ text: 'Features', link: 'en/docs/sanitizer/features' },
+		],
+	}
 };

src/content/sanitizer/features/css/at-rules/counter-style.md

@@ -0,0 +1,7 @@
+---
+title: "@counter-style"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/at-rules/font-face.md

@@ -0,0 +1,7 @@
+---
+title: "@font-face"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/at-rules/keyframes.md

@@ -0,0 +1,7 @@
+---
+title: "@keyframes"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/at-rules/layer.md

@@ -0,0 +1,7 @@
+---
+title: "@layer"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/at-rules/media.md

@@ -0,0 +1,7 @@
+---
+title: "@media"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/at-rules/property.md

@@ -0,0 +1,7 @@
+---
+title: "@property"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/at-rules/supports.md

@@ -0,0 +1,7 @@
+---
+title: "@supports"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/properties/color.md

@@ -0,0 +1,7 @@
+---
+title: color
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/values/calc.md

@@ -0,0 +1,7 @@
+---
+title: calc()
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/values/clamp.md

@@ -0,0 +1,7 @@
+---
+title: clamp()
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/values/counters.md

@@ -0,0 +1,7 @@
+---
+title: counters(), counter()
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/values/linear-gradient.md

@@ -0,0 +1,7 @@
+---
+title: linear-gradient()
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/values/max.md

@@ -0,0 +1,7 @@
+---
+title: max()
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/values/min.md

@@ -0,0 +1,7 @@
+---
+title: min()
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/values/radialgradient.md

@@ -0,0 +1,7 @@
+---
+title: radial-gradient()
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/values/rgb.md

@@ -0,0 +1,7 @@
+---
+title: rgb(), rgba()
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/css/values/var.md

@@ -0,0 +1,7 @@
+---
+title: var()
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/html/elements/a.md

@@ -0,0 +1,88 @@
+---
+title: "<a>: The Anchor element"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+
+The `<a>` element creates a hyperlink to anything a URL can address including web pages.
+
+
+## Attributes
+
+- `download`
+- `href`
+- `hreflang`
+- `ping`
+- `referrerpolicy`
+- `rel`
+- `target`
+
+
+## Recommendation
+
+It is highly recommended for an email client to support the `<a>` element. However, special care needs to be taken with the element's attributes and their values as it has direct impact on the users' security and privacy.
+
+### download
+
+The Email Markup Consortium does not have an official recommendation at this stage.
+
+
+### href
+
+The value of the `href` attribute represent a URL. This could be a HTTP-based URL, or a URI scheme supported by browsers such as `mailto:` and `tel:`.
+
+Some URI schemes are [officially registered with Internet Assigned Numbers Authority (IANA)](https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml). There are other unofficial, but common URI schemes such as `app:`.
+
+The fact that a URI scheme is registered with IANA is not enough to determine the scheme is safe to be fully supported by an email client. The `mailto:` URI scheme is a good example of [how fully supporting a registered URI scheme](https://www.zdnet.com/article/some-email-clients-are-vulnerable-to-attacks-via-mailto-links/) is not a wise approach as it can be abused by malicious attackers.
+
+While the `href` is needed to make the `<a>` useful, the Email Markup Consortium does not currently have an official stance on what URI schemes should be considered safe. It is out of this project's scope at this stage.
+
+
+### hreflang
+
+The `hreflang` attribute and its allowed values can be safely supported.
+
+
+### ping
+
+The use of the `ping` attribute, while safe, is a privacy concern as it can be used for tracking the user. In fact, this feature is disabled by default on Firefox for this reason.
+
+However, marketing emails heavily use "click tracker" links; a URL with the sole purpose of tracking clicks and redirecting to the actual desired URL. 
+
+If click trackers are deemed safe, the `ping` attribute should be too. If used in place of click trackers, it may even elevate the user experience as the user would not need to wait for the click tracker to redirect them to the page they intend to visit.
+
+
+### target
+
+It is not recommended to support the `target` attribute with all its values. The email client can determine how and where links are opened instead.
+
+
+### referrerpolicy
+
+The Email Markup Consortium does not have an official recommendation at this stage.
+
+
+### rel
+
+If `target="_blank"` is used, it is advised to have `rel="noreferrer"` and `rel="noopener"` to protect the user from `window.opener` API exploitation attacks. This applies regardless whether the sender or the email client is the one that sets the `target` attribute.
+
+Newer browser versions implicitly sets `rel="noopener"`.
+
+
+## Resources
+
+- [MDN: `<a>`: The Anchor element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a)
+- [HTML Standard: The `a` element](https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element)
+- [Some email clients are vulnerable to attacks via 'mailto' links](https://www.zdnet.com/article/some-email-clients-are-vulnerable-to-attacks-via-mailto-links/)
+
+
+## Email client compatibility
+
+### Linking to an element on the same page
+
+<iframe title="Can I email… Local anchors" src="https://embed.caniemail.com/html-anchor-links/" width="640" height="420" style="width:100%; max-width:40rem; height:26.25rem; border:none;" loading="lazy"></iframe>
+
+### mailto URI scheme
+
+<iframe title="Can I email… mailto: links" src="https://embed.caniemail.com/html-mailto-links/" width="640" height="420" style="width:100%; max-width:40rem; height:26.25rem; border:none;" loading="lazy"></iframe>

src/content/sanitizer/features/html/elements/address.md

@@ -0,0 +1,7 @@
+---
+title: "<address>"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/html/elements/article.md

@@ -0,0 +1,7 @@
+---
+title: "<article>"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/html/elements/aside.md

@@ -0,0 +1,7 @@
+---
+title: "<aside>"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/html/elements/body.md

@@ -0,0 +1,7 @@
+---
+title: "<body>"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/html/elements/br.md

@@ -0,0 +1,7 @@
+---
+title: "<br>: the Line Break element"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/html/elements/code.md

@@ -0,0 +1,7 @@
+---
+title: "<code>"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+

src/content/sanitizer/features/html/elements/div.md

@@ -0,0 +1,34 @@
+---
+title: "<div>"
+description:
+layout: "@layouts/MainLayout"
+sidebarType: sanitizer
+---
+
+The `<div>` element is a generic container with no special meaning.
+
+## Recommendation
+
+It is highly recommended for an email client to support the `<div>` element. 
+
+
+## Impacts
+
+### Progressive enhancement
+
+In the context of email in which some HTML elements are expected not to be supported by some email clients, supporting `<div>` may allow the developer to code the email with progressive enhancement in mind and implement an alternative more basic experience.
+
+### Accessibility
+
+While it does not have any semantic meaning on its own and is mainly used for styling, adding the `role` tag attribute can change the semantic meaning of a `<div>`. Supporting `<div>` allows the developer to group elements that semantically need to belong to the same parent.
+
+
+## Resources
+
+- [MDN: `<div>`: The Content Division element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div)
+- [HTML Standard: The `div` element](https://html.spec.whatwg.org/multipage/grouping-content.html#the-div-element)
+
+
+## Email client compatibility
+
+<iframe title="Can I email… &lt;div&gt; element" src="https://embed.caniemail.com/html-div/" width="640" height="420" style="width:100%; max-width:40rem; height:26.25rem; border:none;" loading="lazy"></iframe>