Merge branch 'main' into shadowroot

.github/workflows/pr-review-companion.yml

@@ -7,7 +7,7 @@ name: PR review companion
 
 on:
   workflow_run:
-    workflows: ["PR Test"]
+    workflows: ["PR Test", "PR Test - new CI"]
     types:
       - completed
 

.github/workflows/pr-test-new-ci.yml

@@ -0,0 +1,141 @@
+# This file tests more or less everything related to a pull request. All
+# in one big job. At the end, if all the testing passes, it proceeds
+# to upload all the files that were built to our Dev environment.
+# This way, if the tests passed, you'll be able to review the built
+# pages on a public URL.
+
+name: PR Test - new CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  tests:
+    if: github.repository == 'mdn/content' && startsWith(github.event.pull_request.title, '[new-ci]')
+    runs-on: ubuntu-latest
+    # Set the permissions to `read-all`, preventing the workflow from
+    # any accidental write access to the repository.
+    permissions: read-all
+    env:
+      BASE_SHA: ${{ github.event.pull_request.base.sha }}
+      HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      # This is the directory where the built files will be placed.
+      # It's also hardcoded in the `yarn build` command in package.json.
+      # If you change it here, you must also make the same change in
+      # package.json.
+      BUILD_OUT_ROOT: build
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get changed files
+        run: |
+          # Use the GitHub API to get the list of changed files
+          # documentation: https://docs.github.com/rest/commits/commits#compare-two-commits
+          DIFF_DOCUMENTS=$(gh api repos/{owner}/{repo}/compare/${BASE_SHA}...${HEAD_SHA} \
+            --jq '.files | .[] | select(.status|IN("added", "modified", "renamed", "copied", "changed")) | .filename')
+
+          # filter out files that are not markdown files
+          GIT_DIFF_CONTENT=$(echo "${DIFF_DOCUMENTS}" | egrep -i "^files/.*\.(md)$" | xargs)
+          echo "GIT_DIFF_CONTENT=${GIT_DIFF_CONTENT}" >> $GITHUB_ENV
+
+          # filter out files that are not attachments
+          GIT_DIFF_FILES=$(echo "${DIFF_DOCUMENTS}" | egrep -i "^files/.*\.(png|jpeg|jpg|gif|svg|webp)$" | xargs)
+          echo "GIT_DIFF_FILES=${GIT_DIFF_FILES}" >> $GITHUB_ENV
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js environment
+        if: ${{ env.GIT_DIFF_CONTENT }} || ${{ env.GIT_DIFF_FILES }}
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".nvmrc"
+          cache: yarn
+
+      - name: Install all yarn packages
+        if: ${{ env.GIT_DIFF_CONTENT }} || ${{ env.GIT_DIFF_FILES }}
+        run: yarn --frozen-lockfile
+        env:
+          # https://github.com/microsoft/vscode-ripgrep#github-api-limit-note
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build changed content
+        id: build-content
+        if: ${{ env.GIT_DIFF_CONTENT }}
+        env:
+          CONTENT_ROOT: ${{ github.workspace }}/files
+
+          # This is so that if there's a single 'unsafe_html' flaw, it
+          # completely fails the build.
+          # But all other flaws should be 'warn', so that we can include
+          # information about the flaws when we analyze the built PR.
+          BUILD_FLAW_LEVELS: "unsafe_html: error, *:warn"
+
+          # Because we build these pages in a way that you get a toolbar,
+          # so the flaws can be displayed, but we don't want any of the
+          # other toolbar features like "Fix fixable flaws" or "Quick-edit"
+          # we set this to disable that stuff.
+          REACT_APP_CRUD_MODE_READONLY: true
+
+          BUILD_LIVE_SAMPLES_BASE_URL: https://live.mdnyalp.dev
+          BUILD_LEGACY_LIVE_SAMPLES_BASE_URL: https://live-samples.mdn.allizom.net
+
+          # In these builds, we never care for or need the ability to sign in.
+          # This environment variable will disable that functionality entirely.
+          REACT_APP_DISABLE_AUTH: true
+
+          # TODO: This should be implicit when `CI=true`
+          BUILD_NO_PROGRESSBAR: true
+
+          # Playground
+          REACT_APP_PLAYGROUND_BASE_HOST: mdnyalp.dev
+
+          # rari
+          LIVE_SAMPLES_BASE_URL: https://live.mdnyalp.dev
+          INTERACTIVE_EXAMPLES_BASE_URL: https://interactive-examples.mdn.allizom.net
+
+        run: |
+          # The reason this script isn't in `package.json` is because
+          # you don't need that script as a writer. It's only used in CI
+          # and it can't use the default CONTENT_ROOT that gets set in
+          # package.json.
+          echo Y|yarn rari update
+          ARGS=$(echo $GIT_DIFF_CONTENT | sed -E -e "s#(^| )files#\1-f $PWD/files#g")
+          yarn rari build --no-basic --json-issues --data-issues $ARGS
+          yarn yari-render-html
+
+          echo "Disk usage size of the build"
+          du -sh $BUILD_OUT_ROOT
+
+          # Save the PR number into the build
+          echo ${{ github.event.number }} > ${BUILD_OUT_ROOT}/NR
+
+          # Download the raw diff blob and store that inside the build
+          # directory.
+          # The purpose of this is for the PR Review Companion to later
+          # be able to use this raw diff file for the benefit of analyzing.
+          wget https://github.com/${{ github.repository }}/compare/${BASE_SHA}...${HEAD_SHA}.diff -O ${BUILD_OUT_ROOT}/DIFF
+
+      - name: Merge static assets with built documents
+        if: ${{ env.GIT_DIFF_CONTENT }}
+        run: |
+          # Exclude the .map files, as they're used for debugging JS and CSS.
+          rsync -a --exclude "*.map" node_modules/@mdn/yari/client/build/ $BUILD_OUT_ROOT
+          # Show the final disk usage size of the build.
+          du -sh $BUILD_OUT_ROOT
+
+      - uses: actions/upload-artifact@v4
+        if: ${{ env.GIT_DIFF_CONTENT }}
+        with:
+          name: build
+          path: ${{ env.BUILD_OUT_ROOT }}
+
+      - name: Check changed files
+        if: ${{ env.GIT_DIFF_FILES }}
+        run: |
+          echo $GIT_DIFF_FILES
+
+          export CONTENT_ROOT=$(pwd)/files
+          yarn filecheck $GIT_DIFF_FILES

.github/workflows/pr-test.yml

@@ -13,7 +13,7 @@ on:
 
 jobs:
   tests:
-    if: github.repository == 'mdn/content'
+    if: github.repository == 'mdn/content' && !startsWith(github.event.pull_request.title, '[new-ci]')
     runs-on: ubuntu-latest
     # Set the permissions to `read-all`, preventing the workflow from
     # any accidental write access to the repository.

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

@@ -6,7 +6,7 @@ page-type: glossary-definition
 
 {{GlossarySidebar}}
 
-An **aspect ratio** is the proportional relationship between an element or {{glossary("viewport")}}'s width and height, and is represented as a ratio or two numbers.
+An **aspect ratio** is the proportional relationship between an element or {{glossary("viewport")}}'s width and height. It is represented as a {{cssxref("ratio")}} of two numbers.
 
 Having an aspect ratio, whether it's an inherent aspect ratio like with images and videos or if it's extrinsically set, maintains the intended proportions of an element. You can also query an element or viewport's aspect, which is useful in developing flexible components and layouts.
 

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

@@ -6,7 +6,7 @@ page-type: glossary-definition
 
 {{GlossarySidebar}}
 
-An {{glossary("HTML")}} **character reference** is a formatted pattern of characters that is used to represent another character in the rendered web page.
+An {{glossary("HTML")}} **character reference** is an {{glossary("escape character", "escape sequence")}} of {{glossary("character", "characters")}} that is used to represent another character in the rendered web page.
 
 Character references are used as replacements for characters that are reserved in HTML, such as the less-than (`<`) and greater-than (`>`) symbols used by the HTML parser to identify element {{Glossary('tag','tags')}}, or `"` or `'` within attributes, which may be enclosed by those characters.
 They can also be used for invisible characters that would otherwise be impossible to type, including non-breaking spaces, control characters like left-to-right and right-to-left marks, and for characters that are hard to type on a standard keyboard.
@@ -21,7 +21,7 @@ There are three types of character references:
 
 - **Decimal numeric character references**
 
-  - : These references start with `&#`, followed by one or more ASCII digits representing the base-ten integer that corresponds to the character's Unicode code point, and ending with `;`.
+  - : These references start with `&#`, followed by one or more ASCII digits representing the base-ten integer that corresponds to the character's {{glossary("Unicode")}} {{glossary("code point")}}, and ending with `;`.
     For example, the decimal character reference for `<` is `&#60;`, because the Unicode code point for the symbol is `U+0003C`, and `3C` hexadecimal is 60 in decimal.
 
 - **Hexadecimal numeric character reference**
@@ -50,3 +50,11 @@ A very small subset of useful named character references along with their unicod
 | °         | `&deg;`         | U+000B0            |
 
 The full list of HTML named character references [can found in the HTML specification here](https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references).
+
+## See also
+
+- Related glossary terms:
+  - {{glossary("Character")}}
+  - {{glossary("Escape character")}}
+  - {{glossary("Code point")}}
+  - {{glossary("Unicode")}}

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

@@ -0,0 +1,23 @@
+---
+title: Escape character
+slug: Glossary/Escape_character
+page-type: glossary-definition
+---
+
+{{GlossarySidebar}}
+
+An **escape character** is a {{glossary("character")}} that causes one or more characters that follow it to be interpreted differently. This forms an **escape sequence**, which is often used to represent a character that has an alternative meaning when printed literally, such as the quote character in a string literal. Escape sequences can have other usages too, especially in [regular expressions](/en-US/docs/Web/JavaScript/Reference/Regular_expressions#escape_sequences).
+
+- In JavaScript [regexes](/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Character_escape), [string literals](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#string_literals), and [identifiers](/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#identifiers), we can use the backslash (`\`) to escape characters like `\'`, `\"`, `\u0026`, etc.
+- In CSS identifiers, we can use the backslash (`\`) to escape characters like `\\`, `\n`, `\26`, etc. See [escape characters](/en-US/docs/Web/CSS/ident#escaping_characters) for more information.
+- In HTML text content and attribute values, we can use {{glossary("character reference", "character references")}} like `<`, `<`, or `<`.
+- In {{glossary("URL", "URLs")}}, we can use the percent sign (`%`) to escape characters like `%20`, `%3C`, `%3E`, etc.
+
+## See also
+
+- Related glossary terms:
+  - {{glossary("Character")}}
+  - {{glossary("Character reference")}}
+  - {{glossary("Code point")}}
+- [Escape character](https://en.wikipedia.org/wiki/Escape_character) on Wikipedia
+- [Escape sequence](https://en.wikipedia.org/wiki/Escape_sequence) on Wikipedia

files/en-us/learn_web_development/core/structuring_content/index.md

@@ -71,7 +71,7 @@ These tutorials are not part of the learning pathway, but they are interesting n
   - : [Scrimba's](https://scrimba.com?via=mdn) _Learn HTML and CSS_ course teaches you HTML and CSS through building and deploying five awesome projects, with fun interactive lessons and challenges taught by knowledgeable teachers.
 - [The basics of semantic HTML](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~0xid?via=mdn), Scrimba <sup>_MDN Curriculum partner_</sup>
   - : This interactive lesson provides a useful description of HTML, with particular emphasis on why the _semantic_ aspect of it is important.
-- [Learn HTML](https://v2.scrimba.com/the-frontend-developer-career-path-c0j/~0xid?via=mdn), Codecademy
+- [Learn HTML](https://www.codecademy.com/learn/learn-html), Codecademy
   - : Another useful (and free resource) for learning HTML basics.
 
 {{NextMenu("Learn_web_development/Core/Structuring_content/Basic_HTML_syntax", "Learn_web_development/Core")}}

files/en-us/web/api/dommatrix/index.md

@@ -51,7 +51,7 @@ _This interface includes the following methods, as well as the methods it inheri
 - {{domxref("DOMMatrix.multiplySelf()")}}
   - : Modifies the matrix by post-multiplying it with the specified `DOMMatrix`. This is equivalent to the dot product `A⋅B`, where matrix `A` is the source matrix and `B` is the matrix given as an input to the method. Returns itself.
 - {{domxref("DOMMatrix.preMultiplySelf()")}}
-  - : Modifies the matrix by pre-multiplying it with the specified `DOMMatrix`. This is equivalent to the dot product `B⋅A`, where matrix `A` is the source matrix and `B` is the matrix given as an input to the method. Returns itself.
+  - : Modifies the matrix by pre-multiplying it with the specified `DOMMatrix`. Returns itself.
 - {{domxref("DOMMatrix.translateSelf()")}}
   - : Modifies the matrix by applying the specified vector. The default vector is `[0, 0, 0]`. Returns itself.
 - {{domxref("DOMMatrix.scaleSelf()")}}

files/en-us/web/api/dommatrix/multiplyself/index.md

@@ -0,0 +1,58 @@
+---
+title: "DOMMatrix: multiplySelf() method"
+short-title: multiplySelf()
+slug: Web/API/DOMMatrix/multiplySelf
+page-type: web-api-instance-method
+browser-compat: api.DOMMatrix.multiplySelf
+---
+
+{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
+
+The **`multiplySelf()`** method of the {{domxref("DOMMatrix")}} interface multiplies a matrix by the `otherMatrix` parameter, computing the dot product of the original matrix and the specified matrix: `A⋅B`. If no matrix is specified as the multiplier, the matrix is multiplied by a matrix in which every element is `0` _except_ the bottom-right corner and the element immediately above and to its left: `m33` and `m34`. These have the default value of `1`.
+
+To multiply a matrix without mutating it, see {{domxref("DOMMatrixReadOnly.multiply()")}}.
+
+## Syntax
+
+```js-nolint
+  DOMMatrix.multiplySelf()
+  DOMMatrix.multiplySelf(otherMatrix)
+```
+
+### Parameters
+
+- `otherMatrix` {{optional_inline}}
+  - : The [`DOMMatrix`](/en-US/docs/Web/API/DOMMatrix) multiplier.
+
+### Return value
+
+Returns itself; the [`DOMMatrix`](/en-US/docs/Web/API/DOMMatrix) updated to the results of the applied multiplications.
+
+## Examples
+
+```js
+const matrix = new DOMMatrix().rotate(30);
+
+console.log(matrix.toString());
+// output: matrix(0.866, 0.5, -0.5, 0.866, 0, 0)
+
+matrix.multiplySelf(matrix);
+
+console.log(matrix.toString());
+// output: matrix(0.5, 0.866, -0.866, 0.5, 0, 0) (a 60deg rotation)
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("DOMMatrixReadOnly.multiply()")}}
+- {{domxref("DOMMatrix.preMultiplySelf()")}}
+- CSS {{CSSxRef("transform-function/matrix", "matrix()")}} function
+- CSS {{CSSxRef("transform-function/matrix3d", "matrix3d()")}} function

files/en-us/web/api/dommatrix/premultiplyself/index.md

@@ -0,0 +1,57 @@
+---
+title: "DOMMatrix: preMultiplySelf() method"
+short-title: preMultiplySelf()
+slug: Web/API/DOMMatrix/preMultiplySelf
+page-type: web-api-instance-method
+browser-compat: api.DOMMatrix.preMultiplySelf
+---
+
+{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
+
+The **`preMultiplySelf()`** method of the {{domxref("DOMMatrix")}} interface modifies the matrix by pre-multiplying it with the specified `DOMMatrix`. This is equivalent to the dot product `B⋅A`, where matrix `A` is the source matrix and `B` is the matrix given as an input to the method. If no matrix is specified as the multiplier, the matrix is multiplied by a matrix in which every element is `0` _except_ the bottom-right corner and the element immediately above and to its left: `m33` and `m34`. These have the default value of `1`.
+
+## Syntax
+
+```js-nolint
+  DOMMatrix.preMultiplySelf()
+  DOMMatrix.preMultiplySelf(otherMatrix)
+```
+
+### Parameters
+
+- `otherMatrix` {{optional_inline}}
+  - : The [`DOMMatrix`](/en-US/docs/Web/API/DOMMatrix) multiplier.
+
+### Return value
+
+Returns itself; a [`DOMMatrix`](/en-US/docs/Web/API/DOMMatrix) updated to results of the applied multiplications.
+
+## Examples
+
+```js
+const matrix = new DOMMatrix().translate(3, 22);
+const otherMatrix = new DOMMatrix().translateSelf(15, 45);
+
+console.log(matrix.toString()); // output: matrix(1, 0, 0, 1, 3, 22)
+console.log(otherMatrix.toString()); // output: matrix(1, 0, 0, 1, 15, 45)
+
+matrix.preMultiplySelf(otherMatrix);
+
+console.log(matrix.toString()); // output: matrix(1, 0, 0, 1, 18, 67)
+console.log(otherMatrix.toString()); // output: matrix(1, 0, 0, 1, 15, 45)
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("DOMMatrix.multiplySelf()")}}
+- {{domxref("DOMMatrixReadOnly.multiply()")}}
+- CSS {{CSSxRef("transform-function/matrix", "matrix()")}} function
+- CSS {{CSSxRef("transform-function/matrix3d", "matrix3d()")}} function