Merge branch 'main' into multiply

.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 $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/web/api/dommatrixreadonly/flipx/index.md

@@ -8,7 +8,7 @@ browser-compat: api.DOMMatrixReadOnly.flipX
 
 {{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
 
-The `flipX()` method of the {{domxref("DOMMatrixReadOnly")}} interface creates a new matrix being the result of the original matrix flipped about the x-axis.
+The **`flipX()`** method of the {{domxref("DOMMatrixReadOnly")}} interface creates a new matrix being the result of the original matrix flipped about the x-axis. This is equivalent to multiplying the matrix by `DOMMatrix(-1, 0, 0, 1, 0, 0)`. The original matrix is not modified.
 
 ## Syntax
 
@@ -18,16 +18,14 @@ The `flipX()` method of the {{domxref("DOMMatrixReadOnly")}} interface creates a
 
 ### Return value
 
-Returns a [`DOMMatrix`](/en-US/docs/Web/API/DOMMatrix) containing a new matrix being the result of the original matrix flipped about the x-axis, which is equivalent to multiplying the matrix by `DOMMatrix(-1, 0, 0, 1, 0, 0)`. The original matrix is not modified.
+Returns a [`DOMMatrix`](/en-US/docs/Web/API/DOMMatrix).
 
 ## Examples
 
 ### Inverting a triangle
 
 In this example, the SVG contains two paths in the shape of a triangle, both drawn to the same position. Note that the x co-ordinate of the viewBox attribute is negative, showing us content from both sides of the x-axis.
 
-The JavaScript first creates an identity matrix, then uses the `flipX()` method to create a new matrix, which is then applied to the blue triangle, inverting it across the x-axis. The red triangle is left in place.
-
 #### HTML
 
 ```html
@@ -39,6 +37,8 @@ The JavaScript first creates an identity matrix, then uses the `flipX()` method
 
 #### JavaScript
 
+The JavaScript first creates an identity matrix, then uses the `flipX()` method to create a new matrix, which is then applied to the blue triangle, inverting it across the x-axis. The red triangle is left in place.
+
 ```js
 const flipped = document.getElementById("flipped");
 const matrix = new DOMMatrixReadOnly();
@@ -57,3 +57,7 @@ flipped.setAttribute("transform", flippedMatrix.toString());
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{domxref("DOMMatrixReadOnly.flipY()")}}

files/en-us/web/api/dommatrixreadonly/flipy/index.md

@@ -0,0 +1,63 @@
+---
+title: "DOMMatrixReadOnly: flipY() method"
+short-title: flipY()
+slug: Web/API/DOMMatrixReadOnly/flipY
+page-type: web-api-instance-method
+browser-compat: api.DOMMatrixReadOnly.flipY
+---
+
+{{APIRef("Geometry Interfaces")}}{{AvailableInWorkers}}
+
+The **`flipY()`** method of the {{domxref("DOMMatrixReadOnly")}} interface creates a new matrix being the result of the original matrix flipped about the y-axis. This is equivalent to multiplying the matrix by `DOMMatrix(1, 0, 0, -1, 0, 0)`. The original matrix is not modified.
+
+## Syntax
+
+```js-nolint
+  DOMMatrixReadOnly.flipY()
+```
+
+### Return value
+
+A [`DOMMatrix`](/en-US/docs/Web/API/DOMMatrix).
+
+## Examples
+
+### Inverting a triangle
+
+In this example, the SVG contains two identical [paths](/en-US/docs/Web/SVG/Attribute/d) in the shape of a triangle; they are both drawn to have the same size and position. The viewbox has a negative y value showing us content from both sides of the y-axis. This enables the flipped triangle to be withing the viewport after it is transformed.
+
+#### HTML
+
+```html
+<svg height="200" width="100" viewBox="0 -100 100 200">
+  <path fill="red" d="M 0 0 L 100 0 L 50 100 Z" />
+  <path fill="blue" d="M 0 0 L 100 0 L 50 100 Z" id="flipped" />
+</svg>
+```
+
+#### JavaScript
+
+The JavaScript creates an [identity matrix](/en-US/docs/Web/API/DOMMatrixReadOnly/isIdentity), then uses the `flipY()` method to create a new matrix, which is then applied to the blue triangle, inverting it across the y-axis. The red triangle is left in place.
+
+```js
+const flipped = document.getElementById("flipped");
+const matrix = new DOMMatrix();
+const flippedMatrix = matrix.flipY();
+flipped.setAttribute("transform", flippedMatrix.toString());
+```
+
+#### Result
+
+{{EmbedLiveSample('Inverting a triangle', '', '240')}}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("DOMMatrixReadOnly.flipX()")}}

files/en-us/web/api/htmlimageelement/alt/index.md

@@ -128,17 +128,17 @@ In other words, it should be the same text you would use in a textual button to
 For example, in the snippet of HTML below, a toolbar which uses icon images as link labels provides `alt` attributes for each giving a textual label to use instead of the icon when the icons cannot be or are intentionally not used.
 
 ```html
-<li class="toolbar" aria-role="toolbar">
-  <a href="songs.html" aria-role="button">
+<li class="toolbar" role="toolbar">
+  <a href="songs.html" role="button">
     <img src="songicon.svg" alt="Songs" />
   </a>
-  <a href="albums.html" aria-role="button">
+  <a href="albums.html" role="button">
     <img src="albumicon.svg" alt="Albums"
   /></a>
-  <a href="artists.html" aria-role="button">
+  <a href="artists.html" role="button">
     <img src="artisticon.svg" alt="Artists" />
   </a>
-  <a href="playlists.html" aria-role="button">
+  <a href="playlists.html" role="button">
     <img src="playlisticon.svg" alt="Playlists" />
   </a>
 </li>

files/en-us/web/api/htmllinkelement/sizes/index.md

@@ -8,7 +8,7 @@ browser-compat: api.HTMLLinkElement.sizes
 
 {{APIRef("HTML DOM")}}
 
-The readonly **`sizes`** property of the {{domxref("HTMLLinkElement")}} interfaces defines the sizes of the icons for visual media contained in the resource. It reflects the {{HTMLElement("link")}} element's [`sizes`](/en-US/docs/Web/HTML/Element/link#sizes) attribute, which takes a list of space-separated sizes, each in the format `<width in pixels>x<height in pixels>`, or the keyword `any`.
+The **`sizes`** read-only property of the {{domxref("HTMLLinkElement")}} interfaces defines the sizes of the icons for visual media contained in the resource. It reflects the {{HTMLElement("link")}} element's [`sizes`](/en-US/docs/Web/HTML/Element/link#sizes) attribute, which takes a list of space-separated sizes, each in the format `<width in pixels>x<height in pixels>`, or the keyword `any`.
 
 It is only relevant if the {{domxref("HTMLLinkElement.rel", "rel")}} is `icon` or a non-standard type like `apple-touch-icon`.