Merge branch 'main' into patch-5

.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.

.vscode/dictionaries/ignore-list.txt

@@ -112,9 +112,11 @@ dubby
 Duden
 dXNlcm5hbWU6cGFzc3dvcmQ
 EACC
+efregre
 eirmod
 elitr
 ERHGDFy
+ertgrth
 esset
 essum
 Ethere
@@ -173,6 +175,7 @@ isnt
 isoff
 javascripts
 jdoe
+Jgfbgfdgt
 jngl
 jnglstore
 js13kgames
@@ -253,6 +256,7 @@ rebum
 regelialia
 rheeeeet
 ricebean
+rtgtfghhyj
 s3pPLMBiTxaQ9kYGzzhZRbK
 sadipscing
 sagnarelli
@@ -306,6 +310,7 @@ webglsamples
 webvr
 weta
 Whereami
+Whereshire
 wisen
 wisi
 Wookie

.vscode/dictionaries/proper-names.txt

@@ -76,6 +76,7 @@ Béziers
 caitmuenster
 Camino
 Camtasia
+Canva
 Carakan
 Cardano
 carinaanand
@@ -567,6 +568,7 @@ Theora
 Thierry
 Tidwell
 Tink
+tinypng
 Titilayo
 Tokopedia
 Tomayac

.vscode/dictionaries/terms-abbreviations.txt

@@ -714,6 +714,7 @@ sundried
 sunsetting
 supercookie
 superdomain
+superpowered
 superscaling
 supersets
 SVCB

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/learn_web_development/getting_started/environment_setup/browsing_the_web/index.md

@@ -89,15 +89,15 @@ All web pages can each be found at a unique location (web address, also called a
 
 A _website_ is a collection of linked web pages (plus their associated resources) that share a unique [domain name](/en-US/docs/Learn_web_development/Howto/Web_mechanics/What_is_a_domain_name). Each web page of a given website provides explicit links—most of the time in the form of clickable portions of text—that allow the user to move from one page of the website to another.
 
-When you load your favourite website in a browser, it tends to first display the website's main web page, or _homepage_ (casually referred to as "home"):
+When you load your favorite website in a browser, it tends to first display the website's main web page, or _homepage_ (casually referred to as "home"):
 
 ![Example of a website domain name in the browser address bar](web-site.jpg)
 
 > [!CALLOUT]
 >
 > **Try it out**
 >
-> Try clicking some menu items or links to look at some different pages on your favourite website.
+> Try clicking some menu items or links to look at some different pages on your favorite website.
 
 > [!NOTE]
 > It is also possible to have a [_single-page app_](/en-US/docs/Glossary/SPA): a website that consists of a single web page that is dynamically updated with new content when needed.
@@ -146,11 +146,11 @@ When you access the web, quite a lot happens between your first interaction (for
 
 This description of how the web works is heavily simplified, but it is all you really need to know at this point. You will find a more detailed account of how web pages and requested and rendered by a web browser in our [Web standards](/en-US/docs/Learn_web_development/Getting_started/Web_standards) module, slightly later on.
 
-For now, try opening a web browser and loading up a couple of your favourite sites, thinking about the above steps as you do so.
+For now, try opening a web browser and loading up a couple of your favorite sites, thinking about the above steps as you do so.
 
 ## Searching for information
 
-As a web developer, you will spend a lot of time searching for information, from syntax you can't remember to solutions to specific problems. It is therefore a good idea to learn how to effecively search the web.
+As a web developer, you will spend a lot of time searching for information, from syntax you can't remember to solutions to specific problems. It is therefore a good idea to learn how to effectively search the web.
 
 If you are looking for general information about a specific web technology feature, you should type the name of the feature into the MDN search box. For example, try typing `box model`, `fetch()` or `video element` into the the search box and see what comes up. If you don't find the information you need, try expanding your search — try your search term in a search engine.
 

files/en-us/learn_web_development/getting_started/environment_setup/code_editors/index.md

@@ -35,7 +35,7 @@ Previously, we told you to install a code editor, as you'll need one to work thr
 
 Before starting to code, you may have had some experience working on text documents in a program like Microsoft Word. You might also be wondering whether you can work with code in these same programs. Unfortunately, the answer is "not really":
 
-- Programs like Micosoft Word are **Binary file** editors; their files contain a non-text format that can only be understood by those programs. Website source code, on the other hand, is stored as plain text.
+- Programs like Microsoft Word are **Binary file** editors; their files contain a non-text format that can only be understood by those programs. Website source code, on the other hand, is stored as plain text.
 - Word _can_ open and edit plain text files, but it doesn't handle them very well. It doesn't have a featureset designed for working with code — it is for writing documents such as letters and reports. You need a program that is designed to cleanly handle and output plain text, and work with code.
 
 You probably already have a plain text editor on your computer. By default, Windows includes [Notepad](https://en.wikipedia.org/wiki/Microsoft_Notepad) and macOS comes with [TextEdit](https://en.wikipedia.org/wiki/TextEdit). Linux distros vary; the Ubuntu 22.04 LTS release comes with [GNOME Text Editor](https://en.wikipedia.org/wiki/GNOME_Text_Editor) by default. Default OS plain text editors can be OK, but they also have a limited feature set.
@@ -87,8 +87,8 @@ Let's try an exercise in VS Code:
 
 VS Code provides other syntax features too. For example:
 
-- You'll see a thin vertical line travelling down from the `function` keyword to the closing curly brace (`}`) — these lines are used to mark different [indentation](https://en.wikipedia.org/wiki/Indentation_style) levels in code, making it easier to identify where blocks begin and end.
-- Also try moving the flashing text cursor over the opening or closing curly brace (`{` or `}`) — you'll see both of them highlighted. This also helps identify the start and end of blocks, and is useful when are trying to find where you are missing a character when you have a more complicated structure with lots of nested blocks. This highlighting also works with other delimeters such as parentheses (`(` and `)`) and square brackets (`[` and `]`).
+- You'll see a thin vertical line traveling down from the `function` keyword to the closing curly brace (`}`) — these lines are used to mark different [indentation](https://en.wikipedia.org/wiki/Indentation_style) levels in code, making it easier to identify where blocks begin and end.
+- Also try moving the flashing text cursor over the opening or closing curly brace (`{` or `}`) — you'll see both of them highlighted. This also helps identify the start and end of blocks, and is useful when are trying to find where you are missing a character when you have a more complicated structure with lots of nested blocks. This highlighting also works with other delimiters such as parentheses (`(` and `)`) and square brackets (`[` and `]`).
 
 ### Code completion/suggestion