Merge branch 'main' into document-all

.github/labeler.yml

@@ -1,3 +1,15 @@
+system:
+  - package.json
+  - yarn.lock
+  - .github/**/*
+  - .husky/**/*
+  - .vscode/**/*
+  - .*
+  - scripts/**/*
+  - tests/**/*
+  - jest.config.json
+  - front-matter-config.json
+
 Content:Accessibility:
   - files/en-us/web/accessibility/**/*
 Content:CSS:

.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,
-    // Pending https://github.com/mdn/content/pull/20115
-    "MD037": false,
-    "MD040": false,
+    "no-bare-urls": false,
+    // Produces too many false positives
+    "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

@@ -380,7 +380,7 @@
 /en-US/docs/CSS/:-moz-broken	/en-US/docs/Web/CSS/:-moz-broken
 /en-US/docs/CSS/:-moz-drag-over	/en-US/docs/Web/CSS/:-moz-drag-over
 /en-US/docs/CSS/:-moz-first-node	/en-US/docs/Web/CSS/:-moz-first-node
-/en-US/docs/CSS/:-moz-focusring	/en-US/docs/Web/CSS/:-moz-focusring
+/en-US/docs/CSS/:-moz-focusring	/en-US/docs/Web/CSS/:focus-visible
 /en-US/docs/CSS/:-moz-full-screen	/en-US/docs/Web/CSS/:fullscreen
 /en-US/docs/CSS/:-moz-handler-blocked	/en-US/docs/Web/CSS/:-moz-handler-blocked
 /en-US/docs/CSS/:-moz-handler-crashed	/en-US/docs/Web/CSS/:-moz-handler-crashed
@@ -2084,7 +2084,6 @@
 /en-US/docs/DOM/window.URL.createObjectURL	/en-US/docs/Web/API/URL/createObjectURL_static
 /en-US/docs/DOM/window.URL.revokeObjectURL	/en-US/docs/Web/API/URL/revokeObjectURL_static
 /en-US/docs/DOM/window.alert	/en-US/docs/Web/API/Window/alert
-/en-US/docs/DOM/window.applicationCache	/en-US/docs/Web/API/Window/applicationCache
 /en-US/docs/DOM/window.atob	/en-US/docs/Web/API/atob
 /en-US/docs/DOM/window.back	/en-US/docs/Web/API/Window/back
 /en-US/docs/DOM/window.blur	/en-US/docs/Web/API/Window/blur
@@ -2549,7 +2548,6 @@
 /en-US/docs/DOM:treeWalker.whatToShow	/en-US/docs/Web/API/TreeWalker/whatToShow
 /en-US/docs/DOM:window	/en-US/docs/Web/API/Window
 /en-US/docs/DOM:window.alert	/en-US/docs/Web/API/Window/alert
-/en-US/docs/DOM:window.applicationCache	/en-US/docs/Web/API/Window/applicationCache
 /en-US/docs/DOM:window.atob	/en-US/docs/Web/API/atob
 /en-US/docs/DOM:window.back	/en-US/docs/Web/API/Window/back
 /en-US/docs/DOM:window.blur	/en-US/docs/Web/API/Window/blur
@@ -3268,7 +3266,6 @@
 /en-US/docs/Document_Object_Model_(DOM)/window.URL	/en-US/docs/Web/API/URL
 /en-US/docs/Document_Object_Model_(DOM)/window.URL.createObjectURL	/en-US/docs/Web/API/URL/createObjectURL_static
 /en-US/docs/Document_Object_Model_(DOM)/window.URL.revokeObjectURL	/en-US/docs/Web/API/URL/revokeObjectURL_static
-/en-US/docs/Document_Object_Model_(DOM)/window.applicationCache	/en-US/docs/Web/API/Window/applicationCache
 /en-US/docs/Document_Object_Model_(DOM)/window.captureEvents	/en-US/docs/Web/API/Window/captureEvents
 /en-US/docs/Document_Object_Model_(DOM)/window.clearImmediate	/en-US/docs/Web/API/Window/clearImmediate
 /en-US/docs/Document_Object_Model_(DOM)/window.clearInterval	/en-US/docs/Web/API/clearInterval
@@ -9619,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
@@ -10243,7 +10240,7 @@
 /en-US/docs/Web/API/WorkerConsole.info()	/en-US/docs/Web/API/console/info
 /en-US/docs/Web/API/WorkerConsole.log	/en-US/docs/Web/API/console/log
 /en-US/docs/Web/API/WorkerGlobalScope.close	/en-US/docs/Web/API/DedicatedWorkerGlobalScope/close
-/en-US/docs/Web/API/WorkerGlobalScope.console	/en-US/docs/Web/API/WorkerGlobalScope/console
+/en-US/docs/Web/API/WorkerGlobalScope.console	/en-US/docs/Web/API/console
 /en-US/docs/Web/API/WorkerGlobalScope.dump	/en-US/docs/Web/API/WorkerGlobalScope/dump
 /en-US/docs/Web/API/WorkerGlobalScope.importScripts	/en-US/docs/Web/API/WorkerGlobalScope/importScripts
 /en-US/docs/Web/API/WorkerGlobalScope.location	/en-US/docs/Web/API/WorkerGlobalScope/location
@@ -10262,6 +10259,7 @@
 /en-US/docs/Web/API/WorkerGlobalScope/clearInterval	/en-US/docs/Web/API/clearInterval
 /en-US/docs/Web/API/WorkerGlobalScope/clearTimeout	/en-US/docs/Web/API/clearTimeout
 /en-US/docs/Web/API/WorkerGlobalScope/close	/en-US/docs/Web/API/DedicatedWorkerGlobalScope/close
+/en-US/docs/Web/API/WorkerGlobalScope/console	/en-US/docs/Web/API/console
 /en-US/docs/Web/API/WorkerGlobalScope/fetch	/en-US/docs/Web/API/fetch
 /en-US/docs/Web/API/WorkerGlobalScope/indexedDB	/en-US/docs/Web/API/indexedDB
 /en-US/docs/Web/API/WorkerGlobalScope/onclose	/en-US/docs/Web/API/DedicatedWorkerGlobalScope/close
@@ -10693,7 +10691,6 @@
 /en-US/docs/Web/API/window.URL.createObjectURL	/en-US/docs/Web/API/URL/createObjectURL_static
 /en-US/docs/Web/API/window.URL.revokeObjectURL	/en-US/docs/Web/API/URL/revokeObjectURL_static
 /en-US/docs/Web/API/window.alert	/en-US/docs/Web/API/Window/alert
-/en-US/docs/Web/API/window.applicationCache	/en-US/docs/Web/API/Window/applicationCache
 /en-US/docs/Web/API/window.atob	/en-US/docs/Web/API/atob
 /en-US/docs/Web/API/window.back	/en-US/docs/Web/API/Window/back
 /en-US/docs/Web/API/window.blur	/en-US/docs/Web/API/Window/blur
@@ -11253,6 +11250,7 @@
 /en-US/docs/Web/CSS/-webkit-user-select	/en-US/docs/Web/CSS/user-select
 /en-US/docs/Web/CSS/:-moz-any	/en-US/docs/Web/CSS/:is
 /en-US/docs/Web/CSS/:-moz-any-link	/en-US/docs/Web/CSS/:any-link
+/en-US/docs/Web/CSS/:-moz-focusring	/en-US/docs/Web/CSS/:focus-visible
 /en-US/docs/Web/CSS/:-moz-full-screen	/en-US/docs/Web/CSS/:fullscreen
 /en-US/docs/Web/CSS/:-moz-list-bullet	/en-US/docs/Web/CSS/::-moz-list-bullet
 /en-US/docs/Web/CSS/:-moz-list-number	/en-US/docs/Web/CSS/::-moz-list-number

files/en-us/_wikihistory.json

@@ -66684,25 +66684,6 @@
       "teoli"
     ]
   },
-  "Web/API/Window/applicationCache": {
-    "modified": "2020-12-08T02:25:04.101Z",
-    "contributors": [
-      "sideshowbarker",
-      "schalkneethling",
-      "placecarleen44",
-      "bershanskiy",
-      "alattalatta",
-      "chrisdavidmills",
-      "Sheppy",
-      "fscholz",
-      "teoli",
-      "ethertank",
-      "Jeremie",
-      "ebidel",
-      "Mgjbot",
-      "Kohei"
-    ]
-  },
   "Web/API/Window/back": {
     "modified": "2020-02-23T02:06:28.448Z",
     "contributors": [
@@ -69540,17 +69521,6 @@
       "teoli"
     ]
   },
-  "Web/API/WorkerGlobalScope/console": {
-    "modified": "2020-10-15T21:32:18.184Z",
-    "contributors": [
-      "sideshowbarker",
-      "fscholz",
-      "valentin.gosu",
-      "teoli",
-      "chrisdavidmills",
-      "kscarfone"
-    ]
-  },
   "Web/API/WorkerGlobalScope/dump": {
     "modified": "2020-10-15T21:32:18.913Z",
     "contributors": [
@@ -73733,23 +73703,6 @@
       "Mw22"
     ]
   },
-  "Web/CSS/:-moz-focusring": {
-    "modified": "2020-12-01T16:39:52.169Z",
-    "contributors": [
-      "mfluehr",
-      "cpmsmith",
-      "wbamberg",
-      "fscholz",
-      "chrisdavidmills",
-      "elharony",
-      "Enn2",
-      "Sebastianz",
-      "teoli",
-      "seth",
-      "Jonathan_Watt",
-      "Sheppy"
-    ]
-  },
   "Web/CSS/:-moz-handler-blocked": {
     "modified": "2020-08-06T11:19:00.766Z",
     "contributors": ["Sheppy", "wbamberg", "mfluehr", "teoli"]

files/en-us/games/introduction/index.md

@@ -111,7 +111,7 @@ For the tech folks, let's dig into the APIs the Web brings to the table that cat
   - : The Pointer Lock API lets you lock the mouse or other pointing device within your game's interface so that instead of absolute cursor positioning you receive coordinate deltas that give you more precise measurements of what the user is doing, and prevent the user from accidentally sending their input somewhere else, thereby missing important action.
 - [SVG](/en-US/docs/Web/SVG) (Scalable Vector Graphics)
   - : Lets you build vector graphics that scale smoothly regardless of the size or resolution of the user's display.
-- [Typed Arrays](/en-US/docs/Web/JavaScript/Typed_arrays)
+- [Typed Arrays](/en-US/docs/Web/JavaScript/Guide/Typed_arrays)
   - : JavaScript typed arrays give you access to raw binary data from within JavaScript; this lets you manipulate GL textures, game data, or anything else, even if it's not in a native JavaScript format.
 - [Web Audio API](/en-US/docs/Web/API/Web_Audio_API)
   - : This API for controlling the playback, synthesis, and manipulation of audio from JavaScript code lets you create awesome sound effects as well as play and manipulate music in real time.

files/en-us/games/introduction_to_html5_game_development/index.md

@@ -102,7 +102,7 @@ page-type: guide
   - : Lock the mouse or other pointing device within your game's interface.
 - [SVG](/en-US/docs/Web/SVG) (Scalable Vector Graphics)
   - : Build vector graphics that scale smoothly regardless of the size or resolution of the user's display.
-- [Typed Arrays](/en-US/docs/Web/JavaScript/Typed_arrays)
+- [Typed Arrays](/en-US/docs/Web/JavaScript/Guide/Typed_arrays)
   - : Access raw binary data from within JavaScript; Manipulate GL textures, game data, or anything else.
 - [Web Audio API](/en-US/docs/Web/API/Web_Audio_API)
   - : Control the playback, synthesis, and manipulation of audio in real time.

files/en-us/games/techniques/audio_for_web_games/index.md

@@ -19,7 +19,7 @@ Browser autoplay policy now affects desktop _and_ mobile browsers. There is furt
 It is worth noting that autoplay with sound is allowed if:
 
 - the User has interacted with the domain.
-- on mobile the user has [added the site to their home screen](/en-US/docs/Web/Progressive_web_apps/Add_to_home_screen).
+- on mobile the user has [made the application installable](/en-US/docs/Web/Progressive_web_apps/Guides/Making_PWAs_installable).
 
 Many browsers will ignore any requests made by your game to automatically play audio; instead playback for audio needs to be started by a user-initiated event, such as a click or tap. This means you will have to structure your audio playback to take account of that. This is usually mitigated against by loading the audio in advance and priming it on a user-initiated event.
 
@@ -131,7 +131,7 @@ Although mobile browsers can present problems, there are ways to work around the
 
 ### Audio sprites
 
-Audio sprites borrow their name from [CSS sprites](/en-US/docs/Web/CSS/CSS_Images/Implementing_image_sprites_in_CSS), which is a visual technique for using CSS with a single graphic resource to break it into a series of sprites. We can apply the same principle to audio so that rather than having a bunch of small audio files that take time to load and play, we have one larger audio file containing all the smaller audio snippets we need. To play a specific sound from the file, we just use the known start and stop times for each audio sprite.
+Audio sprites borrow their name from [CSS sprites](/en-US/docs/Web/CSS/CSS_images/Implementing_image_sprites_in_CSS), which is a visual technique for using CSS with a single graphic resource to break it into a series of sprites. We can apply the same principle to audio so that rather than having a bunch of small audio files that take time to load and play, we have one larger audio file containing all the smaller audio snippets we need. To play a specific sound from the file, we just use the known start and stop times for each audio sprite.
 
 The advantage is that we can prime one piece of audio and have our sprites ready to go. To do this we can just play and instantly pause the larger piece of audio. You'll also reduce the number of server requests and save bandwidth.
 

files/en-us/games/techniques/tilemaps/square_tilemaps_implementation_colon__scrolling_maps/index.md

@@ -1,6 +1,7 @@
 ---
 title: "Square tilemaps implementation: Scrolling maps"
 slug: Games/Techniques/Tilemaps/Square_tilemaps_implementation:_Scrolling_maps
+page-type: guide
 ---
 
 {{GamesSidebar}}

files/en-us/games/techniques/tilemaps/square_tilemaps_implementation_colon__static_maps/index.md

@@ -1,6 +1,7 @@
 ---
 title: "Square tilemaps implementation: Static maps"
 slug: Games/Techniques/Tilemaps/Square_tilemaps_implementation:_Static_maps
+page-type: guide
 ---
 
 {{GamesSidebar}}

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

@@ -1,6 +1,7 @@
 ---
 title: Adobe Flash
 slug: Glossary/Adobe_Flash
+page-type: glossary-definition
 ---
 
 {{GlossarySidebar}}

files/en-us/glossary/baseline/compatibility/index.md

@@ -1,6 +1,7 @@
 ---
 title: Baseline (compatibility)
 slug: Glossary/Baseline/Compatibility
+page-type: glossary-definition
 ---
 
 {{GlossarySidebar}}