Document blocking attribute for link,script,style elements (mdn#14648)

* Document blocking attribute for link,script,style tag * Appease the markdown linter * Apply suggestions from code review Co-authored-by: Brian Thomas Smith <[email protected]> Co-authored-by: Michael[tm] Smith <[email protected]> Co-authored-by: Florian Scholz <[email protected]>
hamishwillee · Dec 9, 2022 · c6ad66d · c6ad66d
1 parent 29a2011
commit c6ad66d
Show file tree

Hide file tree

Showing 3 changed files with 29 additions and 0 deletions.
diff --git a/files/en-us/web/html/element/link/index.md b/files/en-us/web/html/element/link/index.md
@@ -268,6 +268,9 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
     The value of the attribute should be a MIME type such as **text/html**, **text/css**, and so on.
     The common use of this attribute is to define the type of stylesheet being referenced (such as **text/css**), but given that CSS is the only stylesheet language used on the web, not only is it possible to omit the `type` attribute, but is actually now recommended practice.
     It is also used on `rel="preload"` link types, to make sure the browser only downloads file types that it supports.
+- {{HTMLAttrDef("blocking")}}
+  - : This attribute explicitly indicates that certain operations should be blocked on the fetching of an external resource. The operations that are to be blocked must be a space-separated list of blocking attributes listed below.
+    - `render`: The rendering of content on the screen is blocked.
 
 ### Non-standard attributes
 
@@ -389,6 +392,15 @@ You can determine when a style sheet has been loaded by watching for a `load` ev
 
 You can find a number of `<link rel="preload">` examples in [Preloading content with `rel="preload"`](/en-US/docs/Web/HTML/Link_types/preload).
 
+### Blocking rendering till a resource is fetched
+
+You can include `render` token inside a `blocking` attribute;
+the rendering of the page will be blocked till the resource is fetched. For example:
+
+```html
+<link blocking="render" href="critical-font.woff2" as="font">
+```
+
 ## Technical summary
 
 <table class="properties">

diff --git a/files/en-us/web/html/element/script/index.md b/files/en-us/web/html/element/script/index.md
@@ -153,6 +153,10 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
         Developers must use a valid MIME type that is not a JavaScript MIME type to denote data blocks.
         All of the other attributes will be ignored, including the `src` attribute.
 
+- {{htmlattrdef("blocking")}}
+  - : This attribute explicitly indicates that certain operations should be blocked on the fetching of the script. The operations that are to be blocked must be a space-separated list of blocking attributes listed below.
+    - `render`: The rendering of content on the screen is blocked.
+
 ### Deprecated attributes
 
 - {{htmlattrdef("charset")}} {{Deprecated_inline}}
@@ -248,6 +252,16 @@ You can also use the `<script>` element to embed data in HTML with server-side r
 </script>
 ```
 
+### Blocking rendering till a script is fetched and executed
+
+You can include `render` token inside a `blocking` attribute;
+the rendering of the page will be blocked till the script is fetched and executed. In the example below, we block rendering on an async script,
+so that the script doesn't block parsing but is guaranteed to be evaluated before rendering starts.
+
+```html
+<script blocking="render" async src="async-script.js"></script>
+```
+
 ## Specifications
 
 {{Specifications}}

diff --git a/files/en-us/web/html/element/style/index.md b/files/en-us/web/html/element/style/index.md
@@ -34,6 +34,9 @@ This element includes the [global attributes](/en-US/docs/Web/HTML/Global_attrib
   - : A cryptographic nonce (number used once) used to allow inline styles in a [style-src Content-Security-Policy](/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src). The server must generate a unique nonce value each time it transmits a policy. It is critical to provide a nonce that cannot be guessed as bypassing a resource's policy is otherwise trivial.
 - {{htmlattrdef("title")}}
   - : This attribute specifies [alternative style sheet](/en-US/docs/Web/CSS/Alternative_style_sheets) sets.
+- {{htmlattrdef("blocking")}}
+  - : This attribute explicitly indicates that certain operations should be blocked on the fetching of critical subresources. [`@import`](/en-US/docs/Web/CSS/@import)-ed stylesheets are generally considered as critical subresources, whereas [`background-image`](/en-US/docs/Web/CSS/background-image) and fonts are not.
+    - `render`: The rendering of content on the screen is blocked.
 
 ### Deprecated attributes