Merge branch 'main' into patch-1

.github/workflows/pr-check-lint_content.yml

@@ -101,6 +101,12 @@ jobs:
           echo "FM_LINT_FAILED=${FM_LINT_FAILED}" >> $GITHUB_ENV
 
           echo "Running Prettier"
+          PRETTIER_FAILED=false
+          PRETTIER_LOG=$(yarn prettier --check ${files_to_lint} 2>&1) || PRETTIER_FAILED=true
+          echo "PRETTIER_LOG<<${EOF}" >> $GITHUB_ENV
+          echo "${PRETTIER_LOG}" >> $GITHUB_ENV
+          echo "${EOF}" >> $GITHUB_ENV
+          echo "PRETTIER_FAILED=${PRETTIER_FAILED}" >> $GITHUB_ENV
           yarn prettier -w ${files_to_lint}
 
           if [[ -n $(git diff) ]]; then
@@ -110,16 +116,17 @@ jobs:
           # info for troubleshooting
           echo MD_LINT_FAILED=${MD_LINT_FAILED}
           echo FM_LINT_FAILED=${FM_LINT_FAILED}
+          echo PRETTIER_FAILED=${PRETTIER_FAILED}
           git diff
 
       - name: Setup reviewdog
-        if: env.FILES_MODIFIED == 'true' || env.MD_LINT_FAILED == 'true'
+        if: ${{ env.FILES_MODIFIED == 'true' || env.MD_LINT_FAILED == 'true' }}
         uses: reviewdog/action-setup@v1
         with:
           reviewdog_version: latest
 
       - name: Suggest changes using diff
-        if: env.FILES_MODIFIED == 'true'
+        if: ${{ env.FILES_MODIFIED == 'true' }}
         env:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
@@ -134,7 +141,7 @@ jobs:
             -reporter=github-pr-review < "${TMPFILE}"
 
       - name: Add reviews for markdownlint errors
-        if: env.MD_LINT_FAILED == 'true'
+        if: ${{ env.MD_LINT_FAILED == 'true' }}
         env:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
@@ -147,11 +154,31 @@ jobs:
             -reporter="github-pr-review"
 
       - name: Fail if any issues pending
-        if: env.FILES_MODIFIED == 'true' || env.MD_LINT_FAILED == 'true' || env.FM_LINT_FAILED == 'true'
+        if: ${{ env.FILES_MODIFIED == 'true' || env.MD_LINT_FAILED == 'true' || env.FM_LINT_FAILED == 'true' }}
+        env:
+          MD_LINT_FAILED: ${{ env.MD_LINT_FAILED }}
+          FM_LINT_FAILED: ${{ env.FM_LINT_FAILED }}
+          PRETTIER_FAILED: ${{ env.PRETTIER_FAILED }}
+          MD_LINT_LOG: ${{ env.MD_LINT_LOG }}
+          FM_LINT_LOG: ${{ env.FM_LINT_LOG }}
+          PRETTIER_LOG: ${{ env.PRETTIER_LOG }}
         run: |
-          echo -e "\nLogs from markdownlint:"
-          echo "${MD_LINT_LOG}"
-          echo -e "\nLogs from front-matter linter:"
-          echo "${FM_LINT_LOG}"
-          echo -e "\nPlease fix all the linting issues mentioned in above logs and in the review comments."
+          echo -e "\nPlease fix all the linting issues mentioned in the following logs and in the PR review comments."
+
+          if [[ ${MD_LINT_FAILED} == 'true' ]]; then
+            echo -e "\n\n🪵 Logs from markdownlint:"
+            echo "${MD_LINT_LOG}"
+          fi
+
+          if [[ ${FM_LINT_FAILED} == 'true' ]]; then
+            echo -e "\n\n🪵 Logs from front-matter linter:"
+            echo "${FM_LINT_LOG}"
+          fi
+
+          if [[ ${PRETTIER_FAILED} == 'true' ]]; then
+            echo -e "\n\n🪵 Logs from Prettier formatter:"
+            echo "${PRETTIER_LOG}"
+            echo -e "\nYou can use Prettier playground to format the files online (configuration pre-filled): https://prettier.io/playground/#N4Igxg9gdgLgprEAuEBiABABwIYGd7owAWc6CMAlgE6kBmFANqSTSADQgSaXS7KjYqVCAHcACoIR8U2BiOwBPPhwBGVbGADWcGAGVsAWzgAZClDjIYVAK5xV6rTt04wZgOaWbdkLjgGKnrYccAAemHBUFEawsgAqEVCCFHDStLK+HLjuTACK1hDwyGkMGSAAVrghutlweQUWSMWlAI758GLCmNIgeAC05nAAJkPsIFbYjO4AwhAGBtjIPQwMo1lQbkwAgjBWFCrW7RGm5kXp3kQwBgwA6kQU8LgucLpS9xQAbvcKi2C4yiDvWwASSgw1gujAkW4m1BuhgCiYpxK3kwwl813UmEWqJSEXeFg4Zl8VBgHWwbnmSNKOCoxMW8yomkGoigo1RZhg1wog2IyAAHAAGDg0VrUOBkikLRpnDgwbAqLk8ojIABMHGsvli8tSMpAfhUQ2Gg2M2HW1nJcAAYhAqPMdu5FtgDhAQABfV1AA \n"
+          fi
+
           exit 1

.vscode/dictionaries/terms-abbreviations.txt

@@ -21,6 +21,7 @@ ANMF
 anonymization
 antialiasing
 antitracking
+apideck
 APNG
 appcontent
 arcosh
@@ -529,6 +530,7 @@ quickmenu
 qvalues
 QWERTZ
 randomizer
+rari
 rasterizes
 RDBMS
 RDBMSes
@@ -562,6 +564,7 @@ retarget
 retargeted
 retargeting
 retargetings
+reviewdog
 RFCOMM
 RGTC
 roadmaps
@@ -879,6 +882,7 @@ xrayed
 Xrays
 XRCPU
 XSSI
+yari
 yearless
 Zalgo
 zoomable

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

@@ -25,8 +25,8 @@ In the previous article, we looked at one of the most important features for mak
       <th scope="row">Learning outcomes:</th>
       <td>
         <ul>
-          <li>An understanding of the accessibility issues associated with tables.<li>
-          <li>Adding captions to tables.<li>
+          <li>An understanding of the accessibility issues associated with tables.</li>
+          <li>Adding captions to tables.</li>
           <li>Better table structuring with head, body, and footer.</li>
           <li>Creating further association between headers and cells with the <code>scope</code>, <code>id</code>, and <code>headers</code> attributes.</li>
         </ul>

files/en-us/learn_web_development/core/styling_basics/values_and_units/index.md

@@ -43,7 +43,7 @@ In this lesson, we will take a look at some of the most frequently used value ty
 
 In CSS specifications and on the property pages here on MDN you will be able to spot value types as they will be surrounded by angle brackets (`<`, `>`), such as [`<color>`](/en-US/docs/Web/CSS/color_value) or {{cssxref("length")}}. When you see the value type `<color>` as valid for a particular property, that means you can use any valid color as a value for that property, as listed on the [`<color>`](/en-US/docs/Web/CSS/color_value) reference page.
 
-Sometimes value types and properties can have the same, or similar names — For example, there is a {{cssxref("color")}} property and a [`<color>`](/en-US/docs/Web/CSS/color_value) data type. You can use the angle brackets to determine which one you are studying in each case. HTML elements also use angle brackets, but it should be clear from the context which one you are looking at. If yo are not sure, try searching for it on MDN.
+Sometimes value types and properties can have the same, or similar names — For example, there is a {{cssxref("color")}} property and a [`<color>`](/en-US/docs/Web/CSS/color_value) data type. You can use the angle brackets to determine which one you are studying in each case. HTML elements also use angle brackets, but it should be clear from the context which one you are looking at. If you are not sure, try searching for it on MDN.
 
 > [!NOTE]
 > You'll see CSS value types referred to as _data types_. The terms are basically interchangeable — when you see something in CSS referred to as a data type, it is really just a fancy way of saying value type. The term _value_ refers to any particular expression supported by a value type that you choose to use.

files/en-us/learn_web_development/getting_started/your_first_website/creating_the_content/index.md

@@ -156,7 +156,7 @@ The keywords for alt text are "descriptive text". The alt text you write should
 Let's get your image displaying now.
 
 1. Inside the `first-website` folder, Create a new folder called `images`, and put the image you chose in the previous example inside this folder.
-2. Inside the `<img>` tag's `alt` attribute value, enter the path to your image. It is inside a folder called `images`, which is inside the same directory as your `index.html` file, therefore the path will be `images/` plus the name of your image. For example, if your image was called `firefox-icon.png`, your `src` attribute would look like this: `src="images/firefox-icon.png"`.
+2. Inside the `<img>` tag's `src` attribute value, enter the path to your image. It is inside a folder called `images`, which is inside the same directory as your `index.html` file, therefore the path will be `images/` plus the name of your image. For example, if your image was called `firefox-icon.png`, your `src` attribute would look like this: `src="images/firefox-icon.png"`.
 3. replace the `alt` attribute value — `My test image` — with some text that better describes your image.
 4. Open your `index.html` file inside a web browser. You should see your image displayed. If not, check your `<img>` element against our code above; make sure it is not missing any of the syntax, such as the quote marks. Make sure the image filename is correct.
 

files/en-us/mozilla/add-ons/webextensions/api/permissions/request/index.md

@@ -7,15 +7,17 @@ browser-compat: webextensions.api.permissions.request
 
 {{AddonSidebar}}
 
-Ask for the set of permissions listed in the given {{WebExtAPIRef("permissions.Permissions")}} object.
+Asks the user for the permissions listed in the {{WebExtAPIRef("permissions.Permissions")}} object.
 
-The `Permissions` argument may contain either an `origins` property, which is an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), or a `permissions` property, which is an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both. Permissions must come from the set of permissions defined in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key. The `origins` property may include permissions that match a subset of the hosts matched by an optional permission: for example, if optional_permissions include "\*://mozilla.org/", then `permissions.origins` may include "https\://developer.mozilla.org/".
+The `Permissions` argument can contain an `origins` property, an array of [host permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions), a `permissions` property, an array of [API permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions), or both.
 
-The request can only be made inside the handler for a [user action](/en-US/docs/Mozilla/Add-ons/WebExtensions/User_actions).
+Requested permissions must be defined in the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) manifest.json key. The `origins` property can include permissions matching a subset of the hosts matched by an optional permission. For example, if `optional_permissions` include `"*://mozilla.org/"`, then `permissions.origins` can include `"https://developer.mozilla.org/"`.
 
-Depending on a circumstances, the browser will probably handle the request by asking the user whether to grant the requested permissions. Only a single request is made for all requested permissions: thus either all permissions are granted or none of them are.
+Requests for [optional-only permissions](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions#optional-only_permissions) can't include any other optional permissions.
 
-Any permissions granted are retained by the extension, even over upgrade and disable/enable cycling.
+The request can only be made inside the handler for a [user action](/en-US/docs/Mozilla/Add-ons/WebExtensions/User_actions). Unless all the permissions requested are ones granted silently, the browser asks the user whether to grant the requested permissions. One request is made for all requested permissions: either all permissions are granted or none are.
+
+The extension retains any permissions granted, even over upgrade and disable and enable cycling.
 
 This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
 
@@ -34,15 +36,15 @@ let requesting = browser.permissions.request(
 
 ### Return value
 
-A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with `true` if the extension is now granted all the permissions listed in the `permissions` argument, or `false` otherwise.
+A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled with `true` if the extension is granted the permissions listed in the `permissions` argument, or `false` otherwise.
 
 ## Browser compatibility
 
 {{Compat}}
 
 ## Examples
 
-This code adds a click handler that asks for various permissions, then logs the result of the request and the extension's permissions after the request completed.
+This code adds a click handler that asks for various permissions, then logs the result of the request and the extension's permissions after the request completes.
 
 ```js
 const permissionsToRequest = {
@@ -73,8 +75,5 @@ document
 
 {{WebExtExamples}}
 
-> [!NOTE]
-> Currently has a [bug with requesting origins](https://bugzil.la/1411873) and [requesting permissions on the about:addons page](https://bugzil.la/1382953).
-
 > [!NOTE]
 > This API is based on Chromium's [`chrome.permissions`](https://developer.chrome.com/docs/extensions/reference/api/permissions) API.

files/en-us/mozilla/add-ons/webextensions/manifest.json/optional_permissions/index.md

@@ -33,26 +33,26 @@ browser-compat: webextensions.manifest.optional_permissions
   </tbody>
 </table>
 
-Use the `optional_permissions` key to list permissions that you want to ask for at runtime, after your extension has been installed.
+Use the `optional_permissions` key to list permissions you want to ask for at runtime, after your extension has been installed.
 
-The [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) key lists permissions that your extension needs before it can be installed. In contrast, `optional_permissions` lists permissions that your extension doesn't need at install time but it may ask for after it has been installed. To ask for a permission, use the {{webextapiref("permissions")}} API. Asking for a permission may present the user with a dialog requesting them to grant the permission to your extension.
+The [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) key lists permissions that your extension needs before it can be installed. In contrast, `optional_permissions` lists permissions that your extension doesn't need at install time but can ask for after installation. To ask for a permission, use the {{webextapiref("permissions.request()")}} API. Asking for a permission presents the user with a dialog requesting them to grant the permission to your extension, unless all the permissions requested are granted silently.
 
 For advice on designing your request for runtime permissions, to maximize the likelihood that users grant them, see [Request permissions at runtime](https://extensionworkshop.com/documentation/develop/request-the-right-permissions/#request_permissions_at_runtime).
 
-Starting with Firefox 84, users can manage optional permissions from the Firefox Add-ons Manager. Extensions that use optional permissions can listen for [browser.permissions.onAdded](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onAdded) and [browser.permissions.onRemoved](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/permissions/onRemoved) API events to know when a user grants or revokes these permissions.
+Starting with Firefox 84, users can manage optional permissions from the Firefox Add-ons Manager. Extensions that use optional permissions can check for the permissions granted by the user with {{webextapiref("permissions.getAll()")}} and listen for {{webextapiref("permissions.onAdded")}} and {{webextapiref("permissions.onRemoved")}} to know when a user grants or revokes permissions.
 
-The key can contain two kinds of permissions: host permissions and API permissions.
+The key can contain host permissions and API permissions.
 
 ## Host permissions
 
 These are the same as the host permissions you can specify in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#host_permissions) key.
 
 > [!NOTE]
-> When using Manifest V3 or higher optional host permissions should be specified using the [`optional_host_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_host_permissions) manifest key. Firefox introduced `optional_host_permissions` in release 128, see [bug 1766026](https://bugzil.la/1766026), and allows for the continued use of `optional_permissions` to specify optional hosts. Use of `optional_host_permissions` however is recommended.
+> When using Manifest V3 or higher, optional host permissions should be specified using the [`optional_host_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_host_permissions) manifest key. Firefox introduced `optional_host_permissions` in release 128, see [bug 1766026](https://bugzil.la/1766026), and allows the continued use of `optional_permissions` to specify optional hosts. Use of `optional_host_permissions`, however, is recommended.
 
 ## API permissions
 
-You can include any of the following here, but not in all browsers: check the compatibility table for browser-specific details.
+The optional API permissions are:
 
 - `activeTab`
 - `background`
@@ -94,9 +94,9 @@ You can include any of the following here, but not in all browsers: check the co
 - `webRequestFilterResponse`
 - `webRequestFilterResponse.serviceWorkerScript`
 
-Note that this is a subset of the API permissions allowed in [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions).
+Check the compatibility table for browser-specific support details.
 
-Of this set, the following permissions are granted silently, without a user prompt:
+These optional permissions are granted silently, without a user prompt:
 
 - `activeTab`
 - `cookies`
@@ -106,7 +106,14 @@ Of this set, the following permissions are granted silently, without a user prom
 - `webRequestFilterResponse`
 - `webRequestFilterResponse.serviceWorkerScript`
 
-## Example
+### Optional-only permissions
+
+Optional permissions are generally available for use in the [`permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions#api_permissions) key so they can be requested at install time. However, some browsers support the concept of optional-only permissions, permissions that can only be requested at runtime using the {{webextapiref("permissions.request()")}} API. In addition, optional-only permissions must be requested individually and alone through the {{webextapiref("permissions.request()")}} API.
+
+> [!NOTE]
+> No optional-only permissions were generally available at the time of writing, December 2024.
+
+## Examples
 
 ```json
  "optional_permissions": ["*://developer.mozilla.org/*"]

files/en-us/web/api/element/attachshadow/index.md

@@ -115,7 +115,7 @@ Returns a {{domxref("ShadowRoot")}} object.
 
 - `NotSupportedError` {{domxref("DOMException")}}
 
-  - : This may can be thrown when you try to attach a shadow root to an element:
+  - : This error may be thrown when you try to attach a shadow root to an element:
 
     - outside the HTML namespace or that can't have a shadow attached to it.
     - where the element definition static property `disabledFeatures` has been given a value of `"shadow"`.

files/en-us/web/api/htmlinputelement/showpicker/index.md

@@ -89,7 +89,7 @@ document.querySelectorAll("button").forEach((button) => {
     try {
       input.showPicker();
     } catch (error) {
-      window.alert(error);
+      console.log(error);
     }
   });
 });