Merge branch 'main' into templates

.github/workflows/markdown-lint-fix.yml

@@ -28,6 +28,7 @@ jobs:
 
       - name: Lint markdown files
         run: |
+          yarn content fix-flaws
           yarn fix:md
           yarn fix:fm
 

.github/workflows/pr-check_markdownlint.yml

@@ -48,8 +48,3 @@ jobs:
           yarn markdownlint-cli2 ${files_to_lint}
           echo "Linting front-matter"
           node scripts/front-matter_linter.js ${files_to_lint}
-
-      - name: Prettier markdown files
-        run: |
-          files_to_lint="${{ env.DIFF_DOCUMENTS }}"
-          yarn prettier -c ${files_to_lint}

.markdownlint-cli2.jsonc

@@ -1,35 +1,38 @@
+// This file defines our configuration for Markdownlint. See
+// https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+// for more details on each rule.
+
 {
   "config": {
     "default": true,
-    // MD001 - Heading levels should only increment by one level at a time.
-    // -> Disabled, as some callouts include headings.
-    "MD001": false,
-    "MD004": {
+    // Disabled, as some callouts include headings.
+    "header-increment": false,
+    "ul-style": {
       "style": "dash"
     },
-    "MD007": {
+    "ul-indent": {
       "indent": 2
     },
-    "MD010": {
+    "no-hard-tabs": {
       "spaces_per_tab": 2
     },
-    "MD013": false,
-    "MD024": {
+    "line-length": false,
+    "no-duplicate-header": {
       "allow_different_nesting": true
     },
-    "MD025": {
+    "single-title": {
       "front_matter_title": "^\\s*title\\s*[:=]"
     },
-    "MD026": {
+    "no-trailing-punctuation": {
       "punctuation": ".,;:"
     },
     // Consecutive Notes/Callouts currently don't conform with this rule
-    "MD028": false,
+    "no-blanks-blockquote": false,
     // Force ordered numbering to catch accidental list ending from indenting
-    "MD029": {
+    "ol-prefix": {
       "style": "ordered"
     },
-    "MD033": {
+    "no-inline-html": {
       "allowed_elements": [
         "a",
         "abbr",
@@ -100,24 +103,25 @@
         "var"
       ]
     },
-    "MD034": false,
+    "no-bare-urls": false,
     // Produces too many false positives
-    "MD037": false,
-    "MD040": false,
+    "no-space-in-emphasis": false,
+    "fenced-code-language": false,
     // See https://github.com/mdn/content/pull/20026, as macros currently break this
-    "MD042": false,
-    "MD046": {
+    "no-empty-links": false,
+    "code-block-style": {
       "style": "fenced"
     },
-    "MD049": {
+    "emphasis-style": {
       "style": "underscore"
     },
-    "MD050": {
+    "strong-style": {
       "style": "asterisk"
     },
-    // MD051 - Link fragments should be valid.
-    // -> Disabled, as yari generates link fragments by replacing spaces with underscores, not dashes.
-    "MD051": false,
+    // Disabled, as yari generates link fragments by replacing spaces with underscores, not dashes.
+    "link-fragments": false,
+
+    // https://github.com/OnkarRuikar/markdownlint-rule-search-replace
     "search-replace": {
       "rules": [
         {
@@ -207,5 +211,5 @@
     }
   },
   "customRules": ["markdownlint-rule-search-replace"],
-  "ignores": ["node_modules", ".github", "tests"]
+  "ignores": ["node_modules", ".git", ".github", "tests"]
 }

CONTRIBUTING.md

@@ -147,22 +147,29 @@ To fork and clone the repository:
 The previous sections describe how to get started using the GitHub UI to make small changes to a single file and how to create a fork and clone the repository to prepare for making larger changes.
 This section describes how to build the project locally and how to prepare your changes for submission.
 
-### Installing and running the project
+### Preparing the project
 
-To set up the site locally, you need to have [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/) installed.
+To serve the site locally, you need to have [Node.js](https://nodejs.org/) and [Yarn 1 (Classic)](https://classic.yarnpkg.com/) installed.
 You can check if these are installed by running the following commands:
 
 ```bash
 node -v
 yarn -v
 ```
 
-After you have installed Node.js and Yarn, you can install the dependencies using `yarn` and start the local preview:
+After you have installed Node.js and Yarn, you can install the dependencies using `yarn`:
 
 ```bash
 # Assuming your fork is in ~/repos/content
 cd ~/repos/content
 yarn
+```
+
+### Running the project
+
+After you have installed all dependencies, you can start the local preview using `yarn start`:
+
+```bash
 yarn start
 ```
 
@@ -184,9 +191,7 @@ To edit files and track your changes, you should use feature branches.
 Feature branches are created from the `main` branch and should be named after the feature you're working on.
 This will make it easier to submit a pull request for your changes.
 
-> **Note**
-> Open a discussion if your changes will contain large, complex or structural changes.
-> Ask for feedback before embarking on large tasks.
+> **Note:** Open a discussion if your changes will contain large, complex or structural changes. Ask for feedback before embarking on large tasks.
 
 1. When the server is running, make the changes you would like to make to one or more `index.md` files.
 
@@ -212,6 +217,14 @@ This will make it easier to submit a pull request for your changes.
    # or "git push --set-upstream origin fix-typo" if you haven't pushed this branch before
    ```
 
+#### Linting edited files
+
+To ensure that all MDN documents follow the same formatting, we use both [Prettier](https://www.prettier.io) and [Markdownlint](https://github.com/DavidAnson/markdownlint) to format and lint Markdown files. This helps us enforce uniform styling across all documents with minimal reviewer intervention.
+
+If you have a [local checkout](#forking-and-cloning-the-repository) of the repository and have [installed the dependencies](#preparing-the-project), or you are using [github.dev](https://github.dev), a pre-commit hook will be installed which automatically runs while making a commit. To save some headache and improve your work flow while authoring, you may wish to [configure your editor to automatically run Prettier](https://prettier.io/docs/en/editors.html). Alternatively, you may run `yarn fix:md` in the command line to manually format all Markdown files.
+
+> **Note:** Automatically formatting changes does not work for pull requests opened using the GitHub Web UI as described in the ["Simple changes" section](#simple-changes). This may result in failed status checks on pull requests. If you're not sure about how to fix this, [get in touch with us](/en-US/docs/MDN/Community/Communication_channels) for help.
+
 ### Adding a new document
 
 Adding a new document is relatively straightforward, especially if you can start by copying the `index.md` of a similar document.

files/en-us/_redirects.txt

@@ -9616,7 +9616,7 @@
 /en-US/docs/Web/API/Screen.unlockOrientation	/en-US/docs/Web/API/Screen/unlockOrientation
 /en-US/docs/Web/API/Screen.width	/en-US/docs/Web/API/Screen/width
 /en-US/docs/Web/API/Screen/onorientationchange	/en-US/docs/Web/API/Screen/orientationchange_event
-/en-US/docs/Web/API/ScreenOrientation/onchange	/en-US/docs/Web/API/ScreenOrientation
+/en-US/docs/Web/API/ScreenOrientation/onchange	/en-US/docs/Web/API/ScreenOrientation/change_event
 /en-US/docs/Web/API/ScriptProcessorNode.bufferSize	/en-US/docs/Web/API/ScriptProcessorNode/bufferSize
 /en-US/docs/Web/API/ScriptProcessorNode.onaudioprocess	/en-US/docs/Web/API/ScriptProcessorNode/audioprocess_event
 /en-US/docs/Web/API/ScriptProcessorNode/audioprocess	/en-US/docs/Web/API/ScriptProcessorNode/audioprocess_event

files/en-us/glossary/boolean/javascript/index.md

@@ -1,12 +1,12 @@
 ---
-title: Boolean (Javascript)
+title: Boolean (JavaScript)
 slug: Glossary/Boolean/JavaScript
 page-type: glossary-definition
 ---
 
 {{GlossarySidebar}}
 
-A **Boolean** in Javascript is a {{Glossary("Primitive", "primitive value")}} that can be either `true` or `false`.
+A **Boolean** in JavaScript is a {{Glossary("Primitive", "primitive value")}} that can be either `true` or `false`.
 
 A {{jsxref("Boolean")}} object is a {{Glossary("wrapper")}} around a Boolean primitive.
 

files/en-us/glossary/dns/index.md

@@ -8,7 +8,7 @@ page-type: glossary-definition
 
 **DNS** (Domain Name System) is a hierarchical and decentralized naming system for Internet connected resources. DNS maintains a list of {{Glossary("domain name","domain names")}} along with the resources, such as IP addresses, that are associated with them.
 
-The most prominent function of DNS is the translation of human-friendly domain names (such as mozilla.org) to a numeric {{Glossary("IP address")}} (such as 151.106.5.172); this process of mapping a domain name to the appropriate IP address is known as a **DNS lookup**. By contrast, a **reverse DNS lookup** (rDNS) is used to determine the domain name associated with an IP address.
+The most prominent function of DNS is the translation of human-friendly domain names (such as mozilla.org) to a numeric {{Glossary("IP address")}} (such as 192.0.2.172); this process of mapping a domain name to the appropriate IP address is known as a **DNS lookup**. By contrast, a **reverse DNS lookup** (rDNS) is used to determine the domain name associated with an IP address.
 
 ## See also
 

files/en-us/glossary/percent-encoding/index.md

@@ -39,3 +39,4 @@ Depending on the context, the character `' '` is translated to a `'+'` (like in
 
 - Definition of [percent-encoding](https://en.wikipedia.org/wiki/Percent-encoding) in Wikipedia.
 - {{RFC(3986)}}, section 2.1, where this encoding is defined.
+- [`encodeURI()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI) and [`encodeURIComponent()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) — functions to percent-encode URLs

files/en-us/glossary/preflight_request/index.md

@@ -8,7 +8,7 @@ page-type: glossary-definition
 
 A CORS preflight request is a {{Glossary("CORS")}} request that checks to see if the CORS protocol is understood and a server is aware using specific methods and headers.
 
-It is an {{HTTPMethod("OPTIONS")}} request, using three HTTP request headers: {{HTTPHeader("Access-Control-Request-Method")}}, {{HTTPHeader("Access-Control-Request-Headers")}}, and the {{HTTPHeader("Origin")}} header.
+It is an {{HTTPMethod("OPTIONS")}} request, using two or three HTTP request headers: {{HTTPHeader("Access-Control-Request-Method")}}, {{HTTPHeader("Origin")}}, and optionally {{HTTPHeader("Access-Control-Request-Headers")}}.
 
 A preflight request is automatically issued by a browser and in normal cases, front-end developers don't need to craft such requests themselves. It appears when request is qualified as ["to be preflighted"](/en-US/docs/Web/HTTP/CORS#preflighted_requests) and omitted for [simple requests](/en-US/docs/Web/HTTP/CORS#simple_requests).
 

files/en-us/glossary/reflow/index.md

@@ -6,8 +6,10 @@ page-type: glossary-definition
 
 {{GlossarySidebar}}
 
-**Reflow** happens when a {{glossary("browser")}} must process and draw part or all of a webpage again, such as after an update on an interactive site.
+**Reflow** happens when a {{glossary("browser")}} recalculates the position and geometry of certain parts of a webpage, such as after an update on an interactive site. This tends to be followed by repainting, which is when the browser redraws the webpage to show the resulting visual updates.
 
 ## See also
 
-- [Google article "Minimizing browser reflow"](https://developers.google.com/speed/docs/insights/browser-reflow)
+- [Repaint](/en-US/docs/Glossary/Repaint)
+- [Minimizing browser reflow](https://developer.google.com/speed/docs/insights/browser-reflow) on developer.google.com
+- [Understanding Reflow and Repaint in the browser](https://dev.to/gopal1996/understanding-reflow-and-repaint-in-the-browser-1jbg) on dev.to (2020)

files/en-us/glossary/render_blocking/index.md

@@ -0,0 +1,17 @@
+---
+title: Render-blocking
+slug: Glossary/Render_blocking
+page-type: glossary-definition
+---
+
+{{GlossarySidebar}}
+
+**Render-blocking** refers to any part of the process of loading a website when it blocks the rendering of the user interface. Render-blocking is bad for web performance because it increases the length of time until users can interact with the site — for example viewing content or interacting with controls.
+
+The most common causes of render-blocking are initially-loaded CSS or JavaScript files.
+
+## See also
+
+- [CSS performance optimization](/en-US/docs/Learn/Performance/CSS)
+- [JavaScript performance optimization](/en-US/docs/Learn/Performance/JavaScript)
+- [What Are Render-Blocking Resources & How to Fix Render Blocking Issues](https://speckyboy.com/render-blocking/) on Speckyboy (2018)

files/en-us/glossary/repaint/index.md

@@ -0,0 +1,14 @@
+---
+title: Repaint
+slug: Glossary/Repaint
+page-type: glossary-definition
+---
+
+{{GlossarySidebar}}
+
+**Repaint** happens when a {{glossary("browser")}} redraws a web page to show the visual updates resulting from a UI change, such as after an update on an interactive site. This usually follows reflowing, which is when the browser recalculates the position and geometry of certain parts of a web page.
+
+## See also
+
+- [Reflow](/en-US/docs/Glossary/Reflow)
+- [Understanding Reflow and Repaint in the browser](https://dev.to/gopal1996/understanding-reflow-and-repaint-in-the-browser-1jbg) on dev.to (2020)

files/en-us/learn/common_questions/web_mechanics/how_does_the_internet_work/index.md

@@ -81,7 +81,7 @@ So we are connected to the telephone infrastructure. The next step is to send th
 
 ### Finding computers
 
-If you want to send a message to a computer, you have to specify which one. Thus any computer linked to a network has a unique address that identifies it, called an "IP address" (where IP stands for _Internet Protocol_). It's an address made of a series of four numbers separated by dots, for example: `192.168.2.10`.
+If you want to send a message to a computer, you have to specify which one. Thus any computer linked to a network has a unique address that identifies it, called an "IP address" (where IP stands for _Internet Protocol_). It's an address made of a series of four numbers separated by dots, for example: `192.0.2.172`.
 
 That's perfectly fine for computers, but we human beings have a hard time remembering that sort of address. To make things easier, we can alias an IP address with a human-readable name called a _domain name_. For example (at the time of writing; IP addresses can change) `google.com` is the domain name used on top of the IP address `142.250.190.78`. So using the domain name is the easiest way for us to reach a computer over the Internet.
 

files/en-us/learn/common_questions/web_mechanics/what_is_a_domain_name/index.md

@@ -34,7 +34,7 @@ page-type: learn-faq
 
 Domain names are a key part of the Internet infrastructure. They provide a human-readable address for any web server available on the Internet.
 
-Any Internet-connected computer can be reached through a public {{Glossary("IP Address")}}, either an IPv4 address (e.g. `173.194.121.32`) or an IPv6 address (e.g., `2027:0da8:8b73:0000:0000:8a2e:0370:1337`).
+Any Internet-connected computer can be reached through a public {{Glossary("IP Address")}}, either an IPv4 address (e.g. `192.0.2.172`) or an IPv6 address (e.g., `2001:db8:8b73:0000:0000:8a2e:0370:1337`).
 
 Computers can handle such addresses easily, but people have a hard time finding out who is running the server or what service the website offers. IP addresses are hard to remember and might change over time.
 

files/en-us/learn/css/building_blocks/selectors/index.md

@@ -175,6 +175,6 @@ article > p {
 
 In this article we've introduced CSS selectors, which enable you to target particular HTML elements. Next, we'll take a closer look at [type, class, and ID selectors](/en-US/docs/Learn/CSS/Building_blocks/Selectors/Type_Class_and_ID_Selectors).
 
-For a complete list of selectors, see our [CSS selectors reference](/en-US/docs/Web/CSS/CSS_Selectors).
+For a complete list of selectors, see our [CSS selectors reference](/en-US/docs/Web/CSS/CSS_selectors).
 
 {{NextMenu("Learn/CSS/Building_blocks/Selectors/Type_Class_and_ID_Selectors", "Learn/CSS/Building_blocks")}}

files/en-us/learn/css/howto/css_faq/index.md

@@ -17,7 +17,7 @@ Modern browsers have two main rendering modes:
 - _Quirks Mode_: also called backwards-compatibility mode, allows legacy webpages to be rendered as their authors intended, following the non-standard rendering rules used by older browsers. Documents with an incomplete, incorrect, or missing `DOCTYPE` declaration or a known `DOCTYPE` declaration in common use before 2001 will be rendered in Quirks Mode.
 - _Standards Mode_: the browser attempts to follow the W3C standards strictly. New HTML pages are expected to be designed for standards-compliant browsers, and as a result, pages with a modern `DOCTYPE` declaration will be rendered with Standards Mode.
 
-Gecko-based browsers, have a third _[Almost Standards Mode](/en-US/docs/Mozilla/Gecko_Almost_Standards_Mode)_ that has only a few minor quirks.
+Gecko-based browsers have a third [limited quirks mode](https://en.wikipedia.org/wiki/Quirks_mode#Limited_quirks_mode) that has only a few minor quirks.
 
 The standard `DOCTYPE` declaration that will trigger standards mode is:
 

files/en-us/learn/css/howto/highlight_first_line/index.md

@@ -24,10 +24,12 @@ In this case we need to use the {{cssxref("::first-line")}} pseudo-element. It s
 
 ## Combining pseudo-elements with other selectors
 
-In the example above, the pseudo-element selects the first line of every paragraph. To select only the first line of the first paragraph, you can combine it with another selector. That could be a class, or in this case the {{cssxref(":first-child")}} {{cssxref("pseudo-classes", "pseudo-class")}}. This allows us to select the first line of the first-child of `.wrapper`.
+In the example above, the pseudo-element selects the first line of every paragraph. To select only the first line of the first paragraph, you can combine it with another selector. In this case, we use the {{cssxref(":first-child")}} {{cssxref("pseudo-classes", "pseudo-class")}}. This allows us to select the first line of the first child of `.wrapper` if that first child is a paragraph.
 
 {{EmbedGHLiveSample("css-examples/howto/highlight_first_line2.html", '100%', 700)}}
 
+> **Note:** When combining pseudo-elements with other selectors in a [complex](/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#complex_selector) or [compound](/en-US/docs/Web/CSS/CSS_selectors/Selector_structure#compound_selector) selector, the pseudo-elements must appear after all the other components in the selector in which they appear.
+
 ## See also
 
 - The {{cssxref("pseudo-elements", "pseudo-elements")}} reference page.

files/en-us/learn/css/howto/highlight_para_after_h1/index.md

@@ -14,7 +14,7 @@ A common pattern is to style the first paragraph in an article differently to th
 
 ## The adjacent sibling combinator
 
-CSS has a group of [CSS Selectors](/en-US/docs/Web/CSS/CSS_Selectors) which are referred to as **combinators**, because they select things based on a combination of selectors. In our case, we will use the [adjacent sibling combinator](/en-US/docs/Web/CSS/Adjacent_sibling_combinator). This combinator selects an element based on it being next to another element. In our HTML we have a {{htmlelement("Heading_Elements", "h1")}} followed by a {{htmlelement("p")}}. The `<p>` is an adjacent sibling of the `<h1>` so we can select it with `h1 + p`.
+CSS has a group of [CSS Selectors](/en-US/docs/Web/CSS/CSS_selectors) which are referred to as **combinators**, because they select things based on a combination of selectors. In our case, we will use the [adjacent sibling combinator](/en-US/docs/Web/CSS/Adjacent_sibling_combinator). This combinator selects an element based on it being next to another element. In our HTML we have a {{htmlelement("Heading_Elements", "h1")}} followed by a {{htmlelement("p")}}. The `<p>` is an adjacent sibling of the `<h1>` so we can select it with `h1 + p`.
 
 {{EmbedGHLiveSample("css-examples/howto/highlight_h1_plus_para.html", '100%', 800)}}
 

files/en-us/learn/forms/how_to_build_custom_form_controls/example_1/index.md

@@ -84,7 +84,7 @@ This is the first example of code that explains [how to build a custom form widg
   vertical-align: top;
 }
 
-.select:after {
+.select::after {
   content: "▼";
   position: absolute;
   z-index: 1;
@@ -220,7 +220,7 @@ This is the first example of code that explains [how to build a custom form widg
   vertical-align: top;
 }
 
-.select:after {
+.select::after {
   content: "▼";
   position: absolute;
   z-index: 1;
@@ -356,7 +356,7 @@ This is the first example of code that explains [how to build a custom form widg
   vertical-align: top;
 }
 
-.select:after {
+.select::after {
   content: "▼";
   position: absolute;
   z-index: 1;

files/en-us/learn/forms/how_to_build_custom_form_controls/example_2/index.md

@@ -102,7 +102,7 @@ This is the second example that explain [how to build custom form widgets](/en-U
   vertical-align: top;
 }
 
-.select:after {
+.select::after {
   content: "▼";
   position: absolute;
   z-index: 1;