From b244b8cea36fe9070fe6d7e406b796cb4da30018 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Wed, 6 Jul 2022 15:40:30 +0200 Subject: [PATCH 01/70] Move new contrib docs --- .../attrib-copyright-license/index.md | 82 +++ .../creating-moving-archiving-pages/index.md | 176 +++++ files/en-us/mdn/writing-guidelines/index.md | 53 ++ .../page-structure/code-examples/index.md | 181 ++++++ .../page-structure/frontmatter/index.md | 0 .../page-structure/images-media/index.md | 171 +++++ .../page-structure/index.md | 48 ++ .../page-structure/macros/index.md | 0 .../page-structure/markdown/index.md | 497 ++++++++++++++ .../page-types/api/apiref-links.png | Bin 0 -> 6176 bytes .../page-structure/page-types/api/index.md | 405 ++++++++++++ .../index.md | 607 ++++++++++++++++++ .../page-types/api/sidebars/index.md | 141 ++++ .../page-structure/page-types/css/index.md | 0 .../page-types/css/property/index.md | 27 + .../page-types/glossary/index.md | 74 +++ .../page-structure/page-types/html/index.md | 0 .../page-structure/page-types/http/index.md | 59 ++ .../page-types/js/errors/index.md | 43 ++ .../page-structure/page-types/js/index.md | 0 .../page-structure/page-types/learn/index.md | 0 .../page-structure/updating-json/index.md | 117 ++++ .../researching-technology/index.md | 115 ++++ .../experimental_deprecated_obsolete/index.md | 111 ++++ .../what-we-write/inclusion-criteria/index.md | 182 ++++++ .../writing-guidelines/what-we-write/index.md | 118 ++++ .../code-style-guide/css/index.md | 225 +++++++ .../code-style-guide/html/index.md | 168 +++++ .../code-style-guide/index.md | 176 +++++ .../code-style-guide/javascript/index.md | 485 ++++++++++++++ .../code-style-guide/shell/index.md | 33 + .../writing-style-guide/index.md | 600 +++++++++++++++++ 32 files changed, 4894 insertions(+) create mode 100644 files/en-us/mdn/writing-guidelines/attrib-copyright-license/index.md create mode 100644 files/en-us/mdn/writing-guidelines/creating-moving-archiving-pages/index.md create mode 100644 files/en-us/mdn/writing-guidelines/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/code-examples/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/frontmatter/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/images-media/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/macros/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/markdown/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/api/apiref-links.png create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/api/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/api/information_contained_in_a_webidl_file/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/api/sidebars/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/css/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/css/property/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/glossary/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/html/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/http/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/js/errors/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/js/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/page-types/learn/index.md create mode 100644 files/en-us/mdn/writing-guidelines/page-structure/updating-json/index.md create mode 100644 files/en-us/mdn/writing-guidelines/researching-technology/index.md create mode 100644 files/en-us/mdn/writing-guidelines/what-we-write/experimental_deprecated_obsolete/index.md create mode 100644 files/en-us/mdn/writing-guidelines/what-we-write/inclusion-criteria/index.md create mode 100644 files/en-us/mdn/writing-guidelines/what-we-write/index.md create mode 100644 files/en-us/mdn/writing-guidelines/writing-style-guide/code-style-guide/css/index.md create mode 100644 files/en-us/mdn/writing-guidelines/writing-style-guide/code-style-guide/html/index.md create mode 100644 files/en-us/mdn/writing-guidelines/writing-style-guide/code-style-guide/index.md create mode 100644 files/en-us/mdn/writing-guidelines/writing-style-guide/code-style-guide/javascript/index.md create mode 100644 files/en-us/mdn/writing-guidelines/writing-style-guide/code-style-guide/shell/index.md create mode 100644 files/en-us/mdn/writing-guidelines/writing-style-guide/index.md diff --git a/files/en-us/mdn/writing-guidelines/attrib-copyright-license/index.md b/files/en-us/mdn/writing-guidelines/attrib-copyright-license/index.md new file mode 100644 index 000000000000000..69fb9eaec25fe25 --- /dev/null +++ b/files/en-us/mdn/writing-guidelines/attrib-copyright-license/index.md @@ -0,0 +1,82 @@ +--- +title: 'Attributions and copyright licensing' +slug: MDN/Writing_guidelines/Attrib_copyright_license +page-type: mdn-writing-guide +tags: + - meta + - writing-guide +--- +{{MDNSidebar}} + +## Using MDN Web Docs content + +MDN Web Doc's content is available free of charge, and under open source licenses. + +## Copyrights and licenses + +MDN's content is entirely available under various open source licenses. This section covers the types of content we provide and what licenses are in effect for each. + +### Linking to MDN + +We regularly get users asking us questions about how to link to MDN, or even if doing so is allowed. The short answer is: **yes, you can link to MDN!** Not only is the hypertext link the essence of the Web, it is both a way to point your users to valuable resources and a show of trust toward the work our community does. + +### Documentation and articles + +> **Note:** MDN content has been prepared with the contributions of authors from both inside and outside Mozilla. Unless otherwise indicated, the content is available under the terms of the [Creative Commons Attribution-ShareAlike license](https://creativecommons.org/licenses/by-sa/2.5/) (CC-BY-SA), v2.5 or any later version. + +When reusing MDN content, you need to ensure two things: + +1. Attribution is given to the original content. + + Please attribute "Mozilla Contributors" and include a hyperlink (online) or URL (in print) to the specific page of the content being sourced. For example, to provide attribution for _this_ article, you can write: + + > [MDN Attributions and copyright licensing](/en_US/docs/MDN/Writing_guidelines/Attrib_copyright_license) by [Mozilla Contributors](/en-US/docs/MDN/About/contributors.txt) is licensed under [CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/). + + Note that in the example, "Mozilla Contributors" links to the history of the cited page. See [Best practices for attribution](https://wiki.creativecommons.org/wiki/Marking/Users) for further explanation. + +2. Your reuse is published under the same license as the original content—CC-BY-SA v2.5 or any later version. + +### Code samples and snippets + +Code samples added on or after August 20, 2010 are in the [public domain](https://creativecommons.org/publicdomain/zero/1.0/) ([CC0](https://creativecommons.org/publicdomain/zero/1.0/)). No licensing notice is necessary, but if you need one, you can use: "Any copyright is dedicated to the Public Domain. http\://creativecommons.org/publicdomain/zero/1.0/". + +Code samples added before August 20, 2010 are available under the [MIT license](https://opensource.org/licenses/mit-license.php); you should insert the following attribution information into the MIT template: "© \ \". + +Since the launch of the new Yari MDN platform on December 14 2020, there is currently no way to determine which one you need. We are working on this and will update this content soon. + +### Contributions + +If you wish to contribute to MDN Web Docs, you agree your documentation is available under the Attribution-ShareAlike license (or occasionally an alternative license already specified by the page you are editing), and your code samples available under [Creative Commons CC-0](https://creativecommons.org/publicdomain/zero/1.0/) (a Public Domain dedication). + +> **Warning:** No new pages may be created using alternate licenses. + +**Copyright for contributed materials remains with the author unless the author assigns it to someone else**. + +If you have any questions or concerns about anything discussed here, please [contact us](). + +### Logos, trademarks, service marks and wordmarks + +The rights in the trademarks, logos, and service marks of the Mozilla Foundation, as well as the look and feel of this website, are not licensed under the Creative Commons license, and to the extent they are works of authorship (like logos and graphic design), they are not included in the work that is licensed under those terms. If you use the text of documents, and wish to also use any of these rights, or if you have any other questions about complying with our licensing terms for this collection, you should contact the Mozilla Foundation here: [licensing@mozilla.org](mailto:licensing@mozilla.org "mailto:licensing@mozilla.org"). + +## Content from elsewhere + +Often, there is useful content about a topic somewhere on the web besides MDN Web Docs. +However, copying such content can be fraught with difficulties, both technical and legal. + +On the technical level, search engines typically penalize a site in their rankings for reproducing content available elsewhere. +Therefore, it is preferable to have original content on MDN Web Docs to enhance the search engine ranking of MDN Web Docs' content. +You can link to the existing content from MDN Web Docs. + +On the legal level, you must be authorized to contribute the content, and it must be licensed and attributed in a way that is compatible with MDN's license. + +- **If you created the existing content** (for your own purposes and not as work-for-hire), and you are willing to contribute it to MDN Web Docs under MDN's license, this is the easiest case, and you are free to contribute the content. +- **If the copyright for the content belongs to someone else**, it must be licensed and attributed compatibly with MDN's license. + It is often not easy for someone who is not a lawyer to determine what licenses are compatible. + To be on the safe side, contact a member of the [MDN Web Docs team](https://github.com/mdn/mdn-community/discussions), who may consult Mozilla's Legal team for guidance if necessary. + + + + + + + diff --git a/files/en-us/mdn/writing-guidelines/creating-moving-archiving-pages/index.md b/files/en-us/mdn/writing-guidelines/creating-moving-archiving-pages/index.md new file mode 100644 index 000000000000000..5be010abb5e368a --- /dev/null +++ b/files/en-us/mdn/writing-guidelines/creating-moving-archiving-pages/index.md @@ -0,0 +1,176 @@ +--- +title: 'Creating, moving, and deleting pages' +slug: MDN/Writing_guidelines +page-type: mdn-writing-guide +tags: + - meta + - writing-guide +--- +{{MDNSidebar}} + +This article describes how to create, move or delete a page. In all instances it's a good idea to check our [What we write](/en_US/docs/MDN/Writing_guidelines/What_we_write) guidelines for whether any of these actions should be taken and discuss it with us before going ahead. + +## Creating pages + +All pages are authored in markdown format, with the filename `index.md` and their own unique directory. The directory name represents the name of the page. For example to create a new reference page for a new CSS property, you'd create a folder in `en-us/web/css` named with the property name and create a file called `index.md` inside it. + +> **Note:** The name of the directory differs slightly from the slug of the page. Most notably the slug is capitalized. + +There are lots of different [page types with certain structures](/en_US/docs/MDN/Writing_guidelines/How_to_write/Page_types), and supporting page templates for them, which you can copy to get you started. + +A document's `index.md` file must start with front-matter that defines the `title`, `short-title`, `page-type`, `slug`, and `tags`. All of which can be found in the afore mentioned page templates. Alternatively you might find it helpful to refer to the front-matter within a similar document's `index.md`. + +The step-by-step process in general would be: + +1. Start a fresh, up-to-date branch to work within: + +```sh +cd ~/repos/mdn/content +git checkout main +git pull mdn main +# Run "yarn" again to ensure you've +# installed the latest Yari dependency. +yarn +git checkout -b my-add +``` + +1. Create one or more new document folders, each with their own `index.md` file. + +1. Add and commit your new files, as well as push your new branch to your fork: + + ```sh + git add files/en-us/folder/you/created + git commit + git push -u origin my-add + ``` + +1. And finally create your +pull request. + +## Moving pages + +Moving one or more documents, or an entire tree of documents is easy, +because we've created a special command that takes care of the details for you: + +```sh +yarn content move [locale] +``` + +You just have to specify the slug of the existing document that you'd like +to move (e.g., `Learn/Accessibility`), as well as the slug of its new +location (e.g., `Learn/A11y`), optionally followed by the locale of the +existing document (defaults to `en-US`). +If the existing document that you'd like to move has child documents (i.e. +it represents a document tree), the `yarn content move` command will move +the entire tree. For example, let's say you want to move the entire +`/en-US/Learn/Accessibility` tree to `/en-US/Learn/A11y`: + +1. First, as we've outlined above, you'll start a fresh branch to work within: + + ```sh + cd ~/repos/mdn/content + git checkout main + git pull mdn main + # Run "yarn" again just to ensure you've + # installed the latest Yari dependency. + yarn + git checkout -b my-move + ``` + +1. Perform the move (which will delete and modify existing files, as well +as create new files): + + ```sh + yarn content move Learn/Accessibility Learn/A11y + ``` + +1. Add and commit all of the deleted, created, and modified files, as well as +push your branch to your fork: + + ```sh + git commit -a + git push -u origin my-move + ``` + +1. Now you're ready to create your pull request. + +> **Note:** `yarn content move` automatically adds the necessary redirect +information to the `_redirects.txt` file so that the old location will redirect +to the new one. Don't edit the `_redirects.txt` file manually! +mistakes can easily creep in if you do. If you need to add a redirect without +moving a file, talk to us about it. + +## Deleting pages + +Documents should only be removed from MDN in special circumstances. If you are thinking about deleting pages, please discuss it with the MDN team first. + +Deleting one or more documents, or an entire tree of documents is also easy, +again because we've created a special command that takes care of the +details for you: + +```sh +yarn content delete [locale] +``` + +You just have to specify the slug of the existing document that you'd like +to delete (e.g., `Learn/Accessibility`), optionally followed by the locale +of the existing document (defaults to `en-US`). If the existing document +that you'd like to delete has child documents (i.e. it represents a +document tree), you must also specify the `-r, --recursive` option, or +the command will fail. + +**Important: you need to use the `delete` command to delete MDN documents. Don't +just delete their directories from the repo, as `delete` also handles other +necessary changes such as updating the `_wikihistory.json` file.** + +For example, let's say you want to delete the +entire `/en-US/Learn/Accessibility` tree: + +1. First, as we've outlined above, you'll start a fresh branch to work in: + + ```sh + cd ~/repos/mdn/content + git checkout main + git pull mdn main + # Run "yarn" again just to ensure you've + # installed the latest Yari dependency. + yarn + git checkout -b my-delete + ``` + +1. Perform the delete: + + ```sh + yarn content delete Learn/Accessibility --recursive + ``` + +1. Add a redirect + +```sh + yarn content add-redirect /en-US/path/of/deleted/page /en-US/path/of/target/page + ``` + + Note that the target page can be an external URL or another page. + +1. Add and commit all of the deleted files, as well as +push your branch to your fork: + + ```sh + git commit -a + git push -u origin my-delete + ``` + +1. Now you're ready to create your pull request. + +> **Note:** If the slug of the page you wish to delete contain special + characters, include it in quotes: + +```sh +yarn content delete "Mozilla/Add-ons/WebExtensions/Debugging_(before_Firefox_50)" +``` + +Removing content from MDN will inevitably result in updating existing content as well, as a lot of articles link to others, the removed content will be referenced elsewhere. + +Adding the redirect will mitigate the impact of removing content, however it's best practice to edit content to reflect the change and include the edits alongside the removal pr. + + diff --git a/files/en-us/mdn/writing-guidelines/index.md b/files/en-us/mdn/writing-guidelines/index.md new file mode 100644 index 000000000000000..43e5d1a08a6b1b1 --- /dev/null +++ b/files/en-us/mdn/writing-guidelines/index.md @@ -0,0 +1,53 @@ +--- +title: MDN writing guidelines +slug: MDN/Writing_guidelines +page-type: mdn-writing-guide +tags: + - meta + - writing-guide +--- +{{MDNSidebar}} + +Here are the guidelines for what we document and how we do it on MDN. + +MDN is an open source project, to find out how to contribute see our contribution guidelines. + +## In this section + +This section contains the following information: + +- [What we write](/en_US/docs/MDN/Writing_guidelines/What_we_write) + - : This sections covers what we include on MDN and want we don't, as well as a number of policies such as when we write about new technologies, content suggestion process, whether we accept external links and when we remove content. This is a good place to start if you're considering writing or updating content for us. This section also includes: + - [Inclusion criteria](/en_US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria) + - : In depth criteria for content to be included on MDN Web Docs, the application process for including new documentation, and expectations and guidelines for a party applying. + +- [Writing style guide](/en_US/docs/MDN/Writing_guidelines/What_we_write) + - : The writing style guide covers the language and style we use to write on MDN. + +- [How to write](/en_US/docs/MDN/Writing_guidelines/How_to_write) + - : How to write covers all the information for creating and editing pages. Including certain processes and techniques we adhere to. This page includes information on getting started, a general overview into how pages are structured and where to find how tos on specific tasks. This section also includes: + + - [Moving and deleting pages]() + - : This explains how to move or delete a page. + + - [Researching a technology](/en_US/docs/MDN/Writing_guidelines/) + - : Some handy tips for researching a technology you are documenting + + - [Page types]() + - : Each page on MDN has a specific type. Whether that's a CSS reference page, or a JavaScript guide page. This lists the different types and provides templates for each structure. It's a good idea to browse these to understand which page type you are writing. + + - [Markdown]() + - : The markdown format we use derives from [GitHub flavored markdown (GFM)](https://github.github.com/gfm/). This is a guide to markdown we use, including formats for specific in page components, such as notes and definition lists. + + - [Macros]() + - : These are shortcuts that are used in pages to generate content, such as sidebars or code examples. This lists the macros we use and what they do. + + - [Code examples]() + - : There are lots of different ways to include code examples on pages. This outlines them and provides syntax guidelines for the different languages. + + - [Images and media]() + - : This section describes requirements for including media in pages, such as images. + +- [Attribution and copyright licensing](/en_US/docs/MDN/Writing_guidelines/Attrib_copyright_license) + - : What copyright license content is and how to attribute correctly. + diff --git a/files/en-us/mdn/writing-guidelines/page-structure/code-examples/index.md b/files/en-us/mdn/writing-guidelines/page-structure/code-examples/index.md new file mode 100644 index 000000000000000..9305a55fc000b58 --- /dev/null +++ b/files/en-us/mdn/writing-guidelines/page-structure/code-examples/index.md @@ -0,0 +1,181 @@ + + +This document series outlines the coding guidelines and best practices we use for writing demos, code snippets, interactive examples, etc, for use on MDN. + +If you are looking for guidelines to follow when writing your code examples, you have come to the right place. The biggest advantage to adhering to these guidelines is that it will foster consistency across our samples and demos on MDN, which increases readability and comprehension overall. + +> **Note:** If you want advice on the styling of code as it appears on an MDN article, rather than the code content, see our [Writing style guide](/en-US/docs/MDN/Guidelines/Writing_style_guide#code_sample_style_and_formatting). + +## Article structure + +This article contains general high-level best practices for writing MDN code examples. Its subarticles are as follows: + +- [General guidelines for all code](/en-US/docs/MDN/Guidelines/Code_guidelines/General) — both syntactical and for styling/displaying examples +- [HTML guidelines](/en-US/docs/MDN/Guidelines/Code_guidelines/HTML) +- [CSS guidelines](/en-US/docs/MDN/Guidelines/Code_guidelines/CSS) +- [JavaScript guidelines](/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript) +- [Shell prompt guidelines](/en-US/docs/MDN/Guidelines/Code_guidelines/Shell) + +## General best practices + +This section provides quick general best practices for creating an understandable minimal code sample to demonstrate usage of a specific feature or function. + +Code samples need to be: + +- simple enough to be understandable, but +- complex enough to do something interesting, and preferably useful. + +There is one overarching consideration that you need to keep in mind: **Readers will copy and paste the code sample into their own code, and may put it into production.** + +Therefore, you need to make sure that the code example is usable and follows generally accepted best practices, and **does not** do anything that will cause an application to be insecure, grossly inefficient, bloated, or inaccessible. If the code example is not runnable or production-worthy, be sure to include a warning in a code comment and in the explanatory text — if it is a snippet and not a full example, make this clear. This also means that you should provide **all** of the information necessary to run the example including any dependencies and setup. + +Code samples should be as self-contained and easy to understand as possible. The aim is not necessarily to produce efficient, clever code that impresses experts and has great functionality, but rather to produce reduced working examples that can be understood as quickly as possible. + +Further general best practices are as follows: + +- The sample should be short and ideally only show the feature you are immediately interested in. +- **Only** include code that is essential for the example. A large amount of non-relevant code can easily distract or confuse the audience. If you want to provide a full, more lengthy, example put it in one of our [GitHub repos](https://github.com/mdn/) (or a JSBin, Codepen, or similar) and then provide the link to the full version above or below the sample. +- Don't include unnecessary server-side code, libraries, frameworks, preprocessors, and other such dependencies — they make the code less portable, and harder to run and understand. Use vanilla code where possible. +- Don't assume knowledge of any libraries, frameworks, preprocessors, or other non-native features. For example, use class names that make sense within the example rather than classnames that make sense to BEM or Bootstrap users. +- Write your code as cleanly and understandably as possible, even if it is not the most efficient way to do it. +- Don't use bad practices for brevity (such as presentational elements like {{HTMLElement("big")}} or {{domxref("Document.write", "document.write()")}}); do it correctly. +- In the case of API demos, if you are using multiple APIs together point out what APIs are included, and what features come from where. + + + +MDN has a "[live sample](/en-US/docs/MDN/Structures/Live_samples)" system, where the code sample shown on a page is directly used to display the output of that same sample. However, many existing articles have code samples that do not yet use this system, and need to be converted. + +Live samples, which let you see what a sample's output looks like, make documentation more dynamic and instructive. This guide covers how to take existing samples and add "live" functionality to them. + +## Where does it need to be done? + +Any article that has a static code example (just blocks of HTML, CSS, JavaScript) that you think would benefit from being shown running live. + +## What do you need to know to do the task? + +- Understanding of HTML, CSS and/or JavaScript, depending on the code sample. +- Ability to use [KumaScript](/en-US/docs/MDN/Tools/KumaScript) macros within MDN articles. + +## What are the steps to do the task? + +1. Find a code example that you think should be converted to be "live". +2. Convert the code sample to be "live". +3. Delete any code or image that was previously used to display the output of the sample. + +For more information on creating and editing Live Samples, see [Using the live sample system](/en-US/docs/MDN/Structures/Live_samples) + + +When learning the web, it's important to rely on active learning content. Such content is made to help with learning something pro-actively. It can be exercises, live hackable examples, tasks to perform, assessments, etc. In short, anything that can help someone to actively understand something. + +There is no straightforward way to create such content. For example many third party tools exist that can help you create live hackable examples (see: [JSFiddle](https://jsfiddle.net/), [CodePen](https://codepen.io/), [Dabblet](https://dabblet.com/), etc.) that you can link from MDN articles. If you want to create more advanced comprehensible exercises, you can easily use [Thimble](https://thimble.mozilla.org) from the WebMaker project. + +Currently, MDN does not have an easy tool to author such active content. However, if you are a coder you can use the current MDN features to create custom active learning content. + +## MDN live samples + +MDN has a very cool feature called **live samples**. It's a mechanism that turns any HTML, CSS, and JavaScript code inside an MDN page into its executed equivalent. Before using it, you should read over [Using the live sample system](/en-US/docs/MDN/Structures/Live_samples), which is our complete documentation for building them. While they're easy to create, there are quirks and tricks you'll learn along the way. + +What is interesting is that it's really easy to tweak that feature to use it in order to embed any kind of tool or utility you want into an MDN page. + +### Hidden code + +The first way to use a code sample to create active learning content is to edit the page where you want to add your content. Use the Live Sample feature to create your content as you wish. Don't bother with the code complexity you could write; just create what you need. Once your code example is ready, surround it with a simple {{HTMLElement('div')}} element with an appropriate `id` attribute. Add the class `hidden` to any {{HTMLElement('pre')}} elements that surround this code. By doing so, your code won't be displayed but your live sample remains accessible and displayable. + +Let's see a simple example: + +Click on the following square to randomly change its color: + +
+ +{{EmbedLiveSample('hidden_code_example', 120, 125)}} + +If you take a look at the source code of this page, you'll see the following HTML code: + +```html +

Click on the following square to randomly change its color or just type an hexadecimal code color

+ +
+ + + + + + +
+ +\{{EmbedLiveSample('hidden_code_example', 120, 125)}} +``` + +You can see a more advanced example of such a tweak on [the Canvas API page](/en-US/docs/Web/API/Canvas_API#javascript). diff --git a/files/en-us/mdn/writing-guidelines/page-structure/frontmatter/index.md b/files/en-us/mdn/writing-guidelines/page-structure/frontmatter/index.md new file mode 100644 index 000000000000000..e69de29bb2d1d64 diff --git a/files/en-us/mdn/writing-guidelines/page-structure/images-media/index.md b/files/en-us/mdn/writing-guidelines/page-structure/images-media/index.md new file mode 100644 index 000000000000000..855113d70c5f2f5 --- /dev/null +++ b/files/en-us/mdn/writing-guidelines/page-structure/images-media/index.md @@ -0,0 +1,171 @@ + + + + +MDN Web Docs is not a very video-heavy site, but there are certain places where video content makes sense to use as part of an article. +This article discusses when including videos in MDN articles is appropriate, and provides tips on how to create simple but effective videos on a budget. + +## When to use video on MDN + +There are several arguments against using video content for technical documentation, particularly reference material and advanced level guides: + +- Video is linear. + People don't tend to read online documentation in a linear fashion, starting at the start and reading through to the end. + _They scan._ + Video is really hard to scan — it forces the user to consume the content start-to-finish. +- Video is less information-dense than text. + It takes longer to consume a video explaining something than it does to read the equivalent instructions. +- Video is big in terms of file size, and therefore more expensive and less performant than text. +- Video has accessibility problems: it's more expensive to produce generally than text, but especially to localize, or make usable by screen reader users. +- Following on from the last point, video is much harder to edit/update/maintain than text content. + +> **Note:** It's worth keeping these problems in mind, even when you are making videos, so you can try to alleviate some of them. + +There are many popular video sites that provide a lot of video tutorials. +MDN isn't a video-driven site, but video does have a place on MDN in certain contexts. + +We tend to most commonly use video when describing some kind of instruction sequence or multi-step workflow that would be hard to describe concisely in words: _"do this, then do that, then this will happen"_. +It is especially useful when trying to describe processes that cross over multiple applications or windows, and include GUI interactions that might not be simple to describe: _"now click on the button near the top-left that looks a bit like a duck"_. + +In such cases it is often more effective to just **show** what you mean. +We most commonly use videos when explaining features of the [Firefox DevTools](https://firefox-source-docs.mozilla.org/devtools-user/index.html). + +## What should MDN videos look like? + +Videos for MDN should be: + +- **Short**: Try to keep videos under 30 seconds, ideally under 20 seconds. + This is short enough not to make big demands on peoples' attention spans. +- **Simple**: Try to make the workflow simple, 2-4 distinct pieces. + This makes them easier to follow. +- **Silent**: Audio makes videos much more engaging, but they are much more time-consuming to make. + Also, having to explain what you're doing makes the videos much longer, and adds to the costs (both financial and in terms of time) of localization. + +To explain something more complex, you can use a blend of short videos and screenshots, interspersed with text. +The text can help reinforce the points made in the video, and the user can rely on the text or the video as they choose. +See [Working with the Animation Inspector](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/work_with_animations/index.html#animation-inspector) for a good example. + +In addition, you should consider the following tips: + +- The video will end up being uploaded to YouTube before embedding. + We'd recommend a 16:9 aspect ratio for this use, so that it fills up the entire viewing frame and you don't end up with ugly black bars on the top and bottom (or left and right) of your video. + So for example, you might choose a resolution of 1024×576, 1152×648, or 1280×720. +- Record the video in HD, so that it looks better when uploaded. +- For DevTools videos, it is often a good idea to choose a contrasting theme to the page content, for example choose the dark theme if the example webpage is light-themed. + It is easier to see what is going on, and where the DevTools start and the page ends. +- For DevTools videos, zoom in the DevTools as much as you can while still showing everything you want to show and making it look OK. +- Make sure the thing you are trying to demonstrate isn't covered up by the mouse cursor. +- Consider whether or not it would be useful to configure the screen recording tool to add a visual indicator of mouse clicks. + +## Video tools + +You'll need some kind of a tool for recording the video. +These range from free to expensive, and simple to complex. +If you are already experienced in creating video content, then great. +If not, then we'd recommend that you start with a simple tool and then work up to something more complex if you start to enjoy creating video and want to create more interesting productions. + +The following table provides some recommendations for good starter tools. + +| Tool | OS | Cost | Post-production features available? | +| ------------------------- | --------------------- | ------ | ----------------------------------- | +| Open Broadcaster Software | macOS, Windows, Linux | Free | Yes | +| CamStudio | Windows | Free | Limited | +| Camtasia | Windows, macOS | High | Yes | +| QuickTime Player | macOS | Free | No, just allows simple recording | +| ScreenFlow | macOS | Medium | Yes | +| Kazam | Linux | Free | Minimal | + +### QuickTime tips + +If you are using macOS, you should have QuickTime Player available. +This actually provides pretty easy simple recording facilities too: + +1. Choose _File_ > _New Screen Recording_ from the main menu. +2. In the _Screen Recording_ box, hit the record button (the red round button). +3. Drag a rectangle round the area of the screen you want to record. +4. Press the _Start Recording_ button. +5. Perform whatever actions you want to record. +6. Press the _Stop_ button. +7. Choose _File_ > _Export As..._ > _1080p_ from the main menu to save as hi definition. + +### Other resources + +- [How to Add Custom Callouts to Screencast Videos in Screenflow](https://photography.tutsplus.com/tutorials/how-to-add-custom-callouts-to-screencast-videos-in-screenflow--cms-27122) + +## A workflow for creating videos + +the following subsections describe the general steps you'd want to follow to create a video and get it shown on an MDN page. + +### Preparation + +First, plan the flow you want to capture: consider the best points to start and end. + +Make sure the desktop background and your browser profile are clean. +Plan the size and positioning of browser windows, especially if you will be using multiple windows. + +Plan carefully what you are actually going to record, and practice the steps a few times before recording them: + +- Don't start a video in the middle of a process — consider whether the viewer has enough context for your actions to make sense to them. + In a short DevTools video for example, it is a good idea to start by opening the DevTools to allow the viewer to get oriented. +- Consider what your actions are, slow down, and make them obvious. + Whenever you have to perform an action (say, click an icon), take it slow and make it obvious, so for example: + + - Move the mouse over the icon + - Highlight or zoom (not always, depending on whether it feels needed) + - Pause for a beat + - Click the icon + +- Plan zoom levels for the parts of the UI that you're going to show. + Not everyone will be able to view your video in high definition. + You will be able to zoom particular parts in post-production, but it's a good idea to zoom the app beforehand as well. + +> **Note:** Don't zoom so far that the UIs you are showing start to look unfamiliar or ugly. + +### Recording + +When recording the workflow you want to show, go through the flow smoothly and steadily. +Pause for a second or two when you are at key moments — for example, about to click on a button. +Make sure the mouse pointer doesn't obscure any icons or text that are important to what you are trying to demonstrate. + +Remember to pause for a second or two at the end, to show the result of the flow. + +> **Note:** If you are using a really simple tool like QuickTime Player and post production is not an option for some reason, you should get your windows set up in the right size to show the area you want to show. In the Firefox DevTools, you can use the [Rulers Tool](https://firefox-source-docs.mozilla.org/devtools-user/rulers/index.html) to make sure the viewport is at the right aspect ratio for the recording. + +### Post-production + +You'll be able to highlight key moments in post-production. +A highlight can consist of a couple of things, which you'll often combine: + +- Zoom in on parts of the screen. +- Fade the background. + +Highlight key moments of the workflow, especially where the detail is hard to see: clicking on a particular icon or entering a particular URL, for example. +Aim for the highlight to last for 1-2 seconds. +It's a good idea to add a short transition (200-300 milliseconds) at the starts and ends of the highlights. + +Use some restraint here: don't make the video a constant procession of zooming in and out, or viewers will get seasick. + +Crop the video to the desired aspect ratio, if required. + +### Uploading + +Videos currently have to be uploaded to YouTube to be displayed on MDN, for example the [mozhacks](https://www.youtube.com/user/mozhacks/videos) channel. +Ask a member of MDN staff to upload the video if you don't have somewhere appropriate to put it. + +> **Note:** Mark the video as "unlisted" if it doesn't make sense out of the context of the page (if it's a short video, then it probably doesn't). + +### Embedding + +Once uploaded, you can embed the video in the page using the [`EmbedYouTube`](https://github.com/mdn/yari/blob/main/kumascript/macros/EmbedYouTube.ejs) macro. +This is used by inserting the following in your page at the position you want the video to appear: + +``` +\{{EmbedYouTube("you-tube-url-slug")}} +``` + +The single property taken by the macro call is the string of characters at the end of the video URL, not the whole URL. +For example, the video embedded in our [Page inspector 3-pane mode](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/3-pane_mode/index.html) article is available at https\://www\.youtube.com/watch?v=ELS2OOUvxIw, so the required macro call looks like this: + +``` +\{{EmbedYouTube("ELS2OOUvxIw")}} +``` diff --git a/files/en-us/mdn/writing-guidelines/page-structure/index.md b/files/en-us/mdn/writing-guidelines/page-structure/index.md new file mode 100644 index 000000000000000..3264e2c99341cbe --- /dev/null +++ b/files/en-us/mdn/writing-guidelines/page-structure/index.md @@ -0,0 +1,48 @@ +--- +title: Page structure +slug: MDN/Writing_guidelines/Page_structure +page-type: mdn-writing-guide +tags: + - meta + - writing-guide +--- +{{MDNSidebar}} + +This section of MDN Web Docs writing guidelines contains all the information on _how_ our pages are structured: The different types of pages we have, what is included in them, how we use markdown, code example guidelines and more. + +To find out more about _how to contribute_ (which happens through GitHub) please refer to our [community guidelines](). + +> **Note:** All the way through this section we assume you have read the contribution guidelines and are familiar with the mdn/content repository and how to use git and GitHub. + +MDN Web Docs content is primarily held in the mdn/content repository and each page is written in a markdown format with frontmatter information at the top. + +Some content is held in other repositories; primarily code examples (such as interactive examples at the top of pages). Anything related to the platform (the website itself and _not_ the articles) is held within the mdn/yari repository. + +If you're looking for the place to update the browser compatibility tables, that data is held with mdn/browser-compat-data repository. + +## Editing an existing page + +To edit a page, you need to find the page source in our [content](https://github.com/mdn/content) repo. The easiest way to find it is to navigate to the page you want to edit, go to the bottom of the page, and click on the "Source on GitHub" link. + +For creating, moving, and removing content, please refer to [Creating, moving and deleting pages](/en-US/docs/MDN/Writing_guidelines/Creating_moving_archiving) + +### Preview changes + +If you are editing the page locally, to see what your changes look like you can go to the content repo folder, execute the CLI command `yarn start`, go to `localhost:5042` in your browser, and navigate to page and view it. Enter the title in the search box to find it easily. The previewed page will update in the browser as you edit the source. + +### Tags + +You can add or remove tags, which describe the page's content and purpose, in the "tags" list at the top of the page source. See [How to properly tag pages](/en-US/docs/MDN/Contribute/Howto/Tag), for information on which tags to apply. + +### Attach files + +To attach a file to your article, you just need to include it in the same directory as the article's `index.html` file, and include it in your page, typically via an `` element. + + +## In this section + + + +## See also + +- [MDN style guide](/en-US/docs/MDN/Guidelines/Writing_style_guide) diff --git a/files/en-us/mdn/writing-guidelines/page-structure/macros/index.md b/files/en-us/mdn/writing-guidelines/page-structure/macros/index.md new file mode 100644 index 000000000000000..e69de29bb2d1d64 diff --git a/files/en-us/mdn/writing-guidelines/page-structure/markdown/index.md b/files/en-us/mdn/writing-guidelines/page-structure/markdown/index.md new file mode 100644 index 000000000000000..ae5e7a615266cca --- /dev/null +++ b/files/en-us/mdn/writing-guidelines/page-structure/markdown/index.md @@ -0,0 +1,497 @@ +--- +title: Markdown +slug: MDN/Writing_guidelines/Page_structure/Markdown +page-type: mdn-writing-guide +tags: + - meta + - writing-guide +--- + +This page describes how we use Markdown to write documentation on MDN. We have chosen GitHub-Flavored Markdown (GFM) as a baseline, and added some extensions to support some of the things we need to do on MDN that aren't readily supported in GFM. + +## Baseline: GitHub-Flavored Markdown + +The baseline for MDN Markdown is GitHub-Flavored Markdown (GFM): . This means that for anything not otherwise specified in this page, you can refer to the GFM specification. GFM in turn is a superset of CommonMark ([https://spec.commonmark.org/](https://spec.commonmark.org/)). + +## Example code blocks + +In GFM and CommonMark, authors can use "code fences" to demarcate `
` blocks. The opening code fence may be followed by some text that is called the "info string". From the spec:
+
+> The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag.
+
+It's permissible for the info string to contain multiple words, like:
+
+````plain
+```fee fi fo fum
+// some example code
+```
+````
+
+In MDN, writers will use code fences for example code blocks. They must specify the language of the code sample using the first word of the info string, and this will be used to provide syntax highlighting for the block. The following words are supported:
+
+- `bash`
+- `batch`
+- `cpp` (for C/C++)
+- `css`
+- `html`
+- `java`
+- `js` (for JavaScript)
+- `json`
+- `php`
+- `python`
+- `sql`
+- `svg`
+- `xml`
+- `wasm` (for WebAssembly text format)
+
+For example:
+
+````plain
+```js
+const greeting = "I will get syntax highlighting";
+```
+````
+
+Writers will be able to supply any one of the following additional words, which must come after the language word:
+
+- `example-good`: style this example as a good example (one to follow)
+- `example-bad`: style this example as a bad example (one to avoid)
+- `hidden`: don't render this code block in the page. This is for use in live samples.
+
+For example:
+
+````plain
+```js example-good
+const greeting = "I'm a good example";
+```
+
+```js example-bad
+const greeting = "I'm a bad example";
+```
+````
+
+These will be rendered as:
+
+```js example-good
+const greeting = "I'm a good example";
+```
+
+```js example-bad
+const greeting = "I'm a bad example";
+```
+
+### Discussion reference
+
+This issue was resolved in .
+
+## Notes, warnings, and callouts
+
+Sometimes writers want to call special attention to some piece of content. To do this, they will use a GFM blockquote with a special first paragraph. There are three types of these: notes, warnings, and callouts.
+
+- To add a note, create a GFM blockquote whose first paragraph starts with `**Note:**`.
+- To add a warning, create a GFM blockquote whose first paragraph starts with `**Warning:**`.
+- To add a callout, create a GFM blockquote whose first paragraph starts with `**Callout:**`.
+
+Notes and warnings will render the **Note:** or **Warning:** text in the output, while callouts will not. This makes callouts a good choice when an author wants to provide a custom title.
+
+Processing of the markup works on the AST it produces, not on the exact characters provided. This means that providing `Note:` will also generate a note. However, the Markdown syntax is required as a matter of style.
+
+Multiple lines are produced by an empty block quote line in the same way as normal paragraphs. Further, multiple lines without a space are also treated like normal markdown lines, and concatenated.
+
+The blockquote can contain code blocks or other block elements.
+
+Because the text "Note:" or "Warning:" also appears in the rendered output, it has to be sensitive to translations. In practice this means that every locale supported by MDN must supply its own translation of these strings, and the platform must recognize them as indicating that the construct needs special treatment.
+
+#### Examples
+
+##### Note
+
+```plain
+> **Note:** This is how you write a note.
+>
+> It can have multiple lines.
+```
+
+This will produce the following HTML:
+
+```html
+

+  
Note: This is how you write a note.

+  
It can have multiple lines.

+

+```
+
+This HTML will be rendered as a highlighted box, like:
+
+> **Note:** This is how you write a note.
+>
+> It can have multiple lines.
+
+##### Warnings
+
+```plain
+> **Warning:** This is how you write a warning.
+>
+> It can have multiple paragraphs.
+```
+
+This will produce the following HTML:
+
+```html
+

+  
Warning: This is how you write a warning.

+  
It can have multiple paragraphs.

+

+```
+
+This HTML will be rendered as a highlighted box, like:
+
+> **Warning:** This is how you write a warning.
+>
+> It can have multiple paragraphs.
+
+##### Callouts
+
+```plain
+> **Callout:** **This is how you write a callout**.
+>
+> It can have multiple paragraphs.
+```
+
+This will produce the following HTML:
+
+```html
+

+  
This is how you write a callout.

+  
It can have multiple paragraphs.

+

+```
+
+This HTML will be rendered as a highlighted box, like:
+
+> **Callout:**
+>
+> **This is how you write a callout.**
+>
+> It can have multiple paragraphs.
+
+##### Translated warning
+
+For example, if we want to use "Warnung" for "Warning" in German, then in German pages we would write:
+
+```plain
+> Warnung: So schreibt man eine Warnung.
+```
+
+...and this will produce:
+
+```html
+

+  
Warnung: So schreibt man eine Warnung.

+

+```
+
+##### Note containing a code block
+
+This example contains a code block.
+
+````plain
+> **Note:** This is how you write a note.
+>
+> It can contain code blocks.
+>
+> ```js
+> const s = "I'm in a code block";
+> ```
+> Like that.
+````
+
+This will produce the following HTML:
+
+```html
+

+  
Note: This is how you write a note.

+  
It can contain code blocks.

+  
const s = "I'm in a code block";

+  
Like that.

+

+```
+
+This HTML will be rendered as with a code block, like:
+
+> **Note:** This is how you write a note.
+>
+> It can contain code blocks.
+>
+> ```js
+> const s = "I'm in a code block";
+> ```
+>
+> Like that.
+
+### Discussion reference
+
+This issue was resolved in .
+
+## Definition lists
+
+To create definition lists in MDN authors write a modified form of a GFM unordered list ({{HTMLElement("ul")}}). In this form:
+
+- The GFM `
    ` contains any number of top-level GFM `
  • ` elements.
+- Each of these top-level GFM `
  • ` elements must contain, as its final element, one GFM `
      ` element.
+- This final nested `
        ` must contain a single GFM `
      • ` element, whose text content must start with ": " (a colon followed by a space). This element may contain block elements, including paragraphs, code blocks, embedded lists, and notes.
+
+Each of these top-level GFM `
      • ` elements will be transformed into a
+`
        `/`
        ` pair, as follows:
+
+- The top-level GFM `
      • ` element will be parsed as a GFM `
      • ` element
+  and its internal contents will comprise the contents of the `
        `, except for the final nested `
          `, which will not be included in the `
          `.
+- The `
        • ` element in the final nested `
            ` will be parsed as a GFM `
          • ` element and its internal contents will comprise the contents of the `
            `, except for the leading ": ", which will be discarded.
+
+For example, this is a `
            `:
+
+````plain
+- term1
+    - : My description of term1
+
+- `term2`
+    - : My description of term2
+
+      It can have multiple paragraphs, and code blocks too:
+
+      ```js
+      const thing = 1;
+      ```
+````
+
+In GFM/CommonMark, this would produce the following HTML:
+
+```html
+
              
+  
            • 
+    
              term1
              
+    
                
+      
              • : My description of term1
                • 
+    
              
+  
              • 
+  
            • 
+    
              term2
              
+    
                
+      
              • 
+        
                : My description of term2
                
+        
                It can have multiple paragraphs, and code blocks too:
                
+        
                +          const thing = 1;
+        
                
+      
                • 
+    
              
+  
              • 
+
            
+```
+
+On MDN, this would produce the following HTML:
+
+```html
+
            
+  
            
+    
            term1
            
+  
            
+  
            My description of term1
            
+  
            
+    
            term2
            
+  
            
+  
            
+    
            My description of term2
            
+    
            It can have multiple paragraphs, and code blocks too:
            
+    
            +       const thing = 1;
+    
            
+  
            
+
            
+```
+
+Definition lists written using this syntax must consist of pairs of `
            `/`
            ` elements. Using this syntax, it's not possible to write a list with more than one consecutive `
            ` element or more than one consecutive `
            ` element: the parser will treat this as an error. We expect almost all definition lists on MDN will work with this limitation, and for those that do not, authors can fall back to raw HTML.
+
+As a workaround for cases where an author needs to associate multiple `
            ` items with a single `
            `, consider providing them as a single `
            ` that holds multiple terms, separated by commas, like this:
+
+```plain
+- `param1`, `param2`, `param3`
+    - : My description of params 1, 2, and 3
+```
+
+The rationale for the syntax described here is that it works well enough with tools that expect CommonMark (for example, Prettier or GitHub previews) while being reasonably easy to write and to parse.
+
+### Discussion reference
+
+This issue was resolved in .
+
+## Tables
+
+In GFM (but not CommonMark) there is a syntax for tables: . We will make use of this but:
+
+- The GFM syntax only supports a subset of the features available in HTML. If you need to use table features that are not supported in GFM, use HTML for the table.
+- If the GFM representation of the table would be more than 150 characters wide, use HTML for the table.
+- We support a special kind of table called a "properties table", which has its own CSS class and is therefore always HTML.
+
+So the general principle here is: authors should use the GFM Markdown syntax when they can, and fall back to raw HTML when they have to or when HTML is more readable. See "When to use HTML tables" below.
+
+### GFM table syntax style
+
+In GFM table syntax, authors can omit leading and trailing pipes for rows. MDN authors must include these pipes, for the sake of readability.
+
+That is, MDN authors must use this style:
+
+```plain
+| Heading 1 | Heading 2 | Heading 3 |
+|-----------|-----------|-----------|
+| cell 1    | cell 2    | cell 3    |
+| cell 4    | cell 5    | cell 6    |
+```
+
+and not this style:
+
+```plain
+Heading 1 | Heading 2 | Heading 3
+ --- | --- | ---
+cell 1    | cell 2    | cell 3
+cell 4    | cell 5    | cell 6
+```
+
+### When to use HTML tables
+
+There are three main circumstances in which authors should use HTML tables rather than GFM syntax: when the table uses features that are not supported in GFM, when the GFM table would be too wide to be readable, and when the writer wants a special type of table called a "properties table".
+
+#### Table features that are not supported in GFM
+
+The main limitations of GFM table syntax are:
+
+- GFM tables must have a header row.
+- GFM tables may not have a header column.
+- GFM won't parse GFM block elements in table cells. For example, you can't have a list in a table cell.
+- GFM doesn't support any table elements beyond ``, ``, and `

From 414a21e5e02cf6c3190b2d8825a9af638a99719c Mon Sep 17 00:00:00 2001
From: kokke 
Date: Mon, 18 Jul 2022 20:50:56 +0200
Subject: [PATCH 41/70] Fix typo (#18486)

Remove stray 'a' in "contain a separator characters like the following" -> "contain separator characters like the following"
---
 files/en-us/web/http/headers/set-cookie/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/http/headers/set-cookie/index.md b/files/en-us/web/http/headers/set-cookie/index.md
index 310ecd21681eb4a..c56b18a123a16bd 100644
--- a/files/en-us/web/http/headers/set-cookie/index.md
+++ b/files/en-us/web/http/headers/set-cookie/index.md
@@ -63,7 +63,7 @@ Set-Cookie: =; Domain=; Secure; HttpOnl
     A cookie definition begins with a name-value pair.
 
     A `` can contain any US-ASCII characters except for: the control character, space, or a tab.
-    It also must not contain a separator characters like the following: `( ) < > @ , ; : \ " / [ ] ? = { }`.
+    It also must not contain separator characters like the following: `( ) < > @ , ; : \ " / [ ] ? = { }`.
 
     A `` can optionally be wrapped in double quotes and include any US-ASCII character excluding a control character, {{glossary("Whitespace")}}, double quotes, comma, semicolon, and backslash.
 

From a15a18d3004ca52d20f1790aee7b59ad61cde9e4 Mon Sep 17 00:00:00 2001
From: de-oz <101826623+de-oz@users.noreply.github.com>
Date: Mon, 18 Jul 2022 23:52:25 +0300
Subject: [PATCH 42/70] Fix link text (#18488)

---
 files/en-us/web/css/box-shadow/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/css/box-shadow/index.md b/files/en-us/web/css/box-shadow/index.md
index 58cc4f0e8519fb4..790b2cfd2535926 100644
--- a/files/en-us/web/css/box-shadow/index.md
+++ b/files/en-us/web/css/box-shadow/index.md
@@ -89,7 +89,7 @@ To specify multiple shadows, provide a comma-separated list of shadows.
 
 ### Interpolation
 
-When animating shadows, such as when multiple shadow values on a box transition to new values on hover, the values are interpolated. {{Glossary("Interpolation")}} determines intermediate values of properties, such as the blur radius, spread radius, and color, as shadows transition.  For each shadow in a list of shadows, the color, x, y, blur, and spread transition; the color as [``](/en-US/docs/Web/CSS/color_value), and the other values as [``s](/en-US/docs/Web/CSS/length).
+When animating shadows, such as when multiple shadow values on a box transition to new values on hover, the values are interpolated. {{Glossary("Interpolation")}} determines intermediate values of properties, such as the blur radius, spread radius, and color, as shadows transition.  For each shadow in a list of shadows, the color, x, y, blur, and spread transition; the color as [``](/en-US/docs/Web/CSS/color_value), and the other values as [``](/en-US/docs/Web/CSS/length)s.
 
 In interpolating multiple shadows between two comma-separated lists of multiple box shadows, the shadows are paired, in order, with interpolation occurring between paired shadows. If the lists of shadows have different lengths, then the shorter list is padded at the end with shadows whose color is `transparent`, and X, Y, and blur are `0`, with the inset, or lack of inset, being set to match. If, in any pair of shadows, one has `inset` set and the other is does not, the entire shadow list is uninterpolated; the shadows will change to the new values without an animating effect.
 

From 633e01bd9cfe883eb668aa55fdbf528aa909a89a Mon Sep 17 00:00:00 2001
From: de-oz <101826623+de-oz@users.noreply.github.com>
Date: Mon, 18 Jul 2022 23:54:40 +0300
Subject: [PATCH 43/70] Add missing period (#18487)

---
 files/en-us/web/api/clipboarditem/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/clipboarditem/index.md b/files/en-us/web/api/clipboarditem/index.md
index c9b9445e60cedbf..6a83f51f39c3ec7 100644
--- a/files/en-us/web/api/clipboarditem/index.md
+++ b/files/en-us/web/api/clipboarditem/index.md
@@ -29,7 +29,7 @@ Access to the contents of the clipboard is gated behind the [Permissions API](/e
 ## Constructor
 
 - {{domxref("ClipboardItem.ClipboardItem", "ClipboardItem()")}}
-  - : Creates a new **`ClipboardItem`** object, with the {{Glossary("MIME type")}} as the key and {{domxref("Blob")}} as the value
+  - : Creates a new **`ClipboardItem`** object, with the {{Glossary("MIME type")}} as the key and {{domxref("Blob")}} as the value.
 
 ## Properties
 

From 0e4bf8a192fa3df72df301894570bc2ac88e890a Mon Sep 17 00:00:00 2001
From: Christopher Dignam 
Date: Mon, 18 Jul 2022 17:13:14 -0400
Subject: [PATCH 44/70] fix broken link (#18490)

---
 files/en-us/web/xpath/functions/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/xpath/functions/index.md b/files/en-us/web/xpath/functions/index.md
index 4c0d9c761dce5cf..e7359710a295bc3 100644
--- a/files/en-us/web/xpath/functions/index.md
+++ b/files/en-us/web/xpath/functions/index.md
@@ -8,7 +8,7 @@ tags:
   - XSLT
   - XSLT_Reference
 ---
-{{ XsltRef() }} The following is an annotated list of core [XPath](/en-US/docs/Web/XPath) functions and [XSLT](/en-US/XSLT)-specific additions to XPath, including a description, syntax, a list of arguments, result-type, source in the appropriate W3C Recommendation. For further information on using XPath/XSLT functions, please see the [For Further Reading](/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT) page.
+{{ XsltRef() }} The following is an annotated list of core [XPath](/en-US/docs/Web/XPath) functions and [XSLT](/en-US/docs/Web/XSLT)-specific additions to XPath, including a description, syntax, a list of arguments, result-type, source in the appropriate W3C Recommendation. For further information on using XPath/XSLT functions, please see the [For Further Reading](/en-US/docs/Web/XSLT/Transforming_XML_with_XSLT) page.
 
 - [boolean()](/en-US/docs/Web/XPath/Functions/boolean)
 - [ceiling()](/en-US/docs/Web/XPath/Functions/ceiling)

From 11f463c1c353dc9044c6d98bd561caed6bce1309 Mon Sep 17 00:00:00 2001
From: dshin-moz <102040459+dshin-moz@users.noreply.github.com>
Date: Mon, 18 Jul 2022 22:08:19 -0400
Subject: [PATCH 45/70] Remove continuity descriptions from `steps(...)`
 (#18482)

As per the spec (https://drafts.csswg.org/css-easing/#step-easing-functions), Figure 5, all step functions are right-continuous (i.e. You'd encounter solid dots approaching discontinuity from the right side). The `direction` keyword should strictly describe when the jumps (i.e. discontinuities) happen.
---
 files/en-us/web/css/easing-function/index.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/files/en-us/web/css/easing-function/index.md b/files/en-us/web/css/easing-function/index.md
index fc9574ef0d4e4f3..b3a5891453c8294 100644
--- a/files/en-us/web/css/easing-function/index.md
+++ b/files/en-us/web/css/easing-function/index.md
@@ -109,11 +109,11 @@ where:
   - : Is a strictly positive {{cssxref("<integer>")}}, representing the amount of equidistant treads composing the stepping function.
 - _direction_
 
-  - : Is a keyword indicating if it the function is [left- or right-continuous](https://en.wikipedia.org/wiki/Left-continuous#Directional_and_semi-continuity):
+  - : Is a keyword indicating when the jumps occur:
 
-    - `jump-start` denotes a left-continuous function, so that the first step or jump happens when the interpolation begins;
-    - `jump-end` denotes a right-continuous function, so that the last step or jump happens when the interpolation ends;
-    - `jump-both` denotes a right and left continuous function, includes pauses at both the 0% and 100% marks, effectively adding a step during the interpolation iteration;
+    - `jump-start` denotes that the first step or jump happens when the interpolation begins;
+    - `jump-end` denotes that the last step or jump happens when the interpolation ends;
+    - `jump-both` denotes that jumps occur at both the 0% and 100% marks, effectively adding a step during the interpolation iteration;
     - `jump-none` There is no jump on either end. Instead, holding at both the 0% mark and the 100% mark, each for 1/n of the duration
     - `start` is the equivalent of `jump-start`
     - `end` is the equivalent of `jump-end`

From 294e54fbad45e203a81fd64fb8bd4a78a7fec446 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=2E=C2=A0S=2E=C2=A0Choi?= 
Date: Mon, 18 Jul 2022 22:55:06 -0400
Subject: [PATCH 46/70] OpenType guide: font-variant-position is not mutually
 exclusive with / (#18459)

Thank you!
---
 files/en-us/web/css/css_fonts/opentype_fonts_guide/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/css/css_fonts/opentype_fonts_guide/index.md b/files/en-us/web/css/css_fonts/opentype_fonts_guide/index.md
index 60a74fe90ac7b45..8a656b44772fa80 100644
--- a/files/en-us/web/css/css_fonts/opentype_fonts_guide/index.md
+++ b/files/en-us/web/css/css_fonts/opentype_fonts_guide/index.md
@@ -96,7 +96,7 @@ While more common in script typefaces, in the below example they are used to cre
 
 Associated CSS property: {{cssxref("font-variant-position")}}
 
-Position variants are used to enable typographic superscript and subscript glyphs. These are designed to work with the surrounding text without altering the baseline or line spacing. This is one of the key benefits over using the {{htmlelement("sub")}} or {{htmlelement("sup")}} elements.
+Position variants are used to enable typographic superscript and subscript glyphs. These are designed to work with the surrounding text without altering the baseline or line spacing. This is especially useful with the {{htmlelement("sub")}} or {{htmlelement("sup")}} elements.
 
 {{EmbedGHLiveSample("css-examples/font-features/font-variant-position.html", '100%', 550)}}
 

From 6d76783b9e1bafefd3117637170171a22e07753c Mon Sep 17 00:00:00 2001
From: Masahiro FUJIMOTO 
Date: Tue, 19 Jul 2022 13:04:56 +0900
Subject: [PATCH 47/70] Fix links for other references (#18501)

---
 files/en-us/web/api/dompoint/dompoint/index.md | 2 +-
 files/en-us/web/api/dompoint/index.md          | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/files/en-us/web/api/dompoint/dompoint/index.md b/files/en-us/web/api/dompoint/dompoint/index.md
index 86bcfe6908db96d..e86b7f8c8f90644 100644
--- a/files/en-us/web/api/dompoint/dompoint/index.md
+++ b/files/en-us/web/api/dompoint/dompoint/index.md
@@ -68,6 +68,6 @@ newTopLeft.y += 100;
 
 ## See also
 
-- {{domxref("DOMPointReadOnly.DOMPoint", "DOMPointReadOnly()")}}
+- {{domxref("DOMPointReadOnly.DOMPointReadOnly", "DOMPointReadOnly()")}}
 - {{domxref("DOMRect")}}
 - {{domxref("DOMMatrix")}}
diff --git a/files/en-us/web/api/dompoint/index.md b/files/en-us/web/api/dompoint/index.md
index f647d9ada942ce8..434faf0eebe278c 100644
--- a/files/en-us/web/api/dompoint/index.md
+++ b/files/en-us/web/api/dompoint/index.md
@@ -42,13 +42,13 @@ _`DOMPoint` inherits methods from its parent, {{domxref("DOMPointReadOnly")}}._
 
 _`DOMPoint` inherits properties from its parent, {{domxref("DOMPointReadOnly")}}._
 
-- {{domxref("DOMPointReadOnly.x", "DOMPoint.x")}}
+- {{domxref("DOMPoint.x")}}
   - : The `x` coordinate of the `DOMPoint`.
-- {{domxref("DOMPointReadOnly.y", "DOMPoint.y")}}
+- {{domxref("DOMPoint.y")}}
   - : The `y` coordinate of the `DOMPoint`.
-- {{domxref("DOMPointReadOnly.z", "DOMPoint.z")}}
+- {{domxref("DOMPoint.z")}}
   - : The `z` coordinate of the `DOMPoint`.
-- {{domxref("DOMPointReadOnly.w", "DOMPoint.w")}}
+- {{domxref("DOMPoint.w")}}
   - : The perspective value of the `DOMPoint`.
 
 ## Examples

From 6ed44f287d136ebad919126f4d627f96bc0ea913 Mon Sep 17 00:00:00 2001
From: Onkar Ruikar <87750369+OnkarRuikar@users.noreply.github.com>
Date: Tue, 19 Jul 2022 09:41:35 +0530
Subject: [PATCH 48/70] update a broken link (#18500)

---
 .../web/api/websockets_api/writing_websocket_server/index.md    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/web/api/websockets_api/writing_websocket_server/index.md b/files/en-us/web/api/websockets_api/writing_websocket_server/index.md
index d348b43cdafb1cc..5652601ca27b7f4 100644
--- a/files/en-us/web/api/websockets_api/writing_websocket_server/index.md
+++ b/files/en-us/web/api/websockets_api/writing_websocket_server/index.md
@@ -18,7 +18,7 @@ This server conforms to [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455
 
 ## First steps
 
-WebSockets communicate over a [TCP (Transmission Control Protocol)](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) connection. Luckily, C# has a [TcpListener](https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.tcplistener&view=net-6.0) class which does as the name suggests. It is in the *System.Net.Sockets* namespace.
+WebSockets communicate over a [TCP (Transmission Control Protocol)](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) connection. Luckily, C# has a [TcpListener](https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.tcplistener?view=net-6.0) class which does as the name suggests. It is in the *System.Net.Sockets* namespace.
 
 > **Note:** It is a good idea to include the namespace with the `using` keyword in order to write less. It allows usage of a namespace's classes without typing the full namespace every time.
 

From 32823e7b791755d7a67d58692cc95224888b3fdf Mon Sep 17 00:00:00 2001
From: Onkar Ruikar <87750369+OnkarRuikar@users.noreply.github.com>
Date: Tue, 19 Jul 2022 09:49:18 +0530
Subject: [PATCH 49/70] Comment out ellipsis in code blocks (#18496)

---
 .../api/stylepropertymapreadonly/foreach/index.md  | 14 +++++++-------
 files/en-us/web/api/stylesheet/disabled/index.md   |  4 ++--
 files/en-us/web/api/stylesheetlist/index.md        |  2 +-
 .../en-us/web/api/subtlecrypto/derivebits/index.md |  4 ++--
 files/en-us/web/api/touch/radiusx/index.md         |  2 +-
 .../web/api/visualviewport/resize_event/index.md   |  4 ++--
 .../web/api/visualviewport/scroll_event/index.md   |  4 ++--
 .../api/vrdisplay/cancelanimationframe/index.md    |  2 +-
 .../en-us/web/api/vrdisplay/getframedata/index.md  |  2 +-
 files/en-us/web/api/vrdisplay/getpose/index.md     |  2 +-
 .../api/vrdisplay/requestanimationframe/index.md   |  2 +-
 files/en-us/web/api/vrdisplay/submitframe/index.md |  2 +-
 files/en-us/web/api/vrframedata/timestamp/index.md |  2 +-
 files/en-us/web/api/vrlayerinit/index.md           |  6 +++---
 .../web/api/vrpose/angularacceleration/index.md    |  2 +-
 .../en-us/web/api/vrpose/angularvelocity/index.md  |  2 +-
 .../web/api/vrpose/linearacceleration/index.md     |  2 +-
 files/en-us/web/api/vrpose/linearvelocity/index.md |  2 +-
 .../using_the_web_animations_api/index.md          | 10 +++++-----
 .../api/web_audio_api/advanced_techniques/index.md |  2 +-
 .../api/web_audio_api/using_iir_filters/index.md   |  6 ++----
 .../en-us/web/api/web_authentication_api/index.md  |  2 +-
 .../using_the_web_speech_api/index.md              |  4 ++--
 .../api/web_workers_api/using_web_workers/index.md |  8 ++------
 .../api/webgl2renderingcontext/beginquery/index.md |  2 +-
 .../bindvertexarray/index.md                       |  6 ++++--
 .../createvertexarray/index.md                     |  6 ++++--
 .../webgl2renderingcontext/deletequery/index.md    |  2 +-
 .../webgl2renderingcontext/deletesampler/index.md  |  2 +-
 .../api/webgl2renderingcontext/deletesync/index.md |  2 +-
 30 files changed, 55 insertions(+), 57 deletions(-)

diff --git a/files/en-us/web/api/stylepropertymapreadonly/foreach/index.md b/files/en-us/web/api/stylepropertymapreadonly/foreach/index.md
index 240a42f02663f4c..604f594c292e636 100644
--- a/files/en-us/web/api/stylepropertymapreadonly/foreach/index.md
+++ b/files/en-us/web/api/stylepropertymapreadonly/foreach/index.md
@@ -22,19 +22,19 @@ provided function once for each element of {{domxref('StylePropertyMapReadOnly')
 
 ```js
 // Arrow function
-forEach((currentValue) => { /* ... */ } )
-forEach((currentValue, index) => { /* ... */ } )
-forEach((currentValue, index, array) => { /* ... */ } )
+forEach((currentValue) => { /* … */ } )
+forEach((currentValue, index) => { /* … */ } )
+forEach((currentValue, index, array) => { /* … */ } )
 
 // Callback function
 forEach(callbackFn)
 forEach(callbackFn, thisArg)
 
 // Inline callback function
-forEach(function(currentValue) { /* ... */ })
-forEach(function(currentValue, index) { /* ... */ })
-forEach(function(currentValue, index, array){ /* ... */ })
-forEach(function(currentValue, index, array) { /* ... */ }, thisArg)
+forEach(function(currentValue) { /* … */ })
+forEach(function(currentValue, index) { /* … */ })
+forEach(function(currentValue, index, array){ /* … */ })
+forEach(function(currentValue, index, array) { /* … */ }, thisArg)
 ```
 
 ### Parameters
diff --git a/files/en-us/web/api/stylesheet/disabled/index.md b/files/en-us/web/api/stylesheet/disabled/index.md
index c8177ae8f87494e..13a2df229a82bd6 100644
--- a/files/en-us/web/api/stylesheet/disabled/index.md
+++ b/files/en-us/web/api/stylesheet/disabled/index.md
@@ -28,9 +28,9 @@ A boolean.
 ## Examples
 
 ```js
-// If the stylesheet is disabled...
+// If the stylesheet is disabled
 if (stylesheet.disabled) {
-  // ... apply styles in-line.
+  // Apply styles in-line
 }
 ```
 
diff --git a/files/en-us/web/api/stylesheetlist/index.md b/files/en-us/web/api/stylesheetlist/index.md
index d1d697ac96a7c99..1df606ad530e3fb 100644
--- a/files/en-us/web/api/stylesheetlist/index.md
+++ b/files/en-us/web/api/stylesheetlist/index.md
@@ -49,7 +49,7 @@ const allCSS = [...document.styleSheets]
         .map(rule => rule.cssText)
         .join('');
     } catch (e) {
-      console.log('Access to stylesheet %s is denied. Ignoring...', styleSheet.href);
+      console.log('Access to stylesheet %s is denied. Ignoring…', styleSheet.href);
     }
   })
   .filter(Boolean)
diff --git a/files/en-us/web/api/subtlecrypto/derivebits/index.md b/files/en-us/web/api/subtlecrypto/derivebits/index.md
index d055f4aced38130..e449c6c69fb5eeb 100644
--- a/files/en-us/web/api/subtlecrypto/derivebits/index.md
+++ b/files/en-us/web/api/subtlecrypto/derivebits/index.md
@@ -113,7 +113,7 @@ async function deriveSharedSecret(privateKey, publicKey) {
   sharedSecretValue.addEventListener("animationend", () => {
     sharedSecretValue.classList.remove("fade-in");
   });
-  sharedSecretValue.textContent = `${buffer}...[${sharedSecret.byteLength} bytes total]`;
+  sharedSecretValue.textContent = `${buffer}…[${sharedSecret.byteLength} bytes total]`;
 }
 
 // Generate 2 ECDH key pairs: one for Alice and one for Bob
@@ -197,7 +197,7 @@ async function getDerivedBits() {
   derivedBitsValue.addEventListener("animationend", () => {
     derivedBitsValue.classList.remove("fade-in");
   });
-  derivedBitsValue.textContent = `${buffer}...[${derivedBits.byteLength} bytes total]`;
+  derivedBitsValue.textContent = `${buffer}…[${derivedBits.byteLength} bytes total]`;
 }
 
 const deriveBitsButton = document.querySelector(".pbkdf2 .derive-bits-button");
diff --git a/files/en-us/web/api/touch/radiusx/index.md b/files/en-us/web/api/touch/radiusx/index.md
index 5d91ae55872b177..5e68815c6fe2c10 100644
--- a/files/en-us/web/api/touch/radiusx/index.md
+++ b/files/en-us/web/api/touch/radiusx/index.md
@@ -27,7 +27,7 @@ This example illustrates using the {{domxref("Touch")}} interface's {{domxref("T
 The following simple code snippet, registers a single handler for the {{domxref("Document/touchstart_event", "touchstart")}}, {{event("touchmove")}} and {{event("touchend")}} events. When the `src` element is touched, the element's width and height will be calculate based on the touch point's `radiusX` and `radiusY` values and the element will then be rotated using the touch point's `rotationAngle`.
 
 ```html
-
             ... 
            
+
             … 
            
 ```
 
 ```js
diff --git a/files/en-us/web/api/visualviewport/resize_event/index.md b/files/en-us/web/api/visualviewport/resize_event/index.md
index a48ec426d703b36..c75bd01e3ad72f3 100644
--- a/files/en-us/web/api/visualviewport/resize_event/index.md
+++ b/files/en-us/web/api/visualviewport/resize_event/index.md
@@ -34,7 +34,7 @@ You can use the `resize` event in an [`addEventListener`](/en-US/docs/Web/API/Ev
 
 ```js
 visualViewport.addEventListener('resize', function() {
-  /* ... */
+  // …
 });
 ```
 
@@ -42,7 +42,7 @@ Or use the `onresize` event handler property:
 
 ```js
 visualViewport.onresize = function() {
-  /* ... */
+  // …
 };
 ```
 
diff --git a/files/en-us/web/api/visualviewport/scroll_event/index.md b/files/en-us/web/api/visualviewport/scroll_event/index.md
index 51deba85292dc4b..4b1272d5df6979a 100644
--- a/files/en-us/web/api/visualviewport/scroll_event/index.md
+++ b/files/en-us/web/api/visualviewport/scroll_event/index.md
@@ -34,7 +34,7 @@ You can use the `scroll` event in an [`addEventListener`](/en-US/docs/Web/API/Ev
 
 ```js
 visualViewport.addEventListener('scroll', function() {
-  /* ... */
+  // …
 });
 ```
 
@@ -42,7 +42,7 @@ Or use the `onscroll` event handler property:
 
 ```js
 visualViewport.onscroll = function() {
-  /* ... */
+  // …
 };
 ```
 
diff --git a/files/en-us/web/api/vrdisplay/cancelanimationframe/index.md b/files/en-us/web/api/vrdisplay/cancelanimationframe/index.md
index 52e6516b4878f4a..9c2e3b2a46592a6 100644
--- a/files/en-us/web/api/vrdisplay/cancelanimationframe/index.md
+++ b/files/en-us/web/api/vrdisplay/cancelanimationframe/index.md
@@ -93,7 +93,7 @@ function drawVRScene() {
   // WebVR: Request the next frame of the animation
   vrSceneFrame = vrDisplay.requestAnimationFrame(drawVRScene);
 
-  // ...
+  // …
 }
 ```
 
diff --git a/files/en-us/web/api/vrdisplay/getframedata/index.md b/files/en-us/web/api/vrdisplay/getframedata/index.md
index e3181574f69152b..36285fc842f208a 100644
--- a/files/en-us/web/api/vrdisplay/getframedata/index.md
+++ b/files/en-us/web/api/vrdisplay/getframedata/index.md
@@ -94,7 +94,7 @@ function drawVRScene() {
     // draw the view for each eye
   }
 
-  // ...
+  // …
 
   // WebVR: Indicate that we are ready to present the rendered frame to the VR display
   vrDisplay.submitFrame();
diff --git a/files/en-us/web/api/vrdisplay/getpose/index.md b/files/en-us/web/api/vrdisplay/getpose/index.md
index 1e9c89a59fe0a93..b0b6470897097f9 100644
--- a/files/en-us/web/api/vrdisplay/getpose/index.md
+++ b/files/en-us/web/api/vrdisplay/getpose/index.md
@@ -53,7 +53,7 @@ if(navigator.getVRDisplays) {
       // Return the current VRPose object for the display
       const pose = vrDisplay.getPose();
 
-      // ...
+      // …
 
     }
   });
diff --git a/files/en-us/web/api/vrdisplay/requestanimationframe/index.md b/files/en-us/web/api/vrdisplay/requestanimationframe/index.md
index fe6b1effca9ec75..0151234f1c3a298 100644
--- a/files/en-us/web/api/vrdisplay/requestanimationframe/index.md
+++ b/files/en-us/web/api/vrdisplay/requestanimationframe/index.md
@@ -94,7 +94,7 @@ function drawVRScene() {
     // draw the view for each eye
   }
 
-  // ...
+  // …
 
   // WebVR: Indicate that we are ready to present the rendered frame to the VR display
   vrDisplay.submitFrame();
diff --git a/files/en-us/web/api/vrdisplay/submitframe/index.md b/files/en-us/web/api/vrdisplay/submitframe/index.md
index 207d79d2982a2c7..abf4e6493561164 100644
--- a/files/en-us/web/api/vrdisplay/submitframe/index.md
+++ b/files/en-us/web/api/vrdisplay/submitframe/index.md
@@ -92,7 +92,7 @@ function drawVRScene() {
     // draw the view for each eye
   }
 
-  // ...
+  // …
 
   // WebVR: Indicate that we are ready to present the rendered frame to the VR display
   vrDisplay.submitFrame();
diff --git a/files/en-us/web/api/vrframedata/timestamp/index.md b/files/en-us/web/api/vrframedata/timestamp/index.md
index 22f0e3a6c549e07..2ed14145b6a8f4a 100644
--- a/files/en-us/web/api/vrframedata/timestamp/index.md
+++ b/files/en-us/web/api/vrframedata/timestamp/index.md
@@ -57,7 +57,7 @@ function drawVRScene() {
   // and do something with it
   framedata.timestamp
 
-  // ...
+  // …
 
   // WebVR: Indicates that we are ready to present the rendered frame to the VR display
   vrDisplay.submitFrame();
diff --git a/files/en-us/web/api/vrlayerinit/index.md b/files/en-us/web/api/vrlayerinit/index.md
index 53b6b23d2f560f3..97109decedf90f0 100644
--- a/files/en-us/web/api/vrlayerinit/index.md
+++ b/files/en-us/web/api/vrlayerinit/index.md
@@ -52,7 +52,7 @@ if(navigator.getVRDisplays) {
           // Here it returns an array of VRLayerInit objects
           layers = vrDisplay.getLayers();
 
-          // ...
+          // …
         });
       });
     }
@@ -64,8 +64,8 @@ if(navigator.getVRDisplays) {
 
 ```
 {
-  leftBounds : [ ... ],
-  rightBounds: [ ... ],
+  leftBounds : [ /* … */ ],
+  rightBounds: [ /* … */ ],
   source: canvasReference
 }
 ```
diff --git a/files/en-us/web/api/vrpose/angularacceleration/index.md b/files/en-us/web/api/vrpose/angularacceleration/index.md
index 48111c4babcefdc..f0f5ec77698a68a 100644
--- a/files/en-us/web/api/vrpose/angularacceleration/index.md
+++ b/files/en-us/web/api/vrpose/angularacceleration/index.md
@@ -46,7 +46,7 @@ function drawVRScene() {
   const aaz = angAcc[2];
 
   // render the scene
-  // ...
+  // …
 
   // WebVR: submit the rendered frame to the VR display
   vrDisplay.submitFrame();
diff --git a/files/en-us/web/api/vrpose/angularvelocity/index.md b/files/en-us/web/api/vrpose/angularvelocity/index.md
index ddaad6ad5ad4ea5..a93a81eb7ff53a2 100644
--- a/files/en-us/web/api/vrpose/angularvelocity/index.md
+++ b/files/en-us/web/api/vrpose/angularvelocity/index.md
@@ -46,7 +46,7 @@ function drawVRScene() {
   const avz = angVel[2];
 
   // render the scene
-  // ...
+  …
 
   // WebVR: submit the rendered frame to the VR display
   vrDisplay.submitFrame();
diff --git a/files/en-us/web/api/vrpose/linearacceleration/index.md b/files/en-us/web/api/vrpose/linearacceleration/index.md
index d000dba29c00a84..158837e970f9a0e 100644
--- a/files/en-us/web/api/vrpose/linearacceleration/index.md
+++ b/files/en-us/web/api/vrpose/linearacceleration/index.md
@@ -46,7 +46,7 @@ function drawVRScene() {
   const laz = linAcc[2];
 
   // render the scene
-  // ...
+  // …
 
   // WebVR: submit the rendered frame to the VR display
   vrDisplay.submitFrame();
diff --git a/files/en-us/web/api/vrpose/linearvelocity/index.md b/files/en-us/web/api/vrpose/linearvelocity/index.md
index b231617fdc170c4..d01f5ab8d5be8d1 100644
--- a/files/en-us/web/api/vrpose/linearvelocity/index.md
+++ b/files/en-us/web/api/vrpose/linearvelocity/index.md
@@ -46,7 +46,7 @@ function drawVRScene() {
   const lvz = linVel[2];
 
   // render the scene
-  // ...
+  // …
 
   // WebVR: submit the rendered frame to the VR display
   vrDisplay.submitFrame();
diff --git a/files/en-us/web/api/web_animations_api/using_the_web_animations_api/index.md b/files/en-us/web/api/web_animations_api/using_the_web_animations_api/index.md
index e059d68648dbe3f..23fb75de7fe5bb1 100644
--- a/files/en-us/web/api/web_animations_api/using_the_web_animations_api/index.md
+++ b/files/en-us/web/api/web_animations_api/using_the_web_animations_api/index.md
@@ -342,15 +342,15 @@ const endGame = function() {
 
   if (aliceHeight <= .333){
     // Alice got smaller!
-    // ...
+    // …
 
   } else if (aliceHeight >= .666) {
     // Alice got bigger!
-    // ...
+    // …
 
   } else {
     // Alice didn't change significantly
-    // ...
+    // …
 
   }
 }
@@ -368,11 +368,11 @@ CSS Animations and Transitions have their own event listeners, and these are als
 Here we set the callbacks for the cake, bottle, and Alice to fire the `endGame` function:
 
 ```js
-// When the cake or bottle runs out...
+// When the cake or bottle runs out
 nommingCake.onfinish = endGame;
 drinking.onfinish = endGame;
 
-// ...or Alice reaches the end of her animation
+// Alice reaches the end of her animation
 aliceChange.onfinish = endGame;
 ```
 
diff --git a/files/en-us/web/api/web_audio_api/advanced_techniques/index.md b/files/en-us/web/api/web_audio_api/advanced_techniques/index.md
index fb7a6ae3ba6e00d..1136eb36df7b83b 100644
--- a/files/en-us/web/api/web_audio_api/advanced_techniques/index.md
+++ b/files/en-us/web/api/web_audio_api/advanced_techniques/index.md
@@ -430,7 +430,7 @@ We can now use `setupSample()` like so:
 setupSample()
     .then((sample) => {
         // sample is our buffered file
-        // ...
+        // …
 });
 ```
 
diff --git a/files/en-us/web/api/web_audio_api/using_iir_filters/index.md b/files/en-us/web/api/web_audio_api/using_iir_filters/index.md
index 86a6f1575a06d13..b7e3c71b3cbdf18 100644
--- a/files/en-us/web/api/web_audio_api/using_iir_filters/index.md
+++ b/files/en-us/web/api/web_audio_api/using_iir_filters/index.md
@@ -97,8 +97,7 @@ And the `click` event listener starts like so:
 playButton.addEventListener('click', function() {
     if (this.dataset.playing === 'false') {
         srcNode = playSourceNode(audioCtx, sample);
-        // ...
-    }   
+        // …
 }, false);
 ```
 
@@ -115,8 +114,7 @@ filterButton.addEventListener('click', function() {
     if (this.dataset.filteron === 'false') {
         srcNode.disconnect(audioCtx.destination);
         srcNode.connect(iirfilter).connect(audioCtx.destination);
-        // ...
-    }
+        // …
 }, false);
 ```
 
diff --git a/files/en-us/web/api/web_authentication_api/index.md b/files/en-us/web/api/web_authentication_api/index.md
index 52e1072faf6e86c..f57d8628ad7791f 100644
--- a/files/en-us/web/api/web_authentication_api/index.md
+++ b/files/en-us/web/api/web_authentication_api/index.md
@@ -180,7 +180,7 @@ navigator.credentials.create(createCredentialDefaultArgs)
         console.log("NEW CREDENTIAL", cred);
 
         // normally the credential IDs available for an account would come from a server
-        // but we can just copy them from above...
+        // but we can just copy them from above…
         const idList = [{
             id: cred.rawId,
             transports: ["usb", "nfc", "ble"],
diff --git a/files/en-us/web/api/web_speech_api/using_the_web_speech_api/index.md b/files/en-us/web/api/web_speech_api/using_the_web_speech_api/index.md
index 2b14841301ef6b9..c73f46343d3e9ad 100644
--- a/files/en-us/web/api/web_speech_api/using_the_web_speech_api/index.md
+++ b/files/en-us/web/api/web_speech_api/using_the_web_speech_api/index.md
@@ -43,7 +43,7 @@ The HTML and CSS for the app is really trivial. We have a title, instructions pa
 
            Speech color changer
            
 
            Tap/click then say a color to change the background color of the app.
            
 
            
-  
            ...diagnostic messages
            
+  
            …diagnostic messages
            
 
            
 ```
 
@@ -68,7 +68,7 @@ const SpeechRecognitionEvent = window.SpeechRecognitionEvent || webkitSpeechReco
 The next part of our code defines the grammar we want our app to recognize. The following variable is defined to hold our grammar:
 
 ```js
-const colors = [ 'aqua' , 'azure' , 'beige', 'bisque', 'black', 'blue', 'brown', 'chocolate', 'coral', /* ... */ ];
+const colors = [ 'aqua' , 'azure' , 'beige', 'bisque', 'black', 'blue', 'brown', 'chocolate', 'coral', /* … */ ];
 const grammar = '#JSGF V1.0; grammar colors; public  = ' + colors.join(' | ') + ' ;'
 ```
 
diff --git a/files/en-us/web/api/web_workers_api/using_web_workers/index.md b/files/en-us/web/api/web_workers_api/using_web_workers/index.md
index 223fd03bb93fdf4..2decaa24072ef37 100644
--- a/files/en-us/web/api/web_workers_api/using_web_workers/index.md
+++ b/files/en-us/web/api/web_workers_api/using_web_workers/index.md
@@ -44,9 +44,7 @@ For slightly more controlled error handling and backwards compatibility, it is a
 
 ```js
 if (window.Worker) {
-
-  // ...
-
+  // …
 }
 ```
 
@@ -606,9 +604,7 @@ There is not an "official" way to embed the code of a worker within a web page,
 
            `, and ``.
+- GFM doesn't support any table element attributes like `colspan`, `rowspan`, or `scope`.
+
+If an author needs to use any of the unsupported features, they should write the table in HTML.
+
+Note that we don't recommend the general use of `
            ` elements on tables, since that would also rule out the GFM syntax.
+
+#### GFM table maximum width
+
+Even when a table could be written in GFM it is sometimes better to use HTML, because GFM uses an "ASCII art" approach to tables that is not readable when table rows get long. For example, consider this table:
+
+```html
+  
+    
+      
+      
+      
+      
+      
+      
+    
+    
+      
+      
+      
+      
+      
+      
+    
+
            A heading 1A heading 2A heading 3A heading 4A heading 5A heading 6
            Something shortishSomething much longer that really goes into a lot of detail about something, so much so that the table formatting starts to look bad in GFM format.Something shortishAnother cell with lots of text in it, that also really goes into a lot of detail about something, so much so that the table formatting starts to look bad in GFM format.Something shortishSomething shortish
            
+```
+
+In GFM this will look like:
+
+```plain
+  | A heading 1        | A heading 2                                                                                                                                         | A heading 3        | A heading 4                                                                                                                                                              | A heading 5        | A heading 6        |
+  | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------------ |
+  | Something shortish | Something much longer that really goes into a lot of detail about something, so much so that the table formatting starts to look bad in GFM format. | Something shortish | Another cell with lots of text in it, that also really goes into a lot of detail about something, so much so that the table formatting starts to look bad in GFM format. | Something shortish | Something shortish |
+```
+
+In a case like this it would be better to use HTML.
+
+This leads us to the following guideline: _if the Markdown representation of the table would be more than 150 characters wide, use HTML for the table_.
+
+#### Properties tables
+
+Properties tables are a specific type of table used for displaying structured property-value content across a set of pages of a particular type. For example, all event pages have a properties table listing common information about the event: whether it bubbles, whether it is cancellable, and so on.
+
+These tables have two columns: the first column is the header column and lists the properties, and the second column lists their values for this particular item. For example, here's the properties table for the {{domxref("XMLHttpRequest/progress_event", "progress")}} event of the {{domxref("XMLHttpRequest")}} interface:
+
+
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
            BubblesNo
            CancelableNo
            Interface{{domxref("ProgressEvent")}}
            Event handler property
+        {{domxref("XMLHttpRequestEventTarget/onprogress", "onprogress")}}
+      
            
+
+These pages can't be represented in GFM anyway, because they have a header column. Writers should therefore use HTML. To get the special styling, writers should apply the `"properties"` class to the table:
+
+```html
+
+```
+
+### Discussion reference
+
+This issue was resolved in , , and .
+
+## Superscript and subscript
+
+Writers will be able to use the HTML {{HTMLElement("sup")}} and {{HTMLElement("sub")}} elements if necessary, but should use alternatives if possible. In particular:
+
+- For exponentiation, use the caret: `2^53`.
+- For ordinal expressions like 1
+
+  st
+
+  , prefer words like "first".
+
+- For footnotes, don't mark up the footnote references with, e.g., `[1]`; it's unnecessary.
+
+### Discussion reference
+
+This issue was resolved in .
+
+## Page summary
+
+The _page summary_ is the first "content" paragraph in a page—the first text that appears after the page front matter and any [sidebar or page banner macros](#kumascript).
+
+This summary is used for search engine optimization (SEO) and also automatically included alongside page listings by some macros.
+The first paragraph should therefore be both succinct and informative.
+
+### Discussion reference
+
+This issue was resolved in .
+
+## KumaScript
+
+Writers will be able to include KumaScript macro calls in prose content:
+
+```plain
+
+The **`margin`** [CSS](/en-US/docs/Web/CSS) property
+sets the margin area on all four sides of an element. It is a shorthand for
+\{{cssxref("margin-top")}}, \{{cssxref("margin-right")}}, \{{cssxref("margin-bottom")}},
+and \{{cssxref("margin-left")}}.
+
+\{{EmbedInteractiveExample("pages/css/margin.html")}}
+
+The top and bottom margins have no effect on replaced inline elements, such as
+\{{HTMLElement("span")}} or \{{HTMLElement("code")}}.
+```
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/apiref-links.png b/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/apiref-links.png
new file mode 100644
index 0000000000000000000000000000000000000000..f4456db4298d4a8d9ff83e6c6030b11a021fc209
GIT binary patch
literal 6176
zcma)Ac{o)6zZWSfB}+mP5oL)eWzCvtGIqiYGS(RTkbTL%Cd*i|W|xt*VQi6gsK~w>
z`#QuJW0<-6e!sux{_cJ5z0W<*`#k5oKksusf4r9W`#dL73-pYEo`ar>ii!cCuA)Ol
zbw>2`45XtuUEzxez@1*s+9+x$Qc+dLUp#(Adzznd(|M*uh5UYFjf#qfO6!H5>OSF+
zLLpHILk=Ka3T2-}p%5s44vjzQ;r{6z2|IbZg#WGqa$erp%^Li@yt2L*B3vNOzM$>H1CC-&$LuP@o{)pLhy>AV&jada~IO5)y$YP_{SLDU?lL
zP2B_hJ{0CeIiA3N38#=(8&;1sEK4*%HWbQEg^$tN)?Q~^;Ne(NYUldlbaiBi?+I>r
zf262#mN=C6#=+Xy#?o$xNGZmw`*8cMz)g`er+GZDEq@ByA%zh
zn60+=vnLe7EPC&N^wA@MveCTPpB~q|c<_5GCMwjYeA-=8e|z^Jy>Wp;*eeZn4vCI{
z$8h`Y@-Qmt5*)=Jc9VpBTS@!w8b2_Fh&i+lrGAcIAv&21r$Or^2
z^|1Bz^K>wbicW|pt@p0<=T8=UT4nUT2?}?InQ7>LtoHSbad9|VtTKn1J3!r_(H-lA
z!~Rqs-13rt{;&RTWtqV)AW)!1V3A)=M|VM3b2N0kHLWN<)E(xm0eVxAU)Z`uaW~5`
zGu9394Vf$tA3!2jwuq=V)_c?K8b)>t72z|Zy)GfK8b*HpF`qkUwv8O#IK+402@Ab_
zy}te#`;^^8U$Zb>-ArpQ9oOgp3&`QtqVd~C4OpsnY;Sr}DhQe#T|ZfhcmsVC6cU?j
zX_TGs9=1M&iZZfA*H`>N*B>nOxh0gY{H7Rz12qG_po>22?|gq(P@LEN-5vhP2pSs?
z(}#l0vIBB`qZ6CHc4w7#Rn#_SL7f}23QK1xVU{5^MeiJfKa}>MHH;B0S%pLRgWa9c
z4;i^ZU#8H*>qDDE9mA7vQW{oCoPtzTEX@EFMZGr@o0$w+dZVm?Mjqon*PMm!+|q2v
zPRwDc(N9~8i-n_t^RDrK3X4=odKaA6cTUyw_E^MMhoP4+e!)tQ)b8xSck5%FV(K)C
z^dCdUYC@v)&BN+!Wjc&w1DXg;kg5hr@vWMN=#{=rG;Z2$cG_$9gWI-WwdW5wkKpW6
zFyk4l5;)?b3y&zvw@?%#;`RbPI0~iqO@9d(uMKw_1DvH2ylD8#-kTbl)@*V`>x&~x
zL0J?RVX8m_i}%XGiMn63{Q!kEM~T
zD2UB-XSIQFFE6^$0cayEZ(3>NSxY|7M~zqB?!3lUjr9D4>Z~jx@OL(J1WTJv*@YfO
zyl)vO#tSg%l5!M#%`h+0U!HGgt)^)WLzJPa3JUl;qN1hel7f+Ag4b>B*fqy!^&oXv
zZ*_oE%-vs}!~~U8w*1WQh4h(17f)euOp3^TLpk(0PB2qqXJ)9tl1ib%*g5AH(os67
z%2eY*53HrA(W-g|&b-q8k>+{p06R#BXprcW_?HOntmQ3irxYXH^C!x&B44V3pV*3;
zqaHCEJ+OtecDOKv5DpmXQzrQ6wXVG!yhfm$ReMq
zb%Jw#1q%vp&Ohrs97WdVzbxP2;pb$phavbn}ANqK_=h8KQ
z`V)s`$ZL)U^JsS#eg)i-a*c7v@?|F78Q6&SJw6%YCwVdFc4)0zJK~nFjf&#mRGu=a
z#mM$IvAMD_7}^fgf2DtT#+!X(z21x!KLT7~{5d>sRMO+Aq={ehoyCwd2YQLi3dNm>>p_2a4IZe^Kdr*oR{=jB6#S+N%COU{u~#uy&6A62?R$njdU<*WP%uZ)Es!tAwBf
z`)k+8U=b1Jf=~Vzri`BUcUwT7yc_<;A+7)uUA+f41_SLMzk8<3q$dqIv@*t39|^*`
zIYh^!%ASPMK0agk{(Gd$K$k*!F-93^Xu!UvQaR%MrNhqb@sAaJK-8OLgZw>
zwc9W9kJSiU!ScfPRk4-6+fW94y&7<{;mHGBL%D@VQa%PvRG6g@4=jyA&uJsDHjfMDb)n*!6&B%h6?v#2Nc|is48n<*!4WuflUE1Soc!AZ%WZwPov=GtG6$Pv#<^NU-
zTbQFCu5_?eG!D4EKcZAr%;7lXn*K8WcRO_vyV88AIqIN!-0bp#rHepq_{^Bvff7jo
z3{jJ+E$KgcVYn+y6w$RVzU+;ef9{r1)j}h=J^s_={&$m2F;uD|W7Ug|7Ak*y&#V%*
zgG2`~2eF9LBY{iRHWC$!nc8`1Uj9fhUu57t?=@*kR;jC)L;`;eI7j4dn&tDL!g_|I
z4gD)met+Ra2n)wcL*O&m?IX6!$}Wu-S*llg7K5uE2oNQ&HR
z;MpKMB1NTN$T0qLd!0$6!576s)iuTUN;ug{-l*N+qJik6s)uiT8G&CZ1#fvZ<}tp5
z{bwYR7iTo#LPXB5h8B5lu_}(-#HX6dMjR#cFKg!yZf!jJmQYwSv-YD(DT(E~fE$qh
zaFqBV(SVLP(@0~mgP8xgILXRi&X`U&%~ud$|4TVO>>`;h_`c%d_lV$A0shk`Zi)US
z$A856gbxYi%)H6gvOE12V>Y?n5$nk3u50=!alUFc^j?_&8`5`6Uibq4c8H|plMMLy
zmdl+3ekO>a{mbMlF|5Oa=5EX`Cyi#b$^LwgX>*?6dsXUx8N^}iXNrgdxoOpFxf`FE
zNd7(-;~}$3WQq@dZ*bE#ph}dr%6s2I`JP}SU1pWoQmacHM{p@Jy9~u8GGJ%HJg1mu
z>Sp3#dpF)aY7D*Vgxn*QgiZS;A5EJMkEJ;q4N{0EI
z=;;z?b%kHM(%bNPpaZhJ78cNL9QPxUd?~P!F5E#14Deg&LM5CSwQ|Uo2cVh$7Hf7E
zl^|`+@zp!ARc)44ZBIo@u5Hznq&NGqfcfCFh6j5g3-r^Hh<6_#`BtNBJGH!VcpNE^=mlWzoWMhq
z0~vfX2%QS`sFcj2c!@PuY{CQ5YTgqSrY{~_Lok(Vp5~ktK$KP64iGlM#OR<(wtrzO-SYRg%ES-$j(eUDPP+A$g4B5@yr88mjn$rt=FC{yLFtHcRi{y^f8Cg!X~E0_1RDIvG1EON<;aUOp8Dj%1+WI
zg@;EG6MFB?g<$45qI~sL?W4h-7P!Dyr(G}iDnfk%JGZt}h{#}3mq2qq*=xguSyujs
zz&9Jm6BN0c1+k18g{VeWIOLCDgw$F~a}J=!7N~xNo15sM5RMUZlQGe2Hy1
z0dzcE(sa1+`rt8>FFurcfX`xaz?4--UryjtT*Tu}3+?UfjUQXgS@BnEZs>UB?Fadh
zo0E?N3zWyvLQ&qRP0uWf18(YVUc>fdd5pZj&2)H9V2&`x;wddlM6b}?ZC=}tv3Jy7
zh}}xK%$mu1wPrm+-@={amtF8jwaK9`<()&j+Oe7MRJuljw82Rn
zP_9*aMwVBIJ+7J^oRTgGAo_TBSb3uZR}m(H;gsx|F-y+6P&T5%?>46Zokv1Oi-7KD
z>N|BOZ#OHC!#T*@oVM_rf`xi(7B}uevTI;sOP|FhpTwCtie%wG822!iZMgYsXDt=1
zu7)3Tz3Xt|Ea`^|W(L?s>A;I?xb^)94c`M!6wNSp$dqB-FSTWZ$KH5H&g9P{Qy7W6
zLTH!XvCz6mph1-)#wUUexVialIOC$=$@CPjha>gUak1~h-m%d3ROM|u3;6MRf303e
z^U@2L;H|D=C_Lb%=E6Dfp(;;?8h-nC+Y?X^4Zl7F^N5||mcEKz^n^CgXREd0EY
zuCR=wcj7~BkcIv9*qv!CuTNCf5n$C0Mi{h{6_JnLzB}8NC$nL#^t^}}y=u*LlfR`i
zDY7F?;{#>{Bw%IlEN}I4c!7rw6?pLsxRv&=2&EF8qy8(DsMws({0VAQAP|R=#Ct9^
z4O0p(sC5>UvZ~{3PQ>t_Ix-y}gRR5k^4`#X%6@`3Wty$&8N*7=_@z5-2VW|HCFE_c&
zl7z2(_j7P|m?xw^+RSk0N7{gn9yD3k8zfRgL}QeVGME=#an}XS+4rgQf{h>2=l_k=j_qAPRV`JW}rjqV&}1
z56(R+&u8o|^v*||RoEJ=wbA@Y-@;|8QeMNS}bkmgZ0&&eAKM8nXJ#HsK6ORAw#
znK$Lk8#)VM6yy!7k3(HtMKPL$jBB&=M=n?P4+kYgVI>`UDt1)1;3az|%;zC_mT
z{_t6PlQd_uw~Ml=_1vu%NHY?>|B@a9dVEM(wGJO
zB+RVc92--AOi6*NOb;9m1{KC-O{6pS&UfgdF}QNTiZ93&*J
zL-tA_865Om6bxm@TE&OsmD*%6N&QIYJEn#f3!}IxkHSZ@vb)W#$+cqyMCPut_a__l
zEPE?2!IXewa055$=<0q`;Xy`GrFgiZ)_bIP+Pp?_>b#T4D<{J=w8
z<9u&nsm-KGS(biMlBUHu{|q|RP9NRb|HH!n;xg2+T`@QD9TV#?;9O5O%lRgR=WV?~
zCIR)xdmlrJpFQkgZ9Dxgyh-BnaCvV1l_uN36t`oa>~Z>x4sZXI^x*!3$sB%BnA8nD
zDdtOqE*b*qzRf2;4+0qdjWvM#Y1$S(?3yRh*ha$A#|zJb@4IhME+GmzFLRY=`8k_j
zffp&}Dko;ovww@sJs5l_aP4zZ_pX69GbQXDGx}<&-IB<4Ne>O!2wRKYV+FegbxfuG
zW=#yOL?L`~wpWayq>3Y5aH~Oo+D>cr=P?6W;medxxG~4FzPexN;xb4HG##szpFD--
z!^D&7O~-s3o*mtLSPsAtQ|G4%Umk#zOBMW5(blphG7R^mEd%gJ2(w9QWh=rq|&XQbPvmi9%=SpTW@Yje#N14bNTit;qs~`&6
z%dy}(4{2U$9I&9f=7!t
V3kp`Tr@#2A0IDDrq>_2?e*lG?oyPzG

literal 0
HcmV?d00001

diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/index.md
new file mode 100644
index 000000000000000..b5013bf93fb6243
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/index.md
@@ -0,0 +1,405 @@
+---
+title: How to write an API reference
+slug: MDN/Contribute/Howto/Write_an_API_reference
+tags:
+  - API
+  - Documentation
+  - Guide
+  - Howto
+  - MDN Meta
+---
+{{MDNSidebar}}
+
+This guide takes you through all you need to know to write an API reference on MDN.
+
+## Getting prepared
+
+Before starting to document an API, there are some things you should prepare and plan in advance of starting to actually write.
+
+### Prerequisite knowledge
+
+It is assumed that before reading this guide you have a reasonable knowledge of:
+
+- Web technologies like HTML, CSS and JavaScript. JavaScript is most important.
+- Reading Web technology specs. You'll be looking at these a lot as you document APIs.
+
+Everything else can be learned along the way.
+
+### Prerequisite resources
+
+Before starting to document an API, you should have available:
+
+1. The latest spec:
+   Whether it is a W3C Recommendation or an early editor's draft, you should refer to the latest available draft of the spec that covers (or specs that cover) that API.
+   To find it, you can usually do a Web search. The latest version will often be linked to from all versions of the spec, listed under "latest draft" or similar.
+2. The latest modern web browsers:
+   These should be experimental/alpha builds such as [Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/)/[Chrome Canary](https://www.google.com/intl/en/chrome/canary/) that are more likely to support the features you are documenting.
+   This is especially pertinent if you are documenting a nascent/experimental API.
+3. Demos/blog posts/other info: Find as much info as you can.
+4. Useful engineering contacts:
+   It is really useful to find yourself a friendly engineering contact to ask questions about the spec, someone who is involved in the standardization of the API, or its implementation in a browser.
+   Good places to find them are:
+
+    - Your internal company address book, if you work for a relevant company.
+    - A public mailing list that is involved in the discussion of that API, such as Mozilla's [dev-platform](https://groups.google.com/a/mozilla.org/g/dev-platform/) or [dev-webapi](https://lists.mozilla.org/listinfo/dev-webapi) lists, or a W3C list like [public-webapps](https://lists.w3.org/Archives/Public/public-webapps/).
+    - The spec itself. For example, the [Web Audio API spec](https://webaudio.github.io/web-audio-api/) lists the authors and their contact details at the top.
+
+### Take some time to play with the API
+
+You will return to build demos many times through the course of documenting an API, but it is useful to start by spending time familiarizing yourself with how the API works — learn what the main interfaces/properties/methods are, what the primary use cases are, and how to write simple functionality with it.
+
+When an API has changed, you need to be careful that existing demos you refer to or learn from are not out of date. Check the main constructs that are used in the demo to see if they match up to the latest spec. They may also not work in up-to-date browsers, but this is not a very reliable test, as often the old features continue to be supported for backwards compatibility.
+
+> **Note:** If the spec has been recently updated so that, say, a method is now defined differently, but the old method still works in browsers, you will often have to document both in the same place, so that the old and new methods are covered.
+> If you need help, refer to demos you have found, or ask an engineering contact.
+
+### Create the list of documents you need to write or update
+
+An API reference will generally contain the following pages.
+You can find more details of what each page contains, examples, and templates, in our [Page types](/en-US/docs/MDN/Structures/Page_types) article.
+Before you start you should write down a list of all the pages you should create.
+
+1. Overview page
+2. Interface pages
+3. Constructor pages
+4. Method pages
+5. Property pages
+6. Event pages
+7. Concept/guide pages
+8. Examples
+
+> **Note:** We'll be referring to the [Web Audio API](/en-US/docs/Web/API/Web_Audio_API) for examples in this article.
+
+#### Overview pages
+
+A single API overview page is used to describe the role of the API, its top-level interfaces, related features contained in other interfaces, and other high level details.
+Its name and slug should be the name of the API plus "API" on the end. It is placed at the top level of the API reference, as a child of [https://developer.mozilla.org/en-US/docs/Web/API](/en-US/docs/Web/API).
+
+Example:
+
+- Title: _Web Audio API_
+- Slug: _Web_Audio_API_
+- URL: [https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API](/en-US/docs/Web/API/Web_Audio_API)
+
+#### Interface pages
+
+Each interface will have its own page too, describing the purpose of the interface, listing any members (constructors, methods, properties, etc. it contains), and showing what browsers it is compatible with.
+A page's name and slug should be the name of the interface, exactly as written in the spec.
+Each page is placed at the top level of the API reference, as a child of [https://developer.mozilla.org/en-US/docs/Web/API](/en-US/docs/Web/API).
+
+Examples:
+
+- Title: _AudioContext_
+- Slug: _AudioContext_
+- URL: [https://developer.mozilla.org/en-US/docs/Web/API/AudioContext](/en-US/docs/Web/API/AudioContext)
+
+
+
+- Title: _AudioNode_
+- Slug: _AudioNode_
+- URL: [https://developer.mozilla.org/en-US/docs/Web/API/AudioNode](/en-US/docs/Web/API/AudioNode)
+
+> **Note:** We document every member appearing in the interface. You should bear the following rules in mind:
+
+- We document methods defined on the prototype of an object implementing this interface (instance methods), and methods defined on the actual class itself (static methods).
+On the rare occasions that they both exist on the same interface, you should list them in separate sections on the page (Static methods/Instance methods).
+Usually only instance methods exist, in which case you can put these under the title "Methods".
+- We do not document inherited properties and methods of the interface: they are listed on the respective parent interface. We do hint at their existence though.
+- We do document properties and methods defined in mixins. Please see the [contribution guide for mixins](/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file#mixins) for more details.
+- Special methods like the stringifier (`toString()`) and the jsonizer (`toJSON()`) are also listed if they do exist.
+- Named constructors (like `Image()` for {{domxref("HTMLImageElement")}} ) are also listed, if relevant.
+
+#### Constructor pages
+
+Each interface has 0 or 1 constructors, documented on a subpage of the interface's page. It describes the purpose of the constructor and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the constructor, which is exactly the same as the interface name, and the title is interface name, dot, constructor name, then parentheses on the end.
+
+Example:
+
+- Title: _AudioContext.AudioContext()_
+- Slug: _AudioContext_
+- URL: [https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/AudioContext](/en-US/docs/Web/API/AudioContext/AudioContext)
+
+#### Property pages
+
+Each interface has zero or more properties, documented on subpages of the interface's page. each page describes the purpose of the property and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the property, and the title is interface name, dot, then property name.
+
+Examples:
+
+- Title: _AudioContext.state_
+- Slug: _state_
+- URL: [https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/state](/en-US/docs/Web/API/BaseAudioContext/state)
+
+
+
+#### Method pages
+
+Each interface has zero or more methods, documented on subpages of the interface's page. each page describes the purpose of the method and shows what its syntax looks like, usage examples, browser compatibility information, etc. Its slug is the name of the method, and the title is interface name, dot, method name, then parentheses.
+
+Examples:
+
+- Title: _AudioContext.close()_
+- Slug: _close_
+- URL: [https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/close](/en-US/docs/Web/API/AudioContext/close)
+
+
+
+- Title: _AudioContext.createGain()_
+- Slug: _createGain_
+- URL: [https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/createGain](/en-US/docs/Web/API/BaseAudioContext/createGain)
+
+#### Event pages
+
+Document events as sub pages of their target interfaces and use the slug _eventname_\_event with the title set to `Interface: eventName event`.
+
+Don't create pages for `on` event handler properties. Mention both ways to access the event on the `eventName_event` page.
+
+Example:
+
+- Title: XRSession: end event
+- Slug: end_event
+- URL: [https://developer.mozilla.org/en-US/docs/Web/XRSession/end_event](/en-US/docs/Web/API/XRSession/end_event)
+
+#### Concept/guide pages
+
+Most API references have at least one guide and sometimes also a concept page to accompany it. At minimum, an API reference should contain a guide called "Using the _name-of-api_", which will provide a basic guide to how to use the API. More complex APIs may require multiple usage guides to explain how to use different aspects of the API.
+
+If required, you can also include a concepts article called "_name-of-api_ concepts", which will provide explanation of the theory behind any concepts related to the API that developers should understand to effectively use it.
+
+These articles should all be created as subpages of the API overview page. For example, the Web Audio has four guides and a concept article:
+
+- [https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API](/en-US/docs/Web/API/Web_Audio_API/Using_Web_Audio_API)
+- [https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API](/en-US/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API)
+- [https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics](/en-US/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics)
+- [https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Porting_webkitAudioContext_code_to_standards_based_AudioContext](/en-US/docs/Web/API/Web_Audio_API/Migrating_from_webkitAudioContext)
+- [https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API](/en-US/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API)
+
+#### Examples
+
+You should create some examples that demonstrate at least the most common use cases of the API. You can put these anywhere that is appropriate, although the recommended place is the [MDN GitHub repo](https://github.com/mdn/).
+
+#### Listing them all
+
+Creating a list of all these subpages is a good way to track them. For example:
+
+- Web_Audio_API
+- AudioContext
+
+  - AudioContext.currentTime
+  - AudioContext.destination
+  - AudioContext.listener
+  - ...
+  - AudioContext.createBuffer()
+  - AudioContext.createBufferSource()
+  - ...
+
+- AudioNode
+
+  - AudioNode.context
+  - AudioNode.numberOfInputs
+  - AudioNode.numberOfOutputs
+  - ...
+  - AudioNode.connect(Param)
+  - ...
+
+- AudioParam
+- Events (update list)
+
+  - start
+  - end
+  - …
+
+Each interface in the list has a separate page created for it as a subpage of https\://developer.mozilla.org/en-US/docs/Web/API; for example, the document for {{domxref("AudioContext")}} would be located at https\://developer.mozilla.org/en-US/docs/Web/API/AudioContext. Each [interface page](#interface_pages) explains what that interface does and provides a list of the methods and properties that comprise the interface. Then each method and property is documented on its own page, which is created as a subpage of the interface it's a member of. For instance, {{domxref("BaseAudioContext/currentTime")}} is documented at https\://developer.mozilla.org/en-US/docs/Web/API/AudioContext/currentTime.
+
+## Create the pages
+
+Now create the pages you need, according to the structures below. Our [MDN content README](https://github.com/mdn/content#adding-a-new-document) contains instructions on creating a new document, and our [Page types](/en-US/docs/MDN/Structures/Page_types) guide contains further examples and page templates that might be useful.
+
+### Structure of an overview page
+
+API landing pages will differ greatly in length, depending on how big the API is, but they will all have basically the same features. See [https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API](/en-US/docs/Web/API/Web_Audio_API) for an example of a big landing page.
+
+The features of a landing page are outlined below:
+
+1. **Description**: the first paragraph of the landing page should provide a short, concise description of the API's overarching purpose.
+2. **Concepts and usage section**: The next section should be titled "\[name of API] concepts and usage", and provide an overview of all the main functionality that the API provides, what problems it solves, and how it works — all at a high level. This section should be fairly short, and not go into code or specific implementation details.
+3. **List of interfaces**: This section should be titled "\[name of API] interfaces", and provide links to the reference page for each interface that makes up the API, along with a short description of what each one does. See the "Referencing other API features with the \\{{domxref}} macro" section for a quicker way to create new pages.
+4. **Examples**: This section should show a simple use case or two for the API.
+5. **Specifications table**: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.
+6. **Browser compatibility**: Now you need to include a browser compatibility table. See [Compatibility tables](/en-US/docs/MDN/Structures/Compatibility_tables) for details.
+7. **See also**: The "See also" section is a good place to include further links that may be useful when learning about this technology, including MDN (and external) tutorials, examples, libraries, etc.
+8. **Tags**: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.
+
+### Structure of an interface page
+
+Now you should be ready to start writing your interface pages. Each interface reference page should observe the following structure:
+
+1. **\\{{APIRef}}**: Include the \\{{APIRef}} macro in the first line of each interface page, including the name of the API as an argument, so for example \\{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left-hand side of the interface page, including properties and methods, and other quick links as defined in the [GroupData](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.
+    ![This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro ](apiref-links.png)
+2. **Standardization status**: The banner indicating the standardization status should be added next (these can be placed on the same line as the \\{{APIRef}} macro.):
+
+   - \\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)
+   - \\{{Deprecated_header}}
+   - \\{{Non-standard_header}}
+
+3. **Description**: the first paragraph of the interface page should provide a short concise description of the interface's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. If the interface is actually a dictionary, you should use that term instead of "interface".
+4. **Inheritance diagram:** Use the [`InheritanceDiagram`](https://github.com/mdn/yari/blob/main/kumascript/macros/InheritanceDiagram.ejs) macro to embed an SVG inheritance diagram for the interface.
+5. **List of properties, List of methods**: These sections should be titled "Properties" and "Methods", and provide links (using the \\{{domxref}} macro) to a reference page for each property/method of that interface, along with a description of what each one does. These should be marked up using description/definition lists, which can be created using the "Definition List", "Definition Term", and "Definition Description" buttons on the MDN editor toolbar. Each description should be short and concise — one sentence if possible. See the "Referencing other API features with the \\{{domxref}} macro" section for a quicker way to create links to other pages.
+
+   At the beginning of both sections, before the beginning of the list of properties/methods, indicate inheritance using the appropriate sentence, in italics:
+   _This interface doesn't implement any specific properties, but inherits properties from \\{{domxref("XYZ")}}, and \\{{domxref("XYZ2")}}._
+   _This interface also inherits properties from \\{{domxref("XYZ")}}, and \\{{domxref("XYZ2")}}._
+   _This interface doesn't implement any specific methods, but inherits methods from \\{{domxref("XYZ")}}, and \\{{domxref("XYZ2")}}._
+   _This interface also inherits methods from \\{{domxref("XYZ")}}, and \\{{domxref("XYZ2")}}._
+
+   > **Note:** Properties that are read-only should have the \\{{readonlyInline}} macro, which creates a nifty little "Read only" badge, included on the same line as their \\{{domxref}} links (after the use of the \\{{experimentalInline}}, \\{{non-standard_Inline}} and \\{{deprecatedInline}} macros, if some of these are needed.
+
+6. **Examples**: Include a code listing to show typical usage of a major feature of the API. Rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you could reference a [GitHub](https://github.com/) repo containing the full example, and you could also link to a live example created using the [GitHub gh-pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) feature (so long as it uses only client-side code of course.) If the example is visual, you could also use the MDN [Live Sample](/en-US/docs/MDN/Structures/Live_samples) feature to make it live and playable in the page.
+7. **Specifications table**: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.
+8. **Browser compatibility**: Now you need to include a browser compatibility table. See [Compatibility tables](/en-US/docs/MDN/Structures/Compatibility_tables) for details.
+9. **Polyfill**: If appropriate, include this section, providing code for a polyfill that enables the API to be used even on browsers that don't implement it. If no polyfill exists or is needed, leave this section out entirely.
+10. **See also**: The "See also" section is a good place to include further links that may be useful when learning about this technology, including MDN (and external) tutorials, examples, libraries, etc. We have a liberal policy for linking to external sources, but pay attention:
+
+    - Do not include pages with the same information as another page in the MDN; link to that page instead.
+    - Do not put author names — we are a writer-neutral documentation site. Link to the document; the author name will be displayed there.
+    - Pay special attention to blog posts: they tend to become outdated (old syntax, wrong compat information). Link to them only if they have a clear added value that can't be found in a maintained document.
+    - Do not use action verb like "See … for more information" or "Click to…", you don't know if your reader is able to see, or to click on the link (like on a paper version of the document).
+
+11. **Tags**: There is a set of standard tags you should include for each reference page — see the "Tags" section for more.
+
+#### Interface page examples
+
+The following are exemplary examples of Interface pages:
+
+- {{domxref("Request")}} from the [Fetch API](/en-US/docs/Web/API/Fetch_API).
+- {{domxref("SpeechSynthesis")}} from the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API).
+
+### Structure of a property page
+
+Create your property pages as subpages of the interface they are implemented on. Copy the structure of another property page to act as the basis for your new page.
+
+Edit the property page name to follow the `Interface.property_name` convention.
+
+Property pages must have the following sections:
+
+1. **Title**: the title of the page must be **InterfaceName.propertyName**. The interface name must start with a capital letter. Although an interface is implemented in JavaScript on the prototype of objects, we don't include `.prototype.` in the title, like we do in the [JavaScript reference](/en-US/docs/Web/JavaScript/Reference).
+2. **\\{{APIRef}}**: Include the \\{{APIRef}} macro in the first line of each property page, including the name of the API as an argument, so for example \\{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left-hand side of the interface page, including properties and methods, and other quick links as defined in the [GroupData](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.
+    ![This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro ](apiref-links.png)
+3. **Standardization status**: The banner indicating the standardization status should be added next to the interface name (these can be placed on the same line as the \\{{APIRef}} macro):
+
+   - \\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)
+   - \\{{Deprecated_header}}
+   - \\{{Non-standard_header}}
+
+4. **Description**: the first paragraph of the property page should provide a short, concise description of the property's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default/initial value, and whether it's read only or not. The structure of the first sentence must be:
+
+   - For read-only properties
+     - : The **`InterfaceName.property`** read-only property returns a \\{{domxref("type")}} that...
+   - For other properties
+     - : The **`InterfaceName.property`** property is a \\{{domxref("type")}} that…
+
+   > **Note:** `InterfaceName.property` should be in ``, and should additionally be in bold (``) the first time it's used.
+
+5. **Syntax**: The syntax section should show how to get the property, and how to set it, if it's not read only. Use the `syntaxbox` class for it and italics for part to be replaced by the actual variable name. For example:
+
+    ```js
+    let myType = oscillator.type;
+    oscillator.type = aType;
+    ```
+
+    The syntax section should also have a subsection — "Value", which will contain a description of the property's value. This should contain the data type of the property, and what it represents. For an example, see {{domxref("SpeechRecognition.grammars")}}
+
+6. **Examples**: Include a code listing to show typical usage of the property in question. You should start with a simple example that shows how an object of the type is created and how to access the property. More complex examples can be added after such an example. In these additional examples, rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you can reference a [GitHub](https://github.com/) repo containing the full example, and you could also link to a live example created using the [GitHub gh-pages feature](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) (so long as it uses only client-side code of course.) If the example is visual, you could also use the MDN [Live Sample](/en-US/docs/MDN/Structures/Live_samples) feature to make it live and playable in the page.
+7. **Specifications table**: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.
+8. **Browser compatibility**: Now you need to include a browser compatibility table. See [Compatibility tables](/en-US/docs/MDN/Structures/Compatibility_tables) for details.
+9. **See also**: The "See also" section is a good place to include further links that may be useful when using this technology: like methods and properties affected by a change of this property or events thrown in relation to it. More links useful when learning about this technology, including MDN (and external) tutorials, examples, libraries,… can be added, though it may be useful to consider adding them on the interface reference page instead.
+10. **Tags**: There is a set of standard tags you should include for each property page — see the "Tags" section for more.
+
+#### Property page examples
+
+The following are exemplary examples of property pages:
+
+- {{domxref("Request.method")}} from the [Fetch API](/en-US/docs/Web/API/Fetch_API).
+- {{domxref("SpeechSynthesis.speaking")}} from the [Web Speech API](/en-US/docs/Web/API/Web_Speech_API).
+
+### Structure of a method page
+
+Create your method pages as subpages of the interface they are implemented on. Copy the structure of another method page to act as the basis for your new page.
+
+Method pages need the following sections:
+
+1. **Title**: the title of the page must be **InterfaceName.method()** (with the two terminal parentheses), but the slug (the end of the page URL) must not include the brackets. Also the interface name must start with a capital. Although an interface is implemented in JavaScript on the prototype of objects, we don't put `.prototype.` in the title, like we do in the [JavaScript reference](/en-US/docs/Web/JavaScript/Reference).
+2. **\\{{APIRef}}**: Include the \\{{APIRef}} macro in the first line of each method page, including the name of the API as an argument, so for example \\{{APIRef("Web Audio API")}}. This macro serves to construct a reference menu on the left-hand side of the interface page, including properties and methods, and other quick links as defined in the [GroupData](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) macro (ask someone to add your API to an existing GroupData entry, or to create a new one, if it isn't already listed there). The menu will look something like the below screenshot.
+    ![This screenshot shows a vertical navigation menu for the OscillatorNode interface, with multiple sublists for methods and properties, as generated by the APIRef macro ](apiref-links.png)
+3. **Standardization status**: Next, the banner indicating the standardization status should be added (these can be placed on the same line as the \\{{APIRef}} macro):
+
+    - \\{{SeeCompatTable}} for an experimental feature (i.e. the spec is not at the CR level.)
+    - \\{{Deprecated_header}}
+    - \\{{Non-standard_header}}
+
+4. **Description**: The first paragraph of the method page should provide a short concise description of the method's overarching purpose. You may also want to include a couple more paragraphs if any additional description is required. Obvious extra information to include is its default parameter values, any theory that the method relies on, and what the parameter values do.
+
+    - The beginning of the first sentence must follow the following structure:
+      - : The **InterfaceName.method()** method interface ...
+
+    > **Note:** `InterfaceName.method()` should be in ``, and should also be in bold (``) the first time it's used.
+
+5. **Syntax**: The syntax section should include a 2–3 line example — usually just construction of the interface, then calling of the interface method.
+
+    - The syntax should be of the form:
+      - : var \returnValue\ = \ifName\.method(\param1\, \param2\, ...)
+    - If the method has no return value (`void` as return value in the webidl), use:
+      - : \ifName\.method(\param1\, \param2\, ...)
+
+    The syntax section should include three subsections (see {{domxref("SubtleCrypto.sign()")}} for an example):
+
+    - "Parameters": This should contain a definition list (or unordered list) that names and describes the different parameters the method takes. You should include the {{optional_inline}} macro next to the parameter name, in the case of optional parameters. If there are no parameters, this section should be omitted.
+    - "Return value": This should say what return value the method has, be it a simple value like a double or boolean, or a more complex value like another interface object, in which case you can use \\{{domxref}} macro to link to the MDN API page covering that interface (if it exists.) A method might return nothing, in which case the return value should be written as "\\{{jsxref('undefined')}}" (which will look like this in the rendered page: {{jsxref("undefined")}}).
+    - "Exceptions": This should list the different exceptions that can be raised when invoking the method, and what circumstances cause them. If there are no exceptions, this section should be omitted.
+
+6. **Examples**: Include a code listing to show typical usage of the method in question. Rather than listing ALL the code, you should list an interesting subset of it. For a complete code listing, you should reference a [GitHub](https://github.com/) repo containing the full example, and you could also link to a live example created using the [GitHub gh-pages feature](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) (so long as it uses only client-side code of course.) If the example is visual, you could also use the MDN [Live Sample](/en-US/docs/MDN/Structures/Live_samples) feature to make it live and playable in the page.
+7. **Specifications table**: At this point you need to include a specifications table — see the "Creating a spec reference table" section for more details.
+8. **Browser compatibility**: Now you need to include a browser compatibility table. See [Compatibility tables](/en-US/docs/MDN/Structures/Compatibility_tables) for details.
+
+#### Method page examples
+
+The following are exemplary examples of Interface pages:
+
+- {{domxref("Document.getAnimations")}} from the [Web Animations API](/en-US/docs/Web/API/Web_Animations_API).
+- {{domxref("fetch()")}} from the [Fetch API](/en-US/docs/Web/API/Fetch_API).
+
+## Tagging
+
+For API reference pages, there are standard tags that all pages should have:
+
+- "API"
+- "Reference"
+- Name of API (e.g. "Web Audio API")
+- Any pertinent related keywords (e.g. "audio")
+
+For Interface pages, also add:
+
+- "Interface"
+- The name of the interface, e.g. "AudioContext"
+
+For method pages, also add:
+
+- "Method"
+- The name of the interface the method relates to, e.g. "AudioContext"
+- The name of the method, e.g. "createBuffer"
+
+For property pages, also add:
+
+- "Property"
+- The name of the interface the property relates to, e.g. "AudioContext"
+- The name of the property, e.g. "currentTime"
+
+In all cases, also add a keyword indicating the standardization status:
+
+- Deprecated
+- Non-standard
+
+These tags will be used to generate correct quicklinks, with nice icons. See [How to properly tag pages](/en-US/docs/MDN/Contribute/Howto/Tag) for additional information on tagging, as well as about other tags you may find useful.
+
+## Sidebars
+
+Once you've created your API reference pages, you'll want to insert the correct sidebars on them to associate the pages together. Our [API reference sidebars](/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference/Sidebars) guide explains how.
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/information_contained_in_a_webidl_file/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/information_contained_in_a_webidl_file/index.md
new file mode 100644
index 000000000000000..2f06aeb8aa26065
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/information_contained_in_a_webidl_file/index.md
@@ -0,0 +1,607 @@
+---
+title: Information contained in a WebIDL file
+slug: >-
+  MDN/Contribute/Howto/Write_an_API_reference/Information_contained_in_a_WebIDL_file
+tags:
+  - Howto
+  - MDN Meta
+  - Reference
+  - WebIDL
+---
+{{MDNSidebar}}
+
+When writing documentation about an API, the sources of information are many: the specifications describe what should be implemented as well as the model, and the implementations describe what has actually been put in the browsers. WebIDL files are a very condensed way of giving a lot, but not all, of the information about the API. This document provides a reference to help understand WebIDL syntax.
+
+IDL stands for **_Interface Definition Language_** and it is designed to describe APIs. In the wider world of computing there are several kinds of IDL. In the world of browsers, the IDL we use is called _WebIDL_. Two kinds of WebIDL are available: the one given in the WebIDL spec, and the one implemented in browsers. The spec is the canonical reference, and the browser WebIDL describes what is actually implemented in a particular browser, and contains additional things such as annotations, information about non-standard elements, and browser-specific extensions to the IDL specification.
+
+## Where to find WebIDL files
+
+WebIDL can be found in multiple locations:
+
+- Each specification contains WebIDL inside the text: it is a very convenient way to convey precise definition. These describe the syntax of the API. Though the canonical reference, we have to keep in mind that they may differ from the actual implementation. On MDN we want to be practical and document what the Web platform really is, not what it ideally should be. So double check what is there with implementations (and don't hesitate to file bugs if you discover incoherence).
+- Three browser engines use (modified) WebIDL as part as their toolchain: Gecko, Chromium/Blink, and WebCore/WebKit. Pre-Chromium versions of Edge used it internally, but these are unfortunately not public.
+
+  - For Gecko, all WebIDL files are grouped in a single directory: . Their extension is `.webidl`. There are other `*.idl` files in the Gecko source tree but they are not WebIDL, so you can ignore them. Older versions of Gecko have some of their WebIDL scattered around somewhat, and may even use Mozilla's IDL instead of WebIDL to describe some Web interfaces, but this won't be a problem in any recent Gecko code.
+  - For Chromium, they are located in two locations, both subtrees of the source code's [`renderer/`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/renderer/) directory: [`core/`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/renderer/core/) and [`modules/`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/renderer/modules/). Chromium source code has IDL files in other locations, but these are part of the testing system and not relevant to API implementations.
+  - For WebCore, they are scattered around the source code, so you need to dig a bit more: E.g. 
+
+## Different dialects of WebIDL
+
+WebIDL is defined in [its specification](https://heycam.github.io/webidl/). But it has been designed to be extended to convey more information, and browser vendors have done so:
+
+- For Gecko, Mozilla created the [documentation](https://firefox-source-docs.mozilla.org/dom/webIdlBindings/index.html) of its dialectal WebIDL.
+- For Chromium, Google also created a [document](https://www.chromium.org/blink/webidl/) to describe its extensions.
+- For WebCore, Apple also made available a [page](https://trac.webkit.org/wiki/WebKitIDL) for its dialect.
+
+> **Note:** We describe here only the subset of WebIDL which is most useful when writing documentation. There are many more annotations useful for implementers; refer to the four documents linked above to have a complete overview.
+
+## Interfaces
+
+This section explains the WebIDL syntax that describes overall API features.
+
+### Name of the interface
+
+The interface name is the string that appears after the keyword `interface` and before the next opening bracket (`'{'`) or colon (`':'`).
+
+```js
+interface URL {};
+```
+
+Each WebIDL interface, being a true interface or a mixin, has its own page in the documentation, listing every constructor, property and method defined for it.
+
+### Inheritance chain
+
+The parent, if any, of a given interface is defined after the interface name, following a colon (`':'`). There can be only one parent per interface.
+
+```js
+interface HTMLMediaElement : HTMLElement {…}
+```
+
+The inheritance chain is listed automatically in the sidebar (using the \\{{APIRef}} macro). It can also be added as an SVG image via the macro \\{{InheritanceDiagram}}.
+
+### Mixins
+
+Some properties or methods are available to several interfaces. To prevent redefinition they are defined in special WebIDL interfaces called _mixins_.
+
+As of September 2019, mixin syntax was updated. In the new syntax, you use `interface mixin` to define a mixin interface, like so:
+
+```js
+interface MyInterface {};
+
+interface mixin MyMixin {
+  void somethingMixedIn();
+}
+```
+
+You then use the `includes` keyword to say that the properties defined inside a mixin are available on an interface:
+
+```js
+MyInterface includes MyMixin;
+```
+
+Mixins have no inheritance and cannot include other mixins. They do however support partials, so you will see things like this:
+
+```js
+interface MyInterface {};
+interface mixin MyMixin {};
+
+partial interface mixin MyMixin {
+  void somethingMixedIn();
+};
+
+MyInterface includes MyMixin;
+```
+
+For documentation purposes, MDN hides mixins. They are abstract and specification-only constructs.
+You can't see them in the browser console and it is more useful to know on which real interfaces methods and properties are implemented on.
+
+If you encounter a mixin in IDL, like [HTMLHyperlinkElementUtils](https://html.spec.whatwg.org/multipage/links.html#htmlhyperlinkelementutils),
+search for the interfaces that implement the mixin, for example
+[HTMLAnchorElement](https://html.spec.whatwg.org/multipage/text-level-semantics.html#htmlanchorelement), and document the mixin members directly on those interfaces.
+
+In practice this means instead of documenting `HTMLHyperlinkElementUtils`,
+docs are added to the concrete interfaces, like [`HTMLAnchorElement`](/en-US/docs/Web/API/HTMLAnchorElement)
+and [`HTMLAreaElement`](/en-US/docs/Web/API/HTMLAreaElement).
+
+See the following two pages that document `HTMLHyperlinkElementUtils.hash` accordingly:
+
+- [`HTMLAnchorElement.hash`](/en-US/docs/Web/API/HTMLAnchorElement/hash)
+- [`HTMLAreaElement.hash`](/en-US/docs/Web/API/HTMLAreaElement/hash)
+
+For compat data, consult the [data guideline for mixins in BCD](https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines.md).
+
+### Old mixin syntax
+
+In the old-style WebIDL mixin syntax, which you still might encounter in some places, mixins are prefixed using the `[NoInterfaceObject]` annotation:
+
+```js
+[NoInterfaceObject]
+   interface MyMixin {…}
+```
+
+In the old-style syntax, mixins implemented on an interface are defined using the `implements` keyword.
+
+```js
+MyInterface implements MyMixin;
+```
+
+### Availability in window and workers
+
+Availability in Web workers (of any type) and on the Window scope is defined using an annotation: `[Exposed=(Window,Worker)]`. The annotation applies to the partial interface it is listed with.
+
+```js
+[Exposed=(Window,Worker)]
+interface Performance {
+   [DependsOn=DeviceState, Affects=Nothing]
+   DOMHighResTimeStamp now();
+};
+
+[Exposed=Window]
+partial interface Performance {
+   [Constant]
+   readonly attribute PerformanceTiming timing;
+   [Constant]
+   readonly attribute PerformanceNavigation navigation;
+
+   jsonifier;
+};
+```
+
+In this case `Performance.now()` is available on the `Window` scope and to any worker, while `Performance.timing`, `Performance.navigation` and `Performance.toJSON()` are not available to Web workers.
+
+The most common values for the `[Exposed]` are:
+
+- `Window`
+  - : The partial interface is available to the {{domxref('Window')}} global scope.
+- `Worker`
+  - : The partial interface is available to any kind of worker, that is if the global scope is a descendant of {{domxref('WorkerGlobalScope')}} — {{domxref('DedicatedWorkerGlobalScope')}}, {{domxref('SharedWorkerGlobalScope')}}, or {{domxref('ServiceWorkerGlobalScope')}} (It also is available to `ChromeWorker`, but we don't document this as they are not visible on the Web and are internal to Firefox.)
+- `DedicatedWorker`
+  - : The partial interface is available to the {{domxref('DedicatedWorkerGlobalScope')}} only.
+- `SharedWorker`
+  - : The partial interface is available to the {{domxref('SharedWorkerGlobalScope')}} only.
+- `ServiceWorker`
+  - : The partial interface is available to the {{domxref('ServiceWorkerGlobalScope')}} only.
+
+Another value is possible, like `System`, but this has a [special meaning](/en-US/docs/Mozilla/WebIDL_bindings#Exposed) and doesn't need to be documented.
+
+Note that these possible values are themselves defined in WebIDL files. Interfaces may have a `[Global=xyz]` annotation. It means that when an object of this type is used as a global scope, any interface, property or method, with `xyz` as a value of `[Exposed]` is available.
+
+```js
+[Global=(Worker,DedicatedWorker), Exposed=DedicatedWorker]
+interface DedicatedWorkerGlobalScope : WorkerGlobalScope {…}
+```
+
+Here, it is defined that when the global scope is of type `DedicatedWorkerGlobalScope`, that is if we are in a dedicated worker, any interface, property or method exposed – using the `[Exposed]` annotation – to `Worker` or `DedicatedWorker` is available.
+
+### Preferences
+
+> **Note:** this information is specific to Gecko and should only be used in the Browser compatibility section.
+
+In Gecko, the availability of a partial interface, including its constructor, properties and methods may be controlled by a preference (usually called a "pref"). This is marked in the WebIDL too.
+
+```js
+[Pref="media.webspeech.synth.enabled"]
+interface SpeechSynthesis {
+   readonly attribute boolean pending;
+   readonly attribute boolean speaking;
+   readonly attribute boolean paused;
+};
+```
+
+Here `media.webspeech.synth.enabled` controls the `SpeechSynthesis` interface and its properties (the full listing has more than 3.)
+
+> **Note:** the default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another.)
+
+### Available only in system code
+
+Some interface features might only be available in browser internal system code, or chrome code. To signify this, in Gecko we use \[ChromeOnly], for example the property propName in the following example is only callable via chrome code:
+
+```js
+interface MyInterface {
+  [ChromeOnly]
+  readonly attribute PropValue propName;
+};
+```
+
+## Properties
+
+You can recognize the definition of a property by the presence of the `attribute` keyword.
+
+### Name of the property
+
+```js
+readonly attribute MediaError? error;
+```
+
+In the above example the name of the property is `error`; in the docs we will refer to it as `HTMLMediaElement.error` as it belongs to the `HTMLMediaElement` interface. Linking to the page is either done **with** the interface prefix using \\{{domxref('HTMLMediaElement.error')}} or **without** the prefix using \\{{domxref('HTMLMediaElement.error', 'error')}} when the context is obvious and unambiguous.
+
+### Type of the property
+
+```js
+readonly attribute MediaError? error;
+```
+
+The property value is an object of type `MediaError`. The question mark (`'?'`) indicates that it can take a value of `null`, and the documentation must explain _when_ this may occur. If no question mark is present, the `error` property can't be `null`.
+
+### Writing permissions on the property
+
+```js
+readonly attribute MediaError? error;
+```
+
+If the keyword `readonly` is present, the property can't be modified. It must be marked as read-only:
+
+- In the interface, by adding the \\{{ReadOnlyInline}} macro next to its definition term.
+- In the first sentence of its own page, by starting the description with: _The read-only **`HTMLMediaElement.error`** property…_
+- By adding the `Read-only` tag to its own page.
+- By starting its description in the interface page with _Returns…_
+
+> **Note:** Only read-only properties can be described as 'returning' a value. Non read-only properties can also be used to set a value.
+
+### Throwing exceptions
+
+```js
+[SetterThrows]
+            attribute DOMString src;
+```
+
+In some cases, like when some values are illegal, setting a new value can lead to an exception being raised. This is marked using the `[SetterThrows]` annotation. When this happens, the Syntax section of the property page _must_ have an Exceptions subsection. The list of exceptions and the conditions to have them thrown are listed, as textual information, in the specification of that API.
+
+Note that some exceptions are not explicitly marked but are defined by the JavaScript bindings. [Trying to set an illegal enumerated value](https://heycam.github.io/webidl/#es-enumeration) (mapped to a JavaScript {{jsxref('String')}}) raises a {{jsxref('TypeError')}} exception. This must be documented, but is only implicitly marked in the WebIDL document.
+
+It is uncommon to have getters throwing exceptions, though it happens in a few cases. In this case the `[GetterThrows]` annotation is used. Here also, the Syntax section of the property page _must_ have an Exceptions subsection.
+
+```js
+partial interface Blob {
+  [GetterThrows]
+  readonly attribute unsigned long long size;
+};
+```
+
+### Not throwing exceptions
+
+When the semantics of Webidl is not followed, an exception is often thrown, even without `[SetterThrows]` or `[GetterThrows]` set. For example, in strict mode, if we try to set a read-only property to a new value, that is to call its implicit setter, a read-only property will throw in strict mode.
+
+Mostly for compatibility purpose, this behavior is sometimes annoying. To prevent this by creating a no-op setter (that is by silently ignoring any attempt to set the property to a new value), the `[LenientSetter]` annotation can be used.
+
+```js
+partial interface Document {
+  [LenientSetter]
+  readonly attribute boolean fullscreen;
+  [LenientSetter]
+  readonly attribute boolean fullscreenEnabled;
+};
+```
+
+In these cases, an extra sentence is added to the description of the property. E.g
+
+_Although this property is read-only, it will not throw if it is modified (even in strict mode); the setter is a no-operation and it will be ignored._
+
+### New objects or references
+
+The return value of a property can be either a copy of an internal object, a newly created synthetic object, or a reference to an internal object.
+
+Basic objects with types like {{jsxref("String")}} (being an IDL `DOMString`, or other), {{jsxref("Number")}} (being an IDL `byte`, `octet`, `unsigned int`, or other), and {{jsxref("Boolean")}} are always copied and nothing special has to be noted about them (it is natural behavior expected by a JavaScript developer.)
+
+For interface objects, the default is to return a _reference_ to the internal object. This has to be mentioned both in the short description in the interface page, and in the description in the specific sub-pages.
+
+> **Note:** The keyword `readonly` used with a property returning an object applies to the reference (the internal object cannot be changed.) The properties of the returned object can be changed, even if they are marked as read-only in the relevant interface.
+
+Sometimes an API must return a _new_ object, or a _copy_ of an internal one. This case is indicated in the WebIDL using the `[NewObject]` annotation.
+
+```js
+[NewObject]
+   readonly attribute TimeRanges buffered;
+```
+
+In this case, each call to `buffered` returns a different object: changing it will not change the internal value, and a change in the internal value will not affect each object instance. In the documentation, we will mark it by using the adjective _new_ next to object:
+
+_The **`HTMLMediaElement.buffered`** read-only property returns a new \\{{domxref("TimeRanges")}} object that…_
+
+and
+
+- _\\{{domxref("HTMLMediaElement.buffered")}}\\{{readonlyinline}}_
+  - : _Returns a new \\{{domxref("TimeRanges")}} object that …_
+
+In the case of a reference to a collection object (like `HTMLCollection`, `HTMLFormElementsCollection`, or `HTMLOptionsCollection`, always without `[NewObject]`), we make it explicit that changes to the underlying object will be available via the returned reference. To mark this, we qualify the collection as a **live** `HTMLCollection` (or `HTMLFormElementsCollections`, or `HTMLOptionsCollection`), both in the interface description and in the subpage.
+
+E.g.
+
+- \\{{domxref("HTMLFormElement.elements")}}\\{{readonlyinline}}
+  - : Returns a live \\{{domxref("HTMLFormControlsCollection")}} containing…
+
+### Availability in workers
+
+Individual property availability in workers is also found in the WebIDL. For a property, the default is the same availability as the `interface` (that is available to {{domxref('Window')}} context only if nothing special is marked) or as the `partial interface` it is defined in.
+
+For documentation, the subpage must contain a sentence indicating if it is available or not in Web workers, right before the "Syntax" section.
+
+### Preferences
+
+> **Note:** This information is specific to Gecko and should only be used in the Browser compatibility section.
+
+In Gecko, the availability of some properties may be controlled by a preference. This is marked in the WebIDL too.
+
+```js
+[Pref="media.webvtt.enabled"]
+    readonly attribute TextTrackList? textTracks;
+```
+
+Here `media.webvtt.enabled` controls the `textTracks` property.
+
+> **Note:** The default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another).
+
+## Methods
+
+You can recognize the definition of a method by the presence of parentheses after the name.
+
+### Name of the method
+
+```js
+DOMString canPlayType(DOMString type);
+```
+
+The name of the method is `canPlayType`, and we will refer to it as `HTMLMediaElement.canPlayType()` (with the parentheses that indicate that it is a method) in the docs, as it belongs to the `HTMLMediaElement` interface. Linking to the page is either done **with** the interface prefix using \\{{domxref('HTMLMediaElement.canPlayType()')}}, or **without** the prefix using \\{{domxref('HTMLMediaElement.canPlayType', 'canPlayType()')}} when the context is obvious and unambiguous. The parentheses should always be included.
+
+### Parameters
+
+```js
+TextTrack addTextTrack(TextTrackKind kind,
+                       optional DOMString label = "",
+                       optional DOMString language = "");
+```
+
+The parameters of a method are listed in the Syntax section of the method sub-page. They are listed in the WebIDL in order, between the parenthesis, as a comma-separated list. Each parameter has a name (indicated above) and a type (e.g. a `'?'` means that the `null` value is valid.) If marked `optional`, the parameter is optional to include in a method call and must have the \\{{OptionalInline}} flag included when it is listed in the Syntax section. The parameter's default value is listed after the equality sign (`'='`).
+
+### Type of the return value
+
+```js
+DOMString canPlayType(DOMString type);
+```
+
+The return value type is indicated first inside the parentheses — in the above case the value is an object of type `DOMString`. if followed by a question mark (`'?'`), a value of `null` can be returned too, and the documentation must explain _when_ this may happen. If no question mark is present, like here, the return value can't be `null`.
+
+The keyword `void` means that there is no return value. It is not a return value type. If the WebIDL entry reads `void`, the _Return value_ section in the docs should contain only a simple _None_.
+
+### Throwing exceptions
+
+```js
+[Throws]
+   void fastSeek(double time);
+```
+
+Some methods can throw exceptions. This is marked using the `[Throws]` annotation. When this happens, the Syntax section of the method page _must_ have an Exceptions subsection. The list of exceptions and the conditions to have them thrown are listed, as textual information, in the specification of that API.
+
+Note that some exceptions are not explicitly marked but are defined by the JavaScript bindings. [Trying to set an illegal enumerated value](https://heycam.github.io/webidl/#es-enumeration) (mapped to a JavaScript {{jsxref('String')}}) as a parameter will raise a {{jsxref('TypeError')}} exception. This must be documented, but it is only implicitly marked in the WebIDL document.
+
+Have a look at one of these [_Exceptions_ sections](/en-US/docs/Web/API/SubtleCrypto/importKey#exceptions).
+
+### Availability in workers
+
+Individual method availability in workers is also found in the WebIDL. For a method, the default is the same availability as the `interface` (that is available to {{domxref('Window')}} context only if nothing special is marked) or as the `partial interface` it is defined it.
+
+For the documentation, the sub-page must contain a sentence indicating if it is available in Web workers, right before the Syntax section.
+
+### Preferences
+
+> **Note:** this information is specific to Gecko and should only be used in the Browser compatibility section.
+
+In Gecko, the availability of some properties may be controlled by a preference. This is marked in the WebIDL too.
+
+```js
+[Pref="media.webvtt.enabled"]
+   TextTrack addTextTrack(TextTrackKind kind,
+                          optional DOMString label = "",
+                          optional DOMString language = "");
+```
+
+Here `media.webvtt.enabled` controls the `addTextTrack()` method.
+
+> **Note:** The default value of the preference is not available directly in the WebIDL (it can be different from one product using Gecko to another.)
+
+## Special methods
+
+Some methods are not listed as regular methods in WebIDL but instead as special keywords, which translate to specific standard JavaScript methods.
+
+### toString() and toJSON()
+
+A stringifier specifies how an object based on an interface is resolved in contexts expecting a string. (See the [Stringifiers](#stringifiers) section.) Additionally, the keyword is mapped to `toString()` and defined as:
+
+```js
+stringifier;
+```
+
+The `toString()` method is listed just like any other method of the interface and has its own sub-page (E.g. {{domxref("Range.toString()")}})
+
+A jsonifier is mapped to `toJSON()` and defined as:
+
+```js
+jsonifier; // Gecko version
+serializer; // Standard version
+```
+
+The `toJSON()` method is listed just like any other method of the interface and has its own sub-page (E.g. {{domxref("Performance.toJSON()")}})
+
+> **Note:** the WebIDL specification uses `serializer` instead of `jsonifier`. This is not used in Gecko — only the non-standard likely early proposal `jsonifier` is found in mozilla-central.
+
+### Iterator-like methods
+
+An interface may be defined as _iterable_, meaning that it will have the following methods: `entries()`, `keys()`, `values()` and `forEach()`. They also supports the use of {{jsxref("Statements/for...of", "for...of")}} on an object implementing this interface.
+
+There are two kinds of iteration possible: the _value iterator_ and the _pair iterator._
+
+#### Value iterator
+
+```js
+iterable
+```
+
+The iterator will iterate over values of type _valueType_. The generated methods will be:
+
+- `entries()`, which returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the indexes (that are `unsigned long`).
+- `values()`, which returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the values.
+- `keys()`, which returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the keys, that are its indexes (that are `unsigned long`). In the case of value iterators, `keys()` and `entries()` are identical.
+- `forEach()`, which returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the keys that calls a given callback function one for each entry in the list.
+
+Such an iterator allows to use the syntax `for (var p in object)` as a shorthand of `for (var p in object.entries())`. We add a sentence about it in the interface description.
+
+> **Note:** the value pairs to iterate over can be defined in two different ways:
+>
+> 1. Outside the webidl file, in the prose accompanying it. Such a prose is in the spec and usually starts with: _"The [values to iterate over](https://heycam.github.io/webidl/#dfn-values-to-iterate-over)…"_.
+> 2. In the webidl file, implicitly, if the interface supports indexed properties, that is when the interface has a `getter` methods with a parameter of type `unsigned long`.
+
+#### Pair iterator
+
+```js
+iterable
+```
+
+The iterator will iterate over values of type _valueType_, with keys of type _keyType_. The generated methods will be:
+
+- `entries()` that returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the indexes (of type _keyType_). E.g. {{domxref('FormData.entries()')}}
+- `values()` that returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the values. E.g. {{domxref('FormData.values()')}}
+- `keys()` that returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the keys. E.g. {{domxref('FormData.keys()')}}
+- Once {{bug(1216751)}} lands, `forEach()`.
+
+Such an iterator allows to use the syntax `for (var p in object)` as a shorthand of `for (var p in object.entries())`. We add a sentence about it in the interface description. E.g. {{domxref('FormData')}}.
+
+> **Note:** the value pairs to iterate over are _not_ defined in the webidl file, but in the prose accompanying it. Such a prose is in the spec and usually starts with: _"The [value pairs to iterate over](https://heycam.github.io/webidl/#dfn-value-pairs-to-iterate-over)…"_
+>
+> E.g, for {{domxref('FormData')}} you find in the spec: _"The [value pairs to iterate over](https://heycam.github.io/webidl/#dfn-value-pairs-to-iterate-over) are the [entries](https://xhr.spec.whatwg.org/#concept-formdata-entry "concept-FormData-entry") with the key being the [name](https://xhr.spec.whatwg.org/#concept-formdata-entry-name "concept-FormData-entry-name") and the value the [value](https://xhr.spec.whatwg.org/#concept-formdata-entry-value "concept-FormData-entry-value"). "_
+
+### Set-like methods
+
+An interface may be defined as _set-like_, meaning that it represents an _ordered set of values_ will have the following methods: `entries()`, `keys()`, `values()`, `forEach(),` and `has()` (it also has the `size` property). They also supports the use of {{jsxref("Statements/for...of", "for...of")}} on an object implementing this interface. The set-like can be prefixed `readonly` or not. If not read-only, the methods to modify the set are also implemented: `add()`, `clear()`, and `delete()`.
+
+```js
+setlike
+```
+
+The generated properties will be:
+
+- `entries()` that returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the indexes. E.g. {{domxref('NodeList.entries()')}}.
+- `values()` that returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the values. E.g. {{domxref('NodeList.values()')}}.
+- `keys()` that returns an [`iterator`](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) on the keys. E.g. {{domxref('NodeList.keys()')}},
+- `forEach()`.
+
+In cases where the set-like declaration is not prefixed by read-only, the following methods are also generated:
+
+- `add()` that adds an entry. E.g. the `.add()` method of {{domxref('FontFaceSet')}}.
+- `clear()` that empties the set-like structure. E.g. the `.clear()` method of {{domxref('FontFaceSet')}}.
+- `delete()` that removes an entry. E.g. the `.delete()` method of {{domxref('FontFaceSet')}}.
+
+Such an set interface also allows to use the syntax `for (var p in object)` as a shorthand of `for (var p in object.entries())`.
+
+## Special Behaviors
+
+Some IDL members indicate special behaviors that should be noted on appropriate pages.
+
+### Stringifiers
+
+In addition to adding the `toString()` method to an interface as described in [toString() and toJSON()](#tostring_and_tojson), stringifiers also indicate that an object instance, when used as a string, returns a string other than the default. (The default is usually a JSON representation of the object). Exactly how depends on the way it is specified in the IDL. Regardless of the how, the non-default behavior should be described on the interface page.
+
+When the `stringifier` keyword accompanies an attribute name, referencing the object name has the same result as referencing the attribute name. Consider the following IDL:
+
+```js
+interface InterfaceIdentifier {
+  stringifier attribute DOMString DOMString name;
+};
+```
+
+For a class based on this interface, the following lines of code below are equivalent. The behavior should be noted on the property page in addition to the interface page.
+
+```js
+console.log(interfaceIdentifier);
+console.log(interfaceIdentifier.name);
+```
+
+When the `stringifier` keyword is used by itself, an object of the interface may be used as above, but the behavior is defined in source code.
+
+```js
+interface InterfaceIdentifier {
+  stringifier;
+};
+```
+
+To learn what an interface reference actually does, refer to the interface's spec or experiment with the interface to determine its output.
+
+## Constructors
+
+Constructors are a little bit hidden in WebIDL: they are listed as annotations of the main interface.
+
+### Unnamed constructors
+
+This is the most common case for constructors. The constructor of a given interface A, can be used as `a = new A(parameters);`
+
+```js
+[Constructor, Func="MessageChannel::Enabled",
+  Exposed=(Window,Worker)]
+    interface MessageChannel {…};
+```
+
+A constructor with the same interface is defined using the `Constructor` annotation on the interface. There can be parenthesis and a list of parameters or not (like in the above example.) We document all the unnamed constructors on a sub-page — for example the above is given the slug _Web/API/MessageChannel/MessageChannel_ and the title `MessageChannel()`.
+
+Another example of an unnamed constructor, with parameters:
+
+```js
+[Constructor(DOMString type, optional MessageEventInit eventInitDict),
+ Exposed=(Window,Worker,System)]
+   interface MessageEvent : Event {…};
+```
+
+There can also be several unnamed constructors, differing by their parameter lists. All syntax is documented in one single sub-page.
+
+```js
+[Constructor(DOMString url, URL base),
+ Constructor(DOMString url, optional DOMString base),
+ Exposed=(Window,Worker)]
+    interface URL {};
+```
+
+### Named constructors
+
+```js
+[NamedConstructor=Image(optional unsigned long width, optional unsigned long height)]
+    interface HTMLImageElement : HTMLElement {…
+```
+
+A named constructor is a constructor that has a different name than that of its interface. For example `new Image(…)` creates a new `HTMLImageElement` object. They are defined in the WebIDL using the `NamedConstructor` annotation on the interface, followed by the name of the constructor after the equality sign (`'='`) and the parameter inside the parenthesis, in the same format as you'll see for methods.
+
+There can be several named constructors for a specific interface, but this is extremely rare; in such a case we include one sub-page per name.
+
+### New constructor syntax
+
+As of September 2019, WebIDL constructor syntax was updated. Constructor syntax no longer involves an extended attribute on the interface:
+
+```js
+[Constructor(DOMString str)]
+    interface MyInterface {
+      ...
+};
+```
+
+New specs instead use a method-like syntax named `constructor` with no explicitly-defined return type, written like so:
+
+```js
+interface MyInterface {
+  constructor(DOMString str);
+};
+```
+
+This means extended attributes can now be specified on the constructor, and it is no longer assumed that all constructors throw. If a constructor does throw, `[Throws]` will be used to indicate that:
+
+```js
+interface MyInterface {
+  [Throws] constructor();
+};
+```
+
+It is unlikely that _all_ specs will be updated to use the new syntax, so you'll probably encounter both out in the wild. We will therefore continue to cover both types of syntax here.
+
+### Availability in workers
+
+Constructors have the same availability as the interface, or partial interface, they are defined on. The sub-page provides this information in the same way as for a method.
+
+### Preferences
+
+Constructors are controlled by the same preference as the interface, or partial interface, they are defined on. The sub-page provides this information in the same way as for a method.
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/sidebars/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/sidebars/index.md
new file mode 100644
index 000000000000000..732f32525f99d4b
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/page-structure/page-types/api/sidebars/index.md
@@ -0,0 +1,141 @@
+---
+title: API reference sidebars
+slug: MDN/Contribute/Howto/Write_an_API_reference/Sidebars
+tags:
+  - API
+  - Documentation
+  - Guide
+  - MDN
+  - MDN Meta
+  - Reference
+  - groupdata
+  - metadata
+  - onboarding
+  - sidebars
+---
+{{MDNSidebar}}
+
+You are able to include a custom sidebar on API reference pages it so that it displays links to related Interfaces, tutorials, and other resources relevant just to that API.
+This article explains how.
+
+## Creating a sidebar
+
+You need to take the following three steps to create your API sidebar:
+
+1. Create your API reference pages.
+2. Add an entry for your particular API into the [`GroupData.json`](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) file.
+3. Use the [`APIRef`](https://github.com/mdn/yari/blob/main/kumascript/macros/APIRef.ejs) macro to insert the sidebar into each page you want to display it on.
+
+Let's run through each of these steps in turn.
+The example we'll refer to in this article is the [Fetch API](/en-US/docs/Web/API/Fetch_API).
+
+### Adding an entry to GroupData.json
+
+The `GroupData.json` file holds all the data relating to what links should appear in API reference sidebars.
+When invoked, the `APIRef` macro takes an API name given to it as a parameter, looks up that name in `GroupData.json`, builds an appropriate sidebar, and inserts it into the page.
+
+To add an entry to `GroupData.json`, you need to:
+
+1. Make sure you have a [GitHub](https://github.com/) account.
+2. Fork the MDN content repo, create a new branch to contain your changes, and clone the repo locally.
+3. Checkout your new branch before starting work, and make sure you push changes to it after finishing.
+4. Create a pull request so that the MDN team can review your work, and ask for changes if necessary.
+
+The `GroupData.json` file can be found inside the `files/jsondata/` directory.
+Looking at it, you'll see a giant JSON structure, with each API having its own member.
+The name is the API name, and the value is an object containing several sub-members defining the sidebar links to be created.
+
+For example, look at the [Fetch API](/en-US/docs/Web/API/Fetch_API) page on MDN.
+The corresponding entry in `GroupData.json` looks like this:
+
+```json
+"Fetch API": {
+    "overview":   [ "Fetch API"],
+    "interfaces": [ "Headers",
+                    "Request",
+                    "Response",
+                    "FetchController",
+                    "FetchObserver",
+                    "FetchSignal",
+                    "ObserverCallback" ],
+    "methods":    [ "fetch()" ],
+    "properties": [],
+    "events":     []
+},
+```
+
+As you can see, we've used "Fetch API" for the name, and inside the object value we include a number of sub-members.
+
+#### Sub-members to include inside a GroupData entry
+
+This section lists all the sub-members you could include in a `GroupData` entry.
+
+Note that most of the values included inside the listed sub-members equate to both the link text, and slugs appended to the end of the main API index page —  `https://developer.mozilla.org//docs/Web/API` — to create the final URL for the displayed link.
+So for example, "Response" will result in a link being created like so:
+
+```html
+
          • Response
            • 
+```
+
+There are a few exceptions.
+For example the "guides" sub-member contains one or more sets of link information (title and slug) that defines links to associated guides/tutorials.
+In this case the slugs are appended to the end of the MDN docs root — https\://developer.mozilla.org/_\_/docs — allowing an article anywhere on MDN to be included.
+
+Here are the available members.
+These are all technically optional, but it is strongly encouraged that instead of omitting them, you include empty arrays.
+
+1. `"overview"` — the value is an array, inside of which you include the slug of the API overview page, if there is one.
+   "Fetch API" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API](/en-US/docs/Web/API/Fetch_API).
+2. `"interfaces"` — the value is an array in which you should list all of the interfaces that form part of that API.
+   "Response" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/API/Response](/en-US/docs/Web/API/Response).
+3. `"methods"` — the value is an array that should contain any methods the spec adds to interfaces associated with other APIs, such as instantiation methods created on {{domxref("Navigator")}} or {{domxref("Window")}}.
+   If there are a huge number of methods, you might want to consider only listing the most popular ones, or putting them first in the list.
+   "fetch()" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/API/fetch](/en-US/docs/Web/API/fetch).
+   Do _not_ list methods that are members of interfaces that are members of interfaces that are owned by the same API.
+4. `"properties"` — the value is an array that should contain all of the properties associated with the API.
+   This can include properties that are members of interfaces defined in the API spec, and properties the API defines on other interfaces.
+   If there are a huge number of properties, you might want to consider only listing the most popular ones, or putting them first in the list.
+   "Headers.append" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/API/Headers/append](/en-US/docs/Web/API/Headers/append).
+5. `"events"` — the value is an array that should contain all of the events associated with the API, defined in the API spec, or elsewhere.
+   If there are a huge number of events, you might want to consider only listing the most popular ones, or putting them first in the list.
+   "animationstart" results in a link being made to [https://developer.mozilla.org/en-US/docs/Web/Events/animationstart](/en-US/docs/Web/API/HTMLElement/animationstart_event).
+6. `"guides"` — the value is an array containing one or more objects that define links to guides explain how to use the API.
+   Each object contains two sub-members — "url", which contains the partial URL pointing to the guide article, and "title", which defines the link test for the link.
+   As an example, the following object:
+
+    ```json
+    { "url":   "/docs/Web/API/Detecting_device_orientation",
+    "title": "Detecting device orientation" }
+    ```
+
+    Creates a link with the title "Detecting device orientation", which points to [https://developer.mozilla.org/en-US/docs/Web/Events/Detecting_device_orientation](/en-US/docs/Web/Events/Detecting_device_orientation).
+
+7. `"dictionaries"` — an array of strings listing all of the dictionaries which are part of the API.
+   Generally, only dictionaries used by more than one property or method should be listed here, unless they are of special significance or are likely to require being referenced from multiple pages.
+   "CryptoKeyPair" results in a link to [https://developer.mozilla.org/en-US/docs/Web/API/CryptoKeyPair](/en-US/docs/Web/API/CryptoKeyPair).
+   > **Note:** MDN is moving away from separately documenting dictionaries.
+   > Where possible, these are now described as objects in the places where they are used.
+8. `"types"` — an array of typedefs and enumerated types defined by the API.
+   You may choose to only list those that are of special importance or are referenced from multiple pages, in order to keep the list short.
+   "RTCSctpTransportState" creates a link to [https://developer.mozilla.org/en-US/docs/Web/API/RTCSctpTransportState](/en-US/docs/Web/API/RTCSctpTransport/state).
+9. `"callbacks"` — the value is an array containing a list of all the defined callback types for the API.
+   You may find it unnecessary to use this group at all, even on APIs that include callback types, as often they are not useful to document separately.
+
+## Tags used by sidebars
+
+Some sub-members are automatically discovered from child pages, based on page tags.
+Pages under the top-level API are crawled each time the sidebar is rendered, and entries are automatically created for methods ("Method" tag), properties ("Property" tag), and constructors ("Constructor" tag).
+
+Sub-members are automatically decorated with warning icons based on tags as well.
+Decorations are added for experimental ("Experimental" tag), non-standard ("Non Standard" or "Non-standard" tag), or deprecated ("Deprecated" tag) sub-members.
+
+Further information about tag-based processing is available [in the APIRef source](https://github.com/mdn/yari/blob/main/kumascript/macros/APIRef.ejs).
+
+## Inserting the sidebar
+
+Once you've added an entry for your API into `GroupData.json`, submitted it as a pull request and had the change accepted into the main repo, you can include it in your API reference pages using the [`APIRef`](https://github.com/mdn/yari/blob/main/kumascript/macros/APIRef.ejs) macro, which takes the name you used for your API in GroupData as a parameter.
+As an example, the [WebVR API](/en-US/docs/Web/API/WebVR_API)'s sidebar is included in its pages with the following:
+
+```js
+\{{APIRef("WebVR API")}}
+```
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/css/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/css/index.md
new file mode 100644
index 000000000000000..e69de29bb2d1d64
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/css/property/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/css/property/index.md
new file mode 100644
index 000000000000000..7a4b979ffc992a4
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/page-structure/page-types/css/property/index.md
@@ -0,0 +1,27 @@
+
+
+As the [CSS](/en-US/docs/Web/CSS) standards evolve, new properties are always being added. The MDN [CSS Reference](/en-US/docs/Web/CSS/Reference) needs to be kept up-to-date with these developments. This document gives step-by-step instructions for creating a CSS property reference page.
+
+Each CSS property reference page follows the same structure. This helps readers find information more easily, especially once they are familiar with the standard reference page format.
+
+## Step 1 — Decide which property to document
+
+First, you will need to decide which property to document. You might have noticed that a page is missing, or you might have seen missing content reported in our [issues list](https://github.com/mdn/content/issues). For details about the CSS property you will need to find a relevant specification for it (e.g., a [W3C specification](https://www.w3.org/Style/CSS/), or a bug report for a non-standard property used in rendering engines like Gecko or Blink).
+
+> **Note:** When using a W3C spec, always use the **Editor's Draft** (note the red banner on the left side) and not a published version (e.g. Working Draft). The Editor's Draft is always closer to the final version!
+
+If the implementation and spec diverge, feel free to mention it in the implementation bug: it may be a bug in the implementation (and a follow-up bug will be filed), a delay in the publication of a new spec, or an error in the spec (in which case a spec bug is worth filing).
+
+## Step 2 — Check the database of CSS properties
+
+Several characteristics of a CSS property, such as its syntax or if it can be animated, are mentioned in several pages and are therefore stored in an ad-hoc database. Macros that you'll use on the page need information about the property that is stored there, so start by [checking that this information is there](/en-US/docs/MDN/Contribute/Howto/Update_the_CSS_JSON_DB).
+
+## Step 3 — Creating the CSS property page
+
+Preparations finished! Now we can add the actual CSS property page. The easiest way to create a new CSS property page is to copy the content of an existing page and to edit it to suit the new property. You can find out how to add a new page in our [GitHub README](https://github.com/mdn/content#adding-a-new-document).
+
+When creating a reference page, you'll want to add _Examples_. To do that follow this [tutorial about live samples](/en-US/docs/MDN/Structures/Live_samples). Don't forget that we are in a document explaining one single property: you need to add examples that show how this property is working in isolation, not how the whole specification is used. That means that examples for `list-style-type` should show what the different property values generate, not how to combine it with other properties, pseudo-classes, or pseudo-elements to generate nice effects. Tutorials and guides can be written to show more.
+
+## Step 4 — Getting a review
+
+Once your page is created, submit it as a PR, and a member of our review team will be assigned automatically to review your page.
\ No newline at end of file
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/glossary/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/glossary/index.md
new file mode 100644
index 000000000000000..934241de37236f7
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/page-structure/page-types/glossary/index.md
@@ -0,0 +1,74 @@
+
+
+
+This article explains how to add and link to entries in the [MDN Web Docs glossary](/en-US/docs/Glossary).
+It also provides guidelines about glossary entry layout and content.
+The glossary provides definitions for all the terms, jargon, abbreviations, and acronyms you'll come across when reading MDN content about the web and web development.
+
+It's possible that the glossary will never be complete because the web is always changing.
+By contributing new entries or fixing problems, you can help us update the glossary and fill-in gaps.
+
+Contributing to the glossary is an easy way to help make the web more understandable for everyone.
+You don't need high level technical skills.
+Glossary entries are intended to be straightforward and brief.
+
+## How to write an entry
+
+First, choose what topic you'd like to write a glossary entry for.
+If you're looking for topics that need a glossary entry, check the [list of undocumented terms](/en-US/docs/Glossary#contribute_to_the_glossary) at the end of the [Glossary landing page](/en-US/docs/Glossary).
+
+If you have an idea for a new glossary entry, [create a new page](https://github.com/mdn/content#adding-a-new-document) for it underneath the [glossary landing page](https://github.com/mdn/content/tree/main/files/en-us/glossary).
+
+### Write a summary
+
+The first paragraph of any glossary page is a simple and short description of the term.
+Preferably, this should be no more than two sentences.
+Make sure anyone reading the description can immediately understand the defined term.
+
+> **Note:** Please don't copy-and-paste from other definitions or content on the internet.
+> (And especially not Wikipedia, since its range of license versions is smaller and incompatible with MDN.) Your glossary entry should be original content.
+
+#### Writing a good glossary entry
+
+Add a few extra paragraphs if you must, but it's easy to find yourself writing an entire article.
+Writing an article is fine, but please don't create it in/for the glossary.
+If you aren't sure where to put your article, feel free to [reach out to discuss it](/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help).
+
+There are a few simple guidelines to consider for writing a better glossary entry:
+
+- When you use terms in the glossary's description of the term or when you use abbreviation, you should create appropriate links.
+  Often, this just involves creating links to other pages in the glossary.
+- Use appropriate related terms (with links) in the glossary entry, if it can be done without making the article difficult to follow.
+  Having a good network of related and useful links makes a page—or set of pages—much easier to use.
+- Think about the search terms you would choose if you wanted to find this page.
+  Try to use all the words you would use to search for the term, but without making the glossary entry nonsensical, long, or difficult to read.
+
+### Expand with links
+
+A glossary entry should always end with a _Learn more_ section.
+This section should contain links to help the reader move forward: discovering more details; learning to use the relevant technology.
+
+It is good practice to organize the links into three groups:
+
+- General knowledge
+  - : These links provide higher-level information about the term or topic.
+    For example: a link to a relevant [Wikipedia](https://www.wikipedia.org/) page.
+- Technical reference
+  - : These links offer in-depth technical information, on MDN Web Docs or other sites.
+- Learn about it
+  - : These are links to tutorials, exercises, examples, or any other instructional content that helps the reader learn.
+
+## Dealing with disambiguation
+
+Some terms can have multiple meanings depending upon context.
+To resolve ambiguity, follow these guidelines:
+
+- The term's main page must be a disambiguation page containing the [`GlossaryDisambiguation`](https://github.com/mdn/yari/blob/main/kumascript/macros/GlossaryDisambiguation.ejs) macro.
+- The term has subpages that define the term for different contexts.
+
+Let's illustrate this with an example.
+The term _signature_ can have different meanings in at least two different contexts: security and function.
+
+1. The page [Glossary/Signature](/en-US/docs/Glossary/Signature) is the disambiguation page with the [`GlossaryDisambiguation`](https://github.com/mdn/yari/blob/main/kumascript/macros/GlossaryDisambiguation.ejs) macro.
+2. The page [Glossary/Signature/Security](/en-US/docs/Glossary/Signature/Security) is the page defining a signature in a security context.
+3. The page [Glossary/Signature/Function](/en-US/docs/Glossary/Signature/Function) is the page defining a function signature.
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/html/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/html/index.md
new file mode 100644
index 000000000000000..e69de29bb2d1d64
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/http/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/http/index.md
new file mode 100644
index 000000000000000..db04f17095e4c1e
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/page-structure/page-types/http/index.md
@@ -0,0 +1,59 @@
+
+
+
+The MDN [HTTP header reference](/en-US/docs/Web/HTTP/Headers) documents HTTP header fields are components of the header section of request and response messages in the Hypertext Transfer Protocol ([HTTP](/en-US/docs/Web/HTTP)). They define the operating parameters of an HTTP transaction. This page explains how to create a new MDN reference page for an HTTP header.
+
+## Prerequisites
+
+- You will need an [MDN account](/en-US/docs/MDN/Contribute/Getting_started#step_1_create_an_account_on_mdn).
+- You will need to know or be able to dive into some [HTTP](/en-US/docs/Web/HTTP).
+
+## Step 1 – find an HTTP header to document
+
+- There are many HTTP headers defined in various IETF standards.
+- IANA maintains a [registry of headers](https://www.iana.org/assignments/message-headers/message-headers.xhtml) and Wikipedia lists [known header fields](https://en.wikipedia.org/wiki/List_of_HTTP_header_fields), but not all are relevant to web developers or part of an official standard.
+- If there are **red links** on the current [MDN header reference overview page](/en-US/docs/Web/HTTP/Headers), these headers are a good choice to document.
+- If in doubt, [ask an MDN contributor](/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help) if you are unsure whether or not it makes sense to write about the header you have chosen.
+
+## Step 2 – look at existing header reference pages
+
+- Existing HTTP headers are documented [here](/en-US/docs/Web/HTTP/Headers).
+- There are different header categories: {{Glossary("Request header")}}, {{Glossary("Response header")}}, and {{Glossary("Representation header")}}.
+- Find the category of the header you are about to document (note that some headers can be both request and response headers, depending on context).
+- Go to an existing header reference page that has the same category.
+
+## Step 3 – create a new page
+
+- All header pages live under this tree: [/docs/Web/HTTP/Headers/](/en-US/docs/Web/HTTP/Headers)
+- To create a new page, see the instructions in our [GitHub README](https://github.com/mdn/content#adding-a-new-document).
+
+## Step 4 – write content
+
+- Either start from our [template HTTP header page](/en-US/docs/MDN/Structures/Page_types#http_header_reference_page) or use a copied structure from one of the existing HTTP header documents that you found in step 2. It's your choice.
+- Write about your new HTTP header.
+- Make sure you have these sections:
+
+  - Introductory text where the first sentence mentions the header name (bold) and summarizes its purpose.
+  - Information box containing at least the header type and if the header is a {{Glossary("Forbidden header name")}}.
+  - A syntax box containing all possible directives/parameters/values of the HTTP header.
+  - A section that explains these directives/values.
+  - An example section that contains a practical use case for this header or shows where and how it occurs usually.
+  - A specification section listing relevant RFC standard documents.
+  - A "See also" section listing relevant resources.
+
+## Step 4a –  add tags to the page
+
+All HTTP header pages should at least have these tags: "HTTP", "Header", "Reference".
+
+## Step 5 – add browser compatibility information
+
+- If you have looked at other HTTP header pages, you will see that there is a \\{{compat}} macro that will fill in a browser table for you.
+- The compatibility table page is generated from structured data. If you'd like to contribute to the data, please check out  and send us a pull request.
+
+## Step 6 – add the header to the HTTP header list
+
+- Make sure your header is listed in an appropriate category on the [HTTP header reference overview page](/en-US/docs/Web/HTTP/Headers).
+
+## Step 7 – get a review
+
+Once your page is created, submit it as a PR, and a member of our review team will be assigned automatically to review your page.
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/js/errors/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/js/errors/index.md
new file mode 100644
index 000000000000000..a1dbe4838cde4f3
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/page-structure/page-types/js/errors/index.md
@@ -0,0 +1,43 @@
+
+
+
+The MDN [JavaScript error reference](/en-US/docs/Web/JavaScript/Reference/Errors) is a project aiming to help web developers with errors occurring in the [Developer Console](https://firefox-source-docs.mozilla.org/devtools-user/web_console/index.html). You can see this feature in action in Firefox — JavaScript errors contain a "Learn more" link that takes you to the JavaScript error reference containing additional advice for fixing issues.
+
+In order to help this project, we need to write more error documentation on MDN so that we can add more links to the tools where the messages are thrown.
+
+## Prerequisites
+
+- You will need an [MDN account](/en-US/docs/MDN/Contribute/Getting_started#step_1_create_an_account_on_mdn).
+- You will need to know or able to dive into some [JavaScript](/en-US/docs/Web/JavaScript).
+
+## Step 1 – find an error to document
+
+- Firefox/Gecko's error messages: 
+- Edge/Chakra's error messages: 
+- Chrome/v8's error messages: 
+
+## Step 2 – look at existing error docs
+
+- Look at the existing [JavaScript error reference](/en-US/docs/Web/JavaScript/Reference/Errors) and see how errors are documented.
+- Depending on which type of error you want to write about, you can take a closer look at these pages.
+- You might want to copy the content of an existing page to kick off your new page.
+
+## Step 3 – create a new page
+
+- All error pages live under this tree: [/docs/Web/JavaScript/Reference/Errors](/en-US/docs/Web/JavaScript/Reference/Errors)
+- To create a new page, see the instructions in our [GitHub README](https://github.com/mdn/content#adding-a-new-document).
+
+## Step 4 – write some content
+
+- Either use a copied structure from one of the existing error documents or start from scratch. Your choice!
+- You should have at least:
+
+  - A syntax box containing the message as thrown in different browsers.
+  - The error type.
+  - A text that explains why this error happened, what its consequences are. Go beyond the thrown message.
+  - Examples showcasing the error (there might be more than one!) and an example showing how to fix the code.
+  - Pointers to other reference material on MDN.
+
+## Step 5 – get a review
+
+Once your page is created, submit it as a PR, and a member of our review team will be assigned automatically to review your page.
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/js/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/js/index.md
new file mode 100644
index 000000000000000..e69de29bb2d1d64
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/page-types/learn/index.md b/files/en-us/mdn/writing-guidelines/page-structure/page-types/learn/index.md
new file mode 100644
index 000000000000000..e69de29bb2d1d64
diff --git a/files/en-us/mdn/writing-guidelines/page-structure/updating-json/index.md b/files/en-us/mdn/writing-guidelines/page-structure/updating-json/index.md
new file mode 100644
index 000000000000000..c5150a18579e490
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/page-structure/updating-json/index.md
@@ -0,0 +1,117 @@
+
+
+MDN stores data in well-defined structures when possible. This information is then centralized and can be updated once, while being used in numerous places.
+
+There are several such files, and this document describes their purpose, structure, and maintenance process.
+
+## GroupData: logical grouping of APIs
+
+`GroupData` is a JSON file collecting information about Web APIs. The grouping of APIs is somewhat fuzzy: any interface, method or property can be part of several APIs. The set of APIs grouped under a name is a convention used to communicate about a feature, without any technical enforcement.
+
+Yet, MDN needs this information to create coherent Web-API sidebars (like with the `\{{APIRef}}` macro) with the proper reference pages, guides, and overview articles.
+
+GroupData does exactly that: for each API, it lists the interfaces, properties, methods, guides, and overview pages. In the past, it also listed dictionaries and callbacks. But that use, though still supported, is deprecated and will be removed in the future.
+
+### Structure of GroupData
+
+> **Warning:** Non-existent pages listed in this file are ignored (in en-US).
+
+An entry in `GroupData.json` has the following structure:
+
+```json
+"Name_of_the_API": {
+  "overview": ["name_of_the_overview_page"],
+  "guides": [
+    "name_of_guide_1",
+    (…)
+  ],
+  "interfaces": [
+    "name_of_interface_1",
+    (…)
+  ],
+  "methods": [
+    "name_of_additional_method_1",
+    (…)
+  ],
+  "properties": [
+    "name_of_additional_property_1",
+    (…)
+  ],
+  "events": [
+    "name_of_additional_property_1",
+    (…)
+  ]
+}
+```
+
+…where:
+
+- `"Name_of_the_API"`
+  - : This key is both an ID used by sidebar macros like `\{{APIRef("Name_of_the_API")}}` and the name displayed in the sidebar itself. Choose it wisely.
+    > **Warning:** If you want to change the name displayed in the sidebar, you must edit all the pages displaying it.
+- `"overview"`
+  - : This is a list containing one page: the overview page, used as the link for the `"Name_of_the_API"` text. The value is the _title of the page_, and the page must be in the `web/api/`directory.
+- `"guides"`
+  - : This is a list of guides to display in the sidebar, in the given order. The values are _paths to the page_, starting with `/docs/`.
+- `"interfaces"`
+  - : This lists the interfaces that are part of the API.
+- `"methods"`
+  - : This lists the methods that are part of the API.
+    > **Note:** The methods of the interfaces listed in `"interfaces"` **must** not be listed there. They are automatically added to the sidebar if the tag `Method` is in the YAML header on that page.
+- `"properties"`
+  - : This lists the methods on other interfaces that are part of the API, like `navigator.xr` (a property that the WebXR API adds to the `navigator` object)
+    > **Note:** The properties of the interfaces listed in `"interfaces"` **must** not be listed there. They are automatically added to the sidebar if the tag `Property` is in the YAML header on that page.
+- `"events"`
+  - : This lists events of other interfaces that are part of the API. The values are the _title of the pages_ (that must reside under `Web/Events`)
+    > **Note:** The events targeting the interfaces listed in `"interfaces"` **must** not be listed there. They are automatically added to the sidebar if the tag `Event` (singular!) is in the YAML header on that page.
+
+There are two other keys, `"dictionaries"` and `"callbacks"`, operating on the same principle. As we no longer document these entities in their own pages, their use is deprecated, and no new entry should be added to them (and we remove them little by little).
+
+> **Note:** Also, none of the keys are mandatory; it is good practice (and we'll enforce this) to add the non-deprecated ones with an empty list rather than omitting them. It shows that the absence of value is a conscious choice.
+
+### Update process for GroupData
+
+This file should be updated in the same PR where changes affecting the sidebar happens. That way, the sidebar is always up-to-date. Reviewers shouldn't merge PRs that don't adopt it.
+
+To test your changes, check that the sidebar in the files in your PR displays all entries correctly.
+
+The `GroupData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/GroupData.json) on GitHub.
+
+## InterfaceData: recording interface inheritance
+
+> **Note:** We hope to generate this file automatically from the data available via w3c/webref in the future.
+
+`InterfaceData` describes the hierarchy of the interfaces. It lists inheritance. In the past, it also listed mixins implemented by each interface; but that usage is deprecated, and we remove mixins from this file at the same rate MDN is updated.
+
+This inheritance data is used when building API sidebars and by the `\{{InheritanceDiagram}}` in the interface pages.
+
+### Structure of InterfaceData
+
+An entry in `InterfaceData.json` has the following structure:
+
+```json
+"Name_of_the_interface": {
+  "inh": "Name_of_the_parent_interface",
+  "impl": []
+}
+```
+
+> **Note:** As mixins are deprecated, `"impl"` must be an empty list for all new interfaces.
+
+The value of `"Name_of_the_parent_interface"` is not a list but a single entry, mandatory; we must not list any interface that don't inherit from another one.
+
+### Update process for InterfaceData
+
+The same PR adding a new interface that inherits from another one must update this file. Reviewers shouldn't merge PRs that don't do so.
+
+To test your changes, check that the sidebars of each interface you edited in your PR display inheritance correctly.
+
+The `InterfaceData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/InterfaceData.json) on GitHub.
+
+## SpecData: Specification information
+
+> **Warning:** The `SpecData.json` file is no longer maintained. Canonical specification information is stored at w3c/browser-spec and in the `spec_url` key of features at mdn/browser-compat-data.
+
+The `\{{SpecName}}` and `\{{Spec2}}` macros that we are removing use the `SpecData.json` file. We do not accept any further contributions to the `SpecData.json` file; instead, either try to insert a specification table, using the `\{{Specifications}}` macro, or try to hardcode the (good) link to the specification. Note that most of the time, mentioning or linking to a specification outside the _Specifications_ section is a sign of something not appropriately documented on MDN.
+
+The `SpecData.json` file is located [here](https://github.com/mdn/content/blob/main/files/jsondata/SpecData.json) on GitHub.
diff --git a/files/en-us/mdn/writing-guidelines/researching-technology/index.md b/files/en-us/mdn/writing-guidelines/researching-technology/index.md
new file mode 100644
index 000000000000000..844dff8df1d6011
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/researching-technology/index.md
@@ -0,0 +1,115 @@
+# Researching a technology
+
+This guide gives you some handy information about approaching how to document technologies.
+
+## Getting prepared
+
+Before starting to document or update something on MDN, there are some things you should prepare and plan in advance of starting to actually write.
+
+It is assumed that before reading this guide you have a reasonable knowledge of:
+
+- Web technologies like HTML, CSS and JavaScript.
+- Reading Web technology specs. You'll be looking at these a lot as you document APIs.
+
+Everything else can be learned along the way.
+
+### Resources
+
+Useful resources for any of the documentation include:
+
+1. The 'How To Write' docs for MDN. You're already here, but it's good to browse through all the docs and familiarize yourself with our writing style, the different types of pages and what sections are included in them, and the different ways we include different parts of the page (like specifications and browser compatibility).
+2. The latest spec:
+   Different standards bodies create specifications for technologies documented on MDN. For example TC39 for JavaScript, or the W3C for HTML, CSS and Web APIs. 
+   Specs are linked to from reference pages on MDN (check the 'Specifications' section). Alternatively, you can usually do a Web search. Always work from the latest, most up to date specification.
+3. The latest modern web browsers:
+   These should be experimental/alpha builds such as [Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/)/[Chrome Canary](https://www.google.com/intl/en/chrome/canary/) that are more likely to support the features you are documenting.
+   This is especially pertinent if you are documenting a feature which is 'upcoming'.
+4. Demos/blog posts/other info: Find as much info as you can. If you are updating a technology because it has changed, you need to be careful existing resources you are using to learn are not out of date. This is why the first two points above are important.
+
+It can also be wise to try and find someone to help answer questions. This can be the specification authors, or the engineers who implement browser features. 
+
+### Reading specifications
+
+This can feel a little alien to start, but the more you do it the more you get used to it. Here are some good links to help you get started:
+
+- [How to read W3C specs](https://alistapart.com/article/readspec/) by J. David Eisenberg on A List Apart
+- [Understanding the CSS Specifications](https://www.w3.org/Style/CSS/read) from the w3c
+- [How to read web specs Part I – Or: WebVR, how do you work?](https://surma.dev/things/reading-specs/) talks through reading the WebVR spec specifically, but is a great introduction to reading Web API specs.
+- [How to read web specs Part IIa – Or: ECMAScript Symbols](https://surma.dev/things/reading-specs-2/) the second part to the link above contains information on understanding the ECMAScript specification which outlines the JavaScript language
+
+In addition we have a guide on [Information contained in a WebIDL file]() which can really help when reading Web API specs.
+
+## Take some time to play with the feature
+
+You will return to writing code examples or building demos many times through the course of documenting a technology, but it is very useful to start by spending time familiarizing yourself with how the technology works. This is a really valuable exercise, as it gives you a good understanding of what the use cases are (_why_ a developer would use this technology) and help with creating some example code at the same time.
+
+
+> **Note:** If the spec has been recently updated so that, say, a method is now defined differently, but the old method still works in browsers, you will often have to document both in the same place, so that the old and new methods are covered.
+> If you need help, refer to demos you have found, or ask an engineering contact.
+
+## Create the list of documents you need to write or update
+
+The different pages you need to write or modify varies depending on the technology you are writing about. Check out the [Page types]() and the relevant section for the technology you're documenting. You'll most likely need to update existing documentation as well, so search MDN for pages which are related to what you are writing about.
+
+### Sidebars
+
+It's possible the sidebar of the pages you write also need to be defined or updated. To find out if this is needed and how to do it [check out our sidebar guide]().
+
+### Code examples
+
+Some of the code examples for MDN docs are held in separate repositories (most notably interactive examples at the top of pages and larger demo code needed for guides). You can find a handy [list of them here]() to find which one you should add to. If you do need to add to or amend one of these repos, it's a good idea to make a note of it in your list.
+
+### Example
+
+Let's say you're documenting a new Web API, your initial list will look a little something like this:
+
+1. Overview page
+2. Interface pages
+3. Constructor pages
+4. Method pages
+5. Property pages
+6. Event pages
+7. Concept/guide pages
+8. Code examples
+9. Sidebars
+
+You can then expand on it with more details, adding each interface and it's members. For examples if you were documenting the Web Audio API, your list might look something more like this:
+
+
+- Web_Audio_API
+- AudioContext
+
+  - AudioContext.currentTime
+  - AudioContext.destination
+  - AudioContext.listener
+  - ...
+  - AudioContext.createBuffer()
+  - AudioContext.createBufferSource()
+  - ...
+
+- AudioNode
+
+  - AudioNode.context
+  - AudioNode.numberOfInputs
+  - AudioNode.numberOfOutputs
+  - ...
+  - AudioNode.connect(Param)
+  - ...
+
+- AudioParam
+- Events (update list)
+
+  - start
+  - end
+  - …
+
+
+### Open an issue
+
+It's a good idea at this point to open a tracking issue on mdn/content with the pages listed as a todo (checkbox) list. This enables not just you, but others working on documentation to publicly keep track of the status. You can also link your pull requests to this issue to give them more context.
+
+## Create the pages
+
+Now create the pages you need, according to the structures below. Our [MDN content README](https://github.com/mdn/content#adding-a-new-document) contains instructions on creating a new document, and our [Page types](/en-US/docs/MDN/Structures/Page_types) guide contains further examples and page templates that might be useful.
+
+
diff --git a/files/en-us/mdn/writing-guidelines/what-we-write/experimental_deprecated_obsolete/index.md b/files/en-us/mdn/writing-guidelines/what-we-write/experimental_deprecated_obsolete/index.md
new file mode 100644
index 000000000000000..16bed7094215f00
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/what-we-write/experimental_deprecated_obsolete/index.md
@@ -0,0 +1,111 @@
+---
+title: 'Experimental, deprecated and obsolete'
+slug: MDN/Writing_guide/Experimental_deprecated_obsolete
+page-type: mdn-writing-guide
+tags:
+  - meta
+  - writing-guide
+---
+
+{{MDNSidebar}}
+
+## Terms used on MDN Web Docs to label a technology
+
+
+
+These terms are commonly associated with technologies and specifications. These are also defined in our [Browser compatibility project](https://github.com/mdn/browser-compat-data/blob/main/schemas/compat-data-schema.md#status-information).
+
+### Deprecated
+
+The term **deprecated** on MDN Web Docs is used to mark an API or technology that is no longer recommended. A deprecated API or technology might be removed in the future or might only be kept for compatibility purposes and may still work. We recommend to avoid using the functionality marked as deprecated.
+
+### Obsolete
+
+On MDN Web Docs, the term **obsolete** was used to mark an API or technology that is not only no longer recommended but is also no longer implemented in browsers. The term was, however, confusing. It was similar to **deprecated** but it's distinction from **deprecated** ws not very helpful.
+
+> **Note:** We do not use the term **obsolete** on MDN Web Docs anymore. If you come across any instances, they should be removed or replaced with the term **deprecated**.
+
+### Experimental
+
+The term **experimental** can mean different things depending on the context you hear or read it in.
+When a technology is described as experimental on MDN Web Docs, it means that the technology is nascent and immature and is currently _in the process_ of being added to the web platform (or being considered for addition).
+
+For a technology that's marked **experimental**, one or both of the following conditions will be true:
+
+- It is implemented and enabled by default in _less than two_ modern major browsers.
+- Its defining specification is likely to change significantly, in backwards-incompatible ways (i.e., it may break existing code that relies on the feature).
+
+If one or both of these conditions is true, then you should think carefully before you start using that technology in any kind of production project (i.e., a project that is not just a demo or experiment). On the other hand, as a web developer, you can try out a feature that is marked **experimental** and provide feedback to browser vendors and standards authors. 
+
+Conversely, a technology is no longer considered **experimental** if one of the following conditions is true:
+
+- It is implemented in two or more major browsers.
+- Its defining specification is unlikely to change in ways that will break the web.
+
+Usually, if a technology is supported across several major browsers, the specification will be stable, but this is not always the case.
+And some technologies might have a stable specification and be well-used but might not have native support in browsers ([IMSC](/en-US/docs/Related/IMSC), for example). 
+
+A feature or technology that is not marked **experimental** or **deprecated** is said to be on a **standards track**, meaning the feature is part of an active specification or specification process.
+
+Sometimes during the development of a new specification or over the course of the evolution of living standards such as HTML, new elements, methods, properties, and so forth are added to the specification, kept there for a while, and then removed. Sometimes this happens very quickly, and sometimes these new items remain in the specification for months or even years before being removed. This can make it tricky to decide how to handle the removal of the item from the specification.
+
+Here are some guidelines to help you decide what to do when something is removed from the specification.
+
+> **Note:** For the purposes of this discussion, the word "item" is used to mean anything that can be part of a specification: an element or an attribute of an element, an interface or any individual method, a property, or other member of an interface, and so forth.
+
+
+### If the item was never implemented
+
+If the item was _never_ implemented in a release version of _any_ browser, not even behind a preference or a flag, delete any references to the item from the documentation.
+
+- If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), delete that page.
+    If the removed item is an interface, this means removing any subpages describing the properties and methods on that interface as well.
+- Remove the item from any lists of properties, attributes, methods, and so forth. For methods of an interface, for example, this means to remove it from the "Methods" section on the interface's overview page.
+- Search the text of the overview page for that interface, element, etc., for any references to the removed item. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy.
+- Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Remove those references, being sure not to leave weird grammar issues or other problems with the text. This may mean not just deleting words but rewriting a sentence or paragraph to make more sense. It may also mean removing entire sections of content if the description of the item's use is lengthy.
+- Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. It's unlikely that there are, since if it was never implemented, it's unlikely to be widely discussed. Remove those mentions as well.
+- If the [Browser compatibility data repository's](https://github.com/mdn/browser-compat-data) JSON files contain data for the removed items, delete those objects from the JSON code and submit a PR with that change, explaining the reason in the commit message and the PR description. Be careful to check that you don't break the JSON syntax while doing this.
+
+### If the item was implemented in a browser behind a flag
+
+If the item was implemented in any release version of any one or more browsers but _only_ behind a preference or a flag, do not delete the item from the documentation immediately. Instead, mark the item as **deprecated** as follows:
+
+- If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the [`deprecated_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Header.ejs) macro to the top of the page and add the {{tag("Deprecated")}} tag to the page's list of tags.
+- On the overview page for the element, interface, or API, find the list of items that includes the item that's been removed from the specification and add the [`deprecated_inline`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Inline.ejs) macro after the item's name in that list.
+- Search the informative text of the overview page for that interface, element, etc., for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "\[item] has been removed from the specification and will be removed from browsers soon. See \[link to page] for a new way to do this."
+- Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.
+- Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.
+- At some point in the future, a decision may be made to actually remove the item from the documentation; we don't normally do this but if the item was especially unutilized or uninteresting, we may decide to do so.
+- Update any relevant entries in the [Browser Compatibility Data repo](https://github.com/mdn/browser-compat-data) to reflect the obsolescence of the item(s) affected.
+
+### If the item was implemented in a browser without a flag
+
+If the item was implemented in one or more release builds of browsers without requiring a preference or a flag, mark the item as **deprecated**, as follows:
+
+- If the item has any documentation pages describing only that one item (such as {{domxref("RTCPeerConnection.close()")}}), add the [`deprecated_header`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Header.ejs) macro to the top of the page and add the {{tag("Deprecated")}} tag to the page's list of tags.
+- On the overview page for the element, interface, or API, find the list of items that includes the item that's been removed from the specification and add the [`deprecated_inline`](https://github.com/mdn/yari/blob/main/kumascript/macros/Deprecated_Inline.ejs) macro after the item's name in that list.
+- Search the informative text of the overview page for that interface, element, etc., for any references to the removed item. Add warning boxes in appropriate places with text along the lines of "\[item] has been removed from the specification and is deprecated. It may be removed from browsers in the future, so you should not use it. See \[link to page] for a new way to do this."
+- Similarly, look for any discussion of the item in the guides and tutorials about the relevant API or technology. Add similar warnings.
+- Search MDN Web Docs for references to the removed item, in case there are discussions elsewhere. Add similar warning boxes there as well.
+- It's unlikely that these items will be removed from the documentation anytime soon, if ever.
+- Update any relevant entries in the [Browser compatibility data repository](https://github.com/mdn/browser-compat-data) to reflect the deprecation of the item(s) affected.
+
+Please use common sense with wording of warning messages and other changes to the text suggested in the guidelines above.
+Different items will require different wording and handling of the situation.
+When in doubt, feel free to ask for advice on the [MDN Web Docs chat room](https://chat.mozilla.org/#/room/#mdn:mozilla.org) on [Matrix](https://wiki.mozilla.org/Matrix), or on the [MDN Web Docs discussion forum](https://discourse.mozilla.org/c/mdn).
+
+## How to communicate a specification conflict
+
+Sometimes, but rarely, there might be a conflict between different specification versions (usually W3C versus WHATWG). For example, one version might have a feature listed as deprecated, while the other doesn't.
+In such cases, consider what the reality is, that is, consider what browsers are actually doing, and write an "important" note to summarize that latest status.
+For example, as of Jan 2019, the [`inputmode`](/en-US/docs/Web/HTML/Global_attributes/inputmode) global attribute has a conflict, which was summarized like so: 
+
+> **Warning:** Specification conflict: The WHATWG specification lists `inputmode`(https://html.spec.whatwg.org/multipage/interaction.html#attr-inputmode) and modern browsers are working towards supporting it.
+> The [W3C HTML 5.2 spec](https://html.spec.whatwg.org/multipage/index.html#contents), however, no longer lists it (i.e. marks it as obsolete).
+> You should consider the WHATWG definition as correct, until a consensus is reached.
+
+
+
+
+
+
diff --git a/files/en-us/mdn/writing-guidelines/what-we-write/inclusion-criteria/index.md b/files/en-us/mdn/writing-guidelines/what-we-write/inclusion-criteria/index.md
new file mode 100644
index 000000000000000..ca0d33bcaa60667
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/what-we-write/inclusion-criteria/index.md
@@ -0,0 +1,182 @@
+---
+title: Inclusion criteria
+slug: MDN/Writing_guide/Inclusion_criteria
+page-type: mdn-writing-guide
+tags:
+  - meta
+  - writing-guide
+---
+
+{{MDNSidebar}}
+
+This describes, in detail, criteria for content to be included on MDN Web Docs, the application process for including new documentation, and expectations and guidelines for a party applying.
+
+This is aimed at larger projects. To suggest a new page or article please refer to the Suggesting content section in [What we write](/en_US/docs/MDN/Writing_guidelines/What_we_write#suggesting_content)
+
+## Web standards technologies
+
+The remit of MDN Web Docs is to document web standards technologies that are in a specification published by a reliable standards body and are supported in at least one stable browser. These criteria signal enough interest, stability, and "intent to implement" by the web industry at large. Therefore, we think those technologies are a safe bet for us to spend our time and effort in documenting them. Any earlier than that, a web technology or a feature might be prone to getting cancelled due to lack of interest or might be so unstable that it might change significantly, which will needlessly involve lot of rewriting (which we try to avoid where possible).
+
+## Non-web standards technologies
+
+Non-web standards technologies are technologies that do not follow our criteria summarized above. We would not normally consider them for documentation on MDN Web Docs.
+
+Our mission statement is _"to provide developers with the information they need to easily build projects on the open web"_. This suggests that we should consider documenting technologies that are useful to web developers, even if they are not open web standards, on the standards track, etc.
+
+If you want to consider a non-web standard technology for inclusion on MDN Web Docs, you should make sure that it matches the criteria below.
+
+## Criteria for inclusion on MDN Web Docs
+
+Technologies should fulfill the criteria described here for being considered to be documented on MDN Web Docs.
+
+### Be open and not proprietary
+
+At MDN Web Docs, we are supporters of open technologies. We don't support closed technology ecosystems that are controlled by a single entity, that are not open for contributions by any interested party, and that are not interoperable across multiple platforms and systems. We believe that technology works better for everyone when created out in the open.
+
+### Be web-exposed and be related to web technologies
+
+Our central remit is web standards technologies; there is no point starting to document technologies that do not relate to the web or hold any interest to web developers.
+
+### Show signs of interest and adoption
+
+We don't want to spend our time documenting a technology that has no signal of interest and adoption from the industry. It may just be that it is too early to start documenting the technology, and we could consider it to be documented on MDN Web Docs in the future.
+
+### Not show signs of being deprecated or superseded
+
+Related to the above point, we also don't want to spend our time documenting a technology that is late in its lifecycle and is already showing signs of decline in interest.
+
+### Not have an established documentation resource elsewhere
+
+There are many libraries and frameworks in existence, which are not web standards but are built on top of web technologies and are very popular in the web industry. We do not document any of these, because in general, they all have established documentation resources already. It would be foolish to compete with the official resource of a popular framework — to do so would be a waste of time and probably end up confusing developers trying to learn the technology.
+
+### Have a community willing to write and maintain the documentation
+
+The MDN Web Docs team concentrates on documenting the open web platform. If you want a technology in this area to be considered for documentation on MDN Web Docs, you'll need to have a community assembled that is willing to write the documentation and maintain it after completion. Our team is happy to provide guidance in such cases, including edits and feedback, but we don't have the resource for more than that.
+
+> **Note:** MDN Web Docs work is carried out on GitHub and 'in the open'. Your team should be verse in git & GitHub and be comfortable with working in open source.
+
+## Process for selecting the new technology
+
+If a technology looks like a good candidate for being documented on MDN Web Docs, you can [contact the team to propose and discuss the inclusion of this technology](). This section describes what the proposal should include.
+
+### Submitting the proposal
+
+Technologies will be considered for inclusion on MDN Web Docs on a case-by-case basis. For consideration, you would need to submit a proposal titled "Proposal for documenting a new technology on MDN Web Docs". We would need the following information from you in the proposal:
+
+- The technology, its core purpose/use cases, and target developer audience.
+- What kind of industry or community buzz is there is around the technology?
+  - Are a lot web developers using it? What is the industry adoption like?
+  - Do a lot web developers want or need this information?
+  - What is the size of the target audience for this information? Supporting statistics would help, if you have them.
+- How does the technology relate to core web technology and web browsers? Useful details include:
+  - Does it use HTML and CSS but generally not output to the web?
+  - Is it supported in web browsers via a polyfill?
+- What documentation or resources are already available that cover the technology?
+- How much documentation would need to be added to MDN Web Docs?
+  - List the expected number of guides, tutorials, reference pages for elements/methods/attributes, etc.
+  - Provide a high-level table of contents.
+  - Mention the kind of "advanced" features you think you might need for this resource, beyond the basic documentation pages. Are you expecting to include embedded videos, interactive code samples, etc.?
+- Who will be writing the documentation? Who are they and why are they suited for the job?
+- How will the documentation be maintained
+
+You don't need to provide us with hundreds of pages of detail at this stage (in fact, we'd prefer it if you didn't). A couple of paragraphs on each of the above points is more than adequate.
+
+> **Note:** MDN Web Docs is primarily an English site (en-US). The primary language for your project should be in US English.
+
+### Awaiting a response
+
+We will consider the technology and respond with one of the following answers:
+
+- **No**: We don't think this meets the criteria for being documented on MDN Web Docs.
+- **Maybe**: We are not sure if it is suitable for documenting on MDN Web Docs and would like to ask some further questions.
+- **Yes**: We think it is appropriate for including it on MDN Web Docs.
+
+If the technology is a good candidate, the team will assist you in getting started with the documentation.
+
+## Project guidelines for documenting the new technology
+
+If your chosen technology is accepted for documentation on MDN Web Docs, the next step is to get started.
+
+To ensure that your project for documenting the new technology on MDN Web Docs is successful, we'll need you to have the following in place:
+
+- A dedicated team
+- A project plan and roadmap
+- Writing guidelines and standards
+- An intuitive documentation structure
+- A maintenance plan
+
+### Dedicated team
+
+Make sure you have a dedicated team in place that will be there to both write the initial documentation as well as maintain it in future with the required updates.
+
+Have a think about how much work there is and how many people you might need for that.
+
+If it is a large project, you might benefit from having a few writers, a technical reviewer to check that the work is technically accurate, a copy editor to clean up the language, someone to write code examples, etc.
+
+On a smaller project, you might have one or two people taking on multiple roles. However you want to build up the team is fine as long as it works for you.
+
+A member of the MDN Web Docs team will be assigned to your project to provide guidance on the MDN Web Docs side of things.
+
+You should assign one (or two) team leads who can liaise with the MDN Web Docs team member.
+
+The MDN Web Docs representative will help get the required permissions to everyone on your team to work in the [MDN organization on Github](https://github.com/mdn).
+
+### Project plan and roadmap
+
+Create a plan for the project — tasks, estimate completion dates, and milestones you would want to track to ensure you're making steady progress.
+
+If the project is large, you should consider assigning one of your team members as the project manager. You should also consider writing a sub-project plan for an initial release that encompasses the minimum set of documentation that is useful to publish (a _minimum viable product_); you can follow it up with further additions later.
+
+If the documentation project is small, you would still need to keep a record of what has been done and what hasn't, what stage each part of the documentation is at (e.g., not started, in progress, draft written, reviewed, done), and who is working on what.
+
+### Writing guidelines and standards
+
+[These guidelines state](/en-US/docs/MDN/Writing_guidelines) how we expect documents to be written for MDN Web Docs.
+
+If you have additional guidelines for the documents you are writing, we expect this guide to be added to and kept up to date.
+
+In terms of standards, you are expected to maintain a reasonable level of writing quality for your documentation to stay on MDN Web Docs. Your MDN Web Docs representative will work with you to make you clear on what is expected.
+
+### Intuitive documentation structure
+
+If you went through the proposal submission process then you should already have a rough outline of what you are going to write for this technology. At this point you should refine that into a site structure plan: think about what the document hierarchy will be and where everything will fit and link together.
+
+Each project is different, but we'd roughly recommend something like this:
+
+```
+Landing page
+|
+------Reference
+      |
+      --------Elements
+      |
+      --------Methods
+      |
+      --------Other reference page type(s)?
+|
+------Guides/tutorials
+|
+------Examples
+```
+
+Each page type that you will use in your project should have a page template for others to copy the structure from. You should decide on these early on.
+
+Please refer to our section on page types, if additions need to be made please liaise with your MDN Web Docs representative.
+
+### Maintenance plan
+
+The documentation for this technology will need to be maintained to remain on MDN Web Docs:
+
+- The content and files for MDN Web Docs are stored on Github. When others make changes to the documentation for your technology, a member from your team needs to review those changes to make sure the content is still good. You can track the open pull requests (PRs) via Github's notification feature.
+- When changes occur to the technology that require documentation to be updated, your team needs to make updates as appropriate, maintaining the same standards as the original documentation.
+
+If positive changes are not observed over a period of 6 months and the documentation appears to be:
+
+- Stale or unmaintained
+- Stalled without being finished
+- Low quality
+- Becoming obsolete
+
+Then the documentation for this technology will be considered dead. After a discussion between your team and the MDN Web Docs team representative, the documentation will be removed.
+
+We hope you understand that we need to be strict on such matters — we can't let the site fill up with bad quality, incomplete, or obsolete documentation.
diff --git a/files/en-us/mdn/writing-guidelines/what-we-write/index.md b/files/en-us/mdn/writing-guidelines/what-we-write/index.md
new file mode 100644
index 000000000000000..1727e34a6867254
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/what-we-write/index.md
@@ -0,0 +1,118 @@
+---
+title: What we write
+slug: MDN/Writing_guidelines/What_we_write
+page-type: mdn-writing-guide
+tags:
+  - meta
+  - writing-guide
+---
+{{MDNSidebar}}  
+
+MDN Web Docs contains _browser-neutral_ documentation that enables web developers to write _browser-agnostic_ code. In this article, you'll find information about whether or not a given topic and/or type of content should be included on MDN Web Docs.
+
+## Suggesting content
+
+If you'd like to suggest content for MDN Web Docs, please make sure you read this page before submitting to ensure what you are suggesting is appropriate.
+
+For new reference pages or guides please open a discussion on [our community repository](https://github.com/mdn/mdn-community/discussions/categories/content-suggestions) outlining what content you are suggesting and why (please be as explicit as possible).
+
+For suggesting larger projects which involve new sections of content, please refer to the [Inclusion criteria page](/en_US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria) which also outlines the application process.
+
+## Topics that belong on MDN Web Docs
+
+In general, if it's an open web technology, we document it on MDN Web Docs. This includes any feature that can be used by web developers to create websites and applications, now and in the near future.
+
+If a feature is implemented by multiple browsers and either accepted as standard or is progressing towards standardization, then yes, we definitely document it here. If a feature is still very experimental and not implemented in multiple browsers and/or liable to change, then it is still suitable for inclusion, but may not be seen as a priority for the writer's team to work on.
+
+In other words, web technologies to be documented on MDN Web Docs should fulfil the following criteria:
+
+- Be on a standards track.
+- Be specified in a specification published by a reliable standards body.
+- Be implemented by at least one rendering engine.
+- Be released in a stable browser version.
+
+Our primary focus is to write about the following front-end web technologies:
+
+- [HTML](/en-US/docs/Web/HTML)
+- [CSS](/en-US/docs/Web/CSS)
+- [JavaScript](/en-US/docs/Web/JavaScript)
+- [Web APIs](/en-US/docs/Web/API)
+- [HTTP](/en-US/docs/Web/HTTP)
+
+We also document some broader topics, such as [SVG](/en-US/docs/Web/SVG), [XML](/en-US/docs/Web/XML), [WebAssembly](/en-US/docs/WebAssembly), and [Accessibility](/en-US/docs/Learn/Accessibility). In addition, we provide extensive [learning guides](/en-US/docs/Learn) for these technologies and also a [glossary](/en-US/docs/Glossary).
+
+> **Note:** Backend technologies usually have their own documentation elsewhere that MDN Web Docs does not attempt to supersede, although we [do have some exceptions](/en-US/docs/Learn/Server-side).
+
+All content on MDN Web Docs must be relevant to the technology section in which it appears. Contributors are expected to follow these [MDN writing guidelines](/en-US/docs/MDN/Writing_guidelines) for writing style, code samples, and other topics.
+
+For more details on acceptance criteria for whether or not a technology can be documented on MDN Web Docs, see the [Criteria for inclusion]
+
+### When we document a new technology
+
+On MDN web Docs, we are constantly looking to document new web standards technologies as appropriate.
+We try to strike a balance between publishing the documentation early enough so that developers can learn about new features as soon as they need to and publishing it late enough so that the technology is mature and stable so the documentation won't need constant updates or rapid removal.
+
+In general, our definition of the earliest we'll consider documenting a new technology is:
+
+_"When the feature is on a standards track and is implemented somewhere."_
+
+We consider documenting a new technology if:
+
+- It is specified in a specification document published under a reliable standards organization (such as W3C, WHATWG, Khronos, IETF, etc.) and has reached a reasonable level of stability (e.g., a W3C working draft or candidate recommendation or when the specification is looking fairly stable judging by the flow of issues filed against it).
+- It is implemented consistently in at least one browser, with other browser developers showing signs of interest (such as an active ticket or an "intent to implement" process is in effect).
+
+We do not document a new technology if it:
+
+- Doesn't have a specification or the specification is a rough note that looks liable to change.
+- One or zero browsers have currently implemented it and non-supporting browsers are not showing signs of interest in implementing it. You can gauge this by asking engineers who work on those browsers and by looking at browser bug trackers and mailing lists, etc.
+- Not a web-exposed technology and/or is completely proprietary.
+- Already showing signs of being deprecated or superseded by a similar feature.
+
+## Topics that don't belong on MDN Web Docs
+
+In general, anything that isn't an open web standard does not belong on MDN Web Docs. Spam (commercial advertisement) and other irrelevant content will never be accepted into the site. Contributors who keep trying to submit spam may be banned from MDN at the discretion of Mozilla MDN staff.
+
+Examples of inappropriate topics for MDN Web Docs include:
+
+- Technology that is not exposed to the web and is specific to a browser.
+- Technology that is not related to the web.
+- Documentation for end-users. For Mozilla products, for example, such documentation belongs on the [Mozilla support site](https://support.mozilla.org).
+- Self-linking or self-promoting external links. Check out these guidelines before adding an external link.
+
+### When we remove documentation
+
+Pages are deleted from MDN Web Docs if they don't contain information that is useful in any way anymore, are out-of-date enough, and/or might be incorrect to the point where keeping them around might be misleading.
+
+Pages might be deleted when:
+
+- Articles containing information about features that weren't implemented across all browsers and have later been withdrawn (usually experimental features such as prefixed functionality).
+- Reference pages for features that were removed from the specification before they were implemented in any browser.
+- Articles covering techniques that were later shown to be bad practices and superseded by better techniques.
+- Articles containing information that were later replaced by other, better quality articles.
+- Articles containing content that is inappropriate for MDN Web Docs.
+- Sections of MDN Web Docs which are not focused on open web technologies and are a maintenance burden.
+
+For more information on _how_ to delete documents, please see the [Creating, moving and deleting pages guide]()
+
+
+## Types of documents on MDN Web Docs
+
+Generally our documentation falls into the following categories:
+
+- Reference
+- Guide
+- Glossary
+- Learn/Tutorials
+
+In general, MDN Web Docs is for _product_ documentation, not for _project_ or _process_ documentation. So, if the document is about "how to use a thing" or "how a thing works" (where, the "thing" is in one of the topic categories mentioned above), then it can go on MDN Web Docs.
+
+If a document is about "who's working on developing a thing" or "plans for developing a thing", then it shouldn't go on MDN Web Docs.
+
+Here are some examples of types of documents that should _not_ be placed on MDN Web Docs:
+
+- Planning documents
+- Design documents
+- Project proposals
+- Specifications or standards
+- Promotional material, advertising, or personal information
+
diff --git a/files/en-us/mdn/writing-guidelines/writing-style-guide/code-style-guide/css/index.md b/files/en-us/mdn/writing-guidelines/writing-style-guide/code-style-guide/css/index.md
new file mode 100644
index 000000000000000..0d58e96408ca996
--- /dev/null
+++ b/files/en-us/mdn/writing-guidelines/writing-style-guide/code-style-guide/css/index.md
@@ -0,0 +1,225 @@
+---
+title: Guidelines for styling CSS code examples
+slug:
+tags:
+  - CSS
+  - Code
+  - Guide
+  - Guidelines
+  - MDN Meta
+---
+{{MDNSidebar}}
+
+The following guidelines cover how to write CSS example code for MDN Web Docs.
+
+## General guidelines for CSS code examples
+
+### Plan your CSS
+
+Before diving in and writing huge chunks of CSS, plan your styles carefully. What general styles are going to be needed, what different layouts do you need to create, what specific overrides need to be created, and are they reusable? Above all, you need to try to **avoid too much overriding**. If you keep finding yourself writing styles and then cancelling them again a few rules down, you probably need to rethink your strategy.
+
+### Use flexible/relative units
+
+For maximum flexibility over the widest possible range of devices, it is a good idea to size containers, padding, etc. using relative units like ems and rems or percentages and viewport units if you want them to vary depending on viewport width. You can read some more about this in our [Responsive design building blocks](/en-US/docs/Web/Progressive_web_apps/Responsive/responsive_design_building_blocks#fluid_grids) article.
+
+### Don't use preprocessors
+
+Don't use preprocessor syntax, such as [Sass](https://sass-lang.com/), [Less](https://lesscss.org/), or [Stylus,](https://stylus-lang.com/), in the example code. On MDN Web Docs, we document the vanilla CSS language. Using preprocessors will only raise the bar to understanding the examples, potentially confusing readers.
+
+### Don't use specific CSS methodologies
+
+In the same spirit as the previous guideline, don't write example codes on MDN Web Docs using a specific CSS methodology such as [BEM](http://getbem.com/naming/) or [SMACSS](http://smacss.com/). Even though they are valid CSS syntax, the naming conventions can be confusing to people not familiar with those methodologies.
+
+### Don't use resets 
+
+For maximum control over CSS across platforms, a lot of people used to use CSS resets to remove every style, before then building things back up themselves. This certainly has its merits, but especially in the modern world, CSS resets can be an overkill, resulting in a lot of extra time spent reimplementing things that weren't completely broken in the first place, like default margins, list styles, etc.
+
+If you really feel like you need to use a reset, consider using [normalize.css by Nicolas Gallagher](https://necolas.github.io/normalize.css/), which aims to just make things more consistent across browsers, get rid of some default annoyances that we always remove (the margins on ``, for example) and fix a few bugs.
+
+## !important
+
+`!important` is the last resort that is generally used only when you need to override something and there is no other way to do it. Using `!important` is a bad practice and you should avoid it wherever possible.
+
+```css example-bad
+.bad-code {
+  font-size: 4rem !important;
+}
+```
+
+## CSS comments
+
+Use CSS-style comments to comment code that isn't self-documenting. Also note that you should leave a space between the asterisks and the comment.
+
+```css example-good
+/* This is a CSS-style comment */
+```
+
+Put your comments on separate lines preceding the code they are referring to, like so:
+
+```css example-good
+h3 {
+  /* Creates a red drop shadow, offset 1px right and down, w/2px blur radius */
+  text-shadow: 1px 1px 2px red;
+  /* Sets the font-size to double the default document font size */
+  font-size: 2rem;
+}
+```
+
+## Double quotes around values
+
+Where quotes can or should be included, use them, and use double quotes. For example:
+
+```css example-good
+[data-vegetable="liquid"] {
+  background-color: goldenrod;
+  background-image: url("../../media/examples/lizard.png");
+}
+```
+
+## Longhand vs. shorthand rules
+
+Usually when teaching the specifics of CSS syntax, it is clearer and more obvious to use longhand properties, rather than terse shorthand (unless of course you're explaining shorthand through the example). Remember that the point of examples on MDN Web Docs is to teach people, not to be clever or efficient. We explain here why recommend writing longhand rules.
+
+- It is often harder to understand what the shorthand is doing. In the example below, it takes a while to pick apart exactly what the {{cssxref("font")}} syntax is doing.
+
+  ```css
+  font: small-caps bold 2rem/1.5 sans-serif;
+  ```
+
+  Whereas the following style is clearer:
+
+  ```css
+  font-variant: small-caps;
+  font-weight: bold;
+  font-size: 2rem;
+  line-height: 1.5;
+  font-family: sans-serif;
+  ```
+
+- CSS shorthand comes with potential added pitfalls — default values are set for parts of the syntax that you don't explicitly set, which can produce unexpected resets of values you've set earlier in the cascade or other expected effects. The {{cssxref("grid")}} property, for example, sets all of the following default values for items that are not specified:
+
+  - {{cssxref("grid-template-rows")}}: `none`
+  - {{cssxref("grid-template-columns")}}: `none`
+  - {{cssxref("grid-template-areas")}}: `none`
+  - {{cssxref("grid-auto-rows")}}: `auto`
+  - {{cssxref("grid-auto-columns")}}: `auto`
+  - {{cssxref("grid-auto-flow")}}: `row`
+  - {{cssxref("column-gap")}}: `0`
+  - {{cssxref("row-gap")}}: `0`
+  - {{cssxref("column-gap")}}: `normal`
+  - {{cssxref("row-gap")}}: `normal`
+
+- Some shorthands only work as expected if you include the different value components in a certain order. This is the case in CSS animations. In the example below, the expected order is written as a comment:
+
+  ```css
+  /* duration | timing-function | delay | iteration-count
+    direction | fill-mode | play-state | name */
+  animation: 3s ease-in 1s 2 reverse both paused slidein;
+  ```
+
+  In this example, the first value that can be parsed as a [`
            
-  
-  
-    
-      
-      
-      
-      
-    
-  
-  
-    
-      
-      
-      
-      
-    
-    
-      
-      
-      
-      
-    
-    
-      
-      
-      
-      
-    
-    
-      
-      
-      
-      
-    
-  
-
            
-    Attributes of a data property
-  
            AttributeTypeDescriptionDefault value
            [[Value]]Any JavaScript typeThe value retrieved by a get access of the property.undefined
            [[Writable]]Boolean
-        If false, the property's [[Value]] cannot be changed.
-      false
            [[Enumerable]]Boolean
-        
            
-          If true, the property will be enumerated in
-          for...in
-          loops.
            See also
-          Enumerability and ownership of properties.
-        
            
-                  		false
            [[Configurable]]Boolean
-        If false, the property cannot be deleted, cannot be changed
-        to an accessor property, and attributes other than [[Value]] and
-        [[Writable]] cannot be changed.
-      false
            
-
-| Attribute  | Type    | Description                                           |
-| ---------- | ------- | ----------------------------------------------------- |
-| Read-only  | Boolean | Reversed state of the ES5 [[Writable]] attribute.     |
-| DontEnum   | Boolean | Reversed state of the ES5 [[Enumerable]] attribute.   |
-| DontDelete | Boolean | Reversed state of the ES5 [[Configurable]] attribute. |
+Data properties associate a key with a value. It can be described by the following attributes:
+
+- `value`
+  - : The value retrieved by a get access of the property. Can be any JavaScript value.
+- `writable`
+  - : A boolean value indicating if the property can be changed with an assignment.
+- `enumerable`
+  - : A boolean value indicating if the property can be enumerated by a [`for...in`](/en-US/docs/Web/JavaScript/Reference/Statements/for...in) loop. See also [Enumerability and ownership of properties](/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties) for how enumerability interacts with other functions and syntaxes.
+- `configurable`
+  - : A boolean value indicating if the property can be deleted, can be changed to an accessor property, and can have its attributes changed.
 
 #### Accessor property
 
@@ -237,12 +178,14 @@ Associates a key with one of two accessor functions (`get` and `set`) to retriev
 
 An accessor property has the following attributes:
 
-| Attribute        | Type                           | Description                                                                                                                                                                                                              | Default value |
-| ---------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
-| [[Get]]          | Function object or `undefined` | The function is called with an empty argument list and retrieves the property value whenever a get access to the value is performed. See also [`get`](/en-US/docs/Web/JavaScript/Reference/Functions/get).               | `undefined`   |
-| [[Set]]          | Function object or `undefined` | The function is called with an argument that contains the assigned value and is executed whenever a specified property is attempted to be changed. See also [`set`](/en-US/docs/Web/JavaScript/Reference/Functions/set). | `undefined`   |
-| [[Enumerable]]   | Boolean                        | If `true`, the property will be enumerated in [`for...in`](/en-US/docs/Web/JavaScript/Reference/Statements/for...in) loops.                                                                                                | `false`       |
-| [[Configurable]] | Boolean                        | If `false`, the property can't be deleted and can't be changed to a data property.                                                                                                                                       | `false`       |
+- `get`
+  - : A function called with an empty argument list to retrieve the property value whenever a get access to the value is performed. See also [getters](/en-US/docs/Web/JavaScript/Reference/Functions/get). May be `undefined`.
+- `set`
+  - : A function called with an argument that contains the assigned value. Executed whenever a specified property is attempted to be changed. See also [setters](/en-US/docs/Web/JavaScript/Reference/Functions/get). May be `undefined`.
+- `enumerable`
+  - : A boolean value indicating if the property can be enumerated by a [`for...in`](/en-US/docs/Web/JavaScript/Reference/Statements/for...in) loop. See also [Enumerability and ownership of properties](/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties) for how enumerability interacts with other functions and syntaxes.
+- `configurable`
+  - : A boolean value indicating if the property can be deleted, can be changed to an data property, and can have its attributes changed.
 
 ### "Normal" objects, and functions
 
diff --git a/files/en-us/web/javascript/reference/global_objects/promise/then/index.md b/files/en-us/web/javascript/reference/global_objects/promise/then/index.md
index e5fefda372ae146..967b85566fc1488 100644
--- a/files/en-us/web/javascript/reference/global_objects/promise/then/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/promise/then/index.md
@@ -74,22 +74,22 @@ method.
 // but its handlers will be triggered asynchronously as demonstrated by the console.logs
 const resolvedProm = Promise.resolve(33);
 
-let thenProm = resolvedProm.then(value => {
-    console.log("this gets called after the end of the main stack. the value received and returned is: " + value);
-    return value;
+const thenProm = resolvedProm.then((value) => {
+  console.log("this gets called after the end of the main stack. the value received and returned is: ", value);
+  return value;
 });
 // instantly logging the value of thenProm
 console.log(thenProm);
 
 // using setTimeout we can postpone the execution of a function to the moment the stack is empty
 setTimeout(() => {
-    console.log(thenProm);
+  console.log(thenProm);
 });
 
 // logs, in order:
-// Promise {[[PromiseStatus]]: "pending", [[PromiseValue]]: undefined}
+// Promise {[[PromiseStatus]]: "pending", [[PromiseResult]]: undefined}
 // "this gets called after the end of the main stack. the value received and returned is: 33"
-// Promise {[[PromiseStatus]]: "resolved", [[PromiseValue]]: 33}
+// Promise {[[PromiseStatus]]: "resolved", [[PromiseResult]]: 33}
 ```
 
 ## Description
diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/from/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/from/index.md
index 49c03598e59a6ab..49d61858aa9677c 100644
--- a/files/en-us/web/javascript/reference/global_objects/typedarray/from/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/typedarray/from/index.md
@@ -94,8 +94,8 @@ Some subtle distinctions between {{jsxref("Array.from()")}} and
   `TypedArray.from()` is not a constructor,
   `TypedArray.from()` will throw a {{jsxref("TypeError")}},
   where `Array.from()` defaults to creating a new {{jsxref("Array")}}.
-- `TypedArray.from()` uses `[[Put]]` where
-  `Array.from()` uses `[[DefineProperty]]`. Hence, when
+- `TypedArray.from()` uses `[[Set]]` where
+  `Array.from()` uses `[[DefineOwnProperty]]`. Hence, when
   working with {{jsxref("Proxy")}} objects, it calls
   {{jsxref("Global_Objects/Proxy/handler/set", "handler.set")}} to create new
   elements rather than {{jsxref("Global_Objects/Proxy/handler/defineProperty",
diff --git a/files/en-us/web/javascript/reference/global_objects/typedarray/of/index.md b/files/en-us/web/javascript/reference/global_objects/typedarray/of/index.md
index f6c9d27b9f73a79..1c4db421c6b8be9 100644
--- a/files/en-us/web/javascript/reference/global_objects/typedarray/of/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/typedarray/of/index.md
@@ -58,8 +58,8 @@ Some subtle distinctions between {{jsxref("Array.of()")}} and
   not a constructor, `TypedArray.of()` will throw a
   {{jsxref("TypeError")}}, where `Array.of()` defaults to creating a new
   {{jsxref("Array")}}.
-- `TypedArray.of()` uses `[[Put]]` where
-  `Array.of()` uses `[[DefineProperty]]`. Hence, when working with
+- `TypedArray.of()` uses `[[Set]]` where
+  `Array.of()` uses `[[DefineOwnProperty]]`. Hence, when working with
   {{jsxref("Proxy")}} objects, it calls {{jsxref("Global_Objects/Proxy/handler/set",
     "handler.set")}} to create new elements rather than
   {{jsxref("Global_Objects/Proxy/handler/defineProperty", "handler.defineProperty()")}}.

From eef5e4d1e0922f7e52ff2e2bf1cb975e4afec804 Mon Sep 17 00:00:00 2001
From: simonvarey <88859869+simonvarey@users.noreply.github.com>
Date: Mon, 18 Jul 2022 10:23:01 -0400
Subject: [PATCH 35/70] Change 'nodes' link to link directly to DOM nodes
 (#18480)

The link to DOM 'nodes' currently links to the 'nodes' glossary page. I changed the link to DOM 'nodes' to directly link to the DOM nodes page.
---
 files/en-us/glossary/shadow_tree/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/files/en-us/glossary/shadow_tree/index.md b/files/en-us/glossary/shadow_tree/index.md
index 71481be589f364c..15a5b8c5e34a469 100644
--- a/files/en-us/glossary/shadow_tree/index.md
+++ b/files/en-us/glossary/shadow_tree/index.md
@@ -7,7 +7,7 @@ tags:
   - Shadow Tree
   - shadow DOM
 ---
-A **shadow tree** is a tree of DOM {{Glossary("node", "nodes")}} whose topmost node is a **shadow root**; that is, the topmost node within a **shadow DOM**. A shadow tree is a hidden set of standard DOM nodes which is attached to a standard DOM node that serves as a host. The hidden nodes are not directly visible using regular DOM functionality, but require the use of a special [Shadow DOM API](/en-US/docs/Web/Web_Components/Using_shadow_DOM) to access.
+A **shadow tree** is a tree of DOM [nodes](/en-US/docs/Glossary/Node/DOM) whose topmost node is a **shadow root**; that is, the topmost node within a **shadow DOM**. A shadow tree is a hidden set of standard DOM nodes which is attached to a standard DOM node that serves as a host. The hidden nodes are not directly visible using regular DOM functionality, but require the use of a special [Shadow DOM API](/en-US/docs/Web/Web_Components/Using_shadow_DOM) to access.
 
 Nodes within the shadow tree are not affected by anything applied outside the shadow tree, and vice versa. This provides a way to encapsulate implementation details, which is especially useful for custom elements and other advanced design paradigms.
 

From 5cda559d3142f49f012b174d2384a3ae8fb7c6fa Mon Sep 17 00:00:00 2001
From: Joshua Chen 
Date: Mon, 18 Jul 2022 22:23:52 +0800
Subject: [PATCH 36/70] Shorten Global object glossary entry (#18474)

---
 files/en-us/glossary/global_object/index.md | 45 ++-------------------
 1 file changed, 3 insertions(+), 42 deletions(-)

diff --git a/files/en-us/glossary/global_object/index.md b/files/en-us/glossary/global_object/index.md
index 50b48bdbd47ffcd..c8c8592304ef108 100644
--- a/files/en-us/glossary/global_object/index.md
+++ b/files/en-us/glossary/global_object/index.md
@@ -14,50 +14,11 @@ In JavaScript, there's always a global object defined. In a web browser, when sc
 - Code running in a {{domxref("Worker")}} has a {{domxref("WorkerGlobalScope")}} object as its global object.
 - Scripts running under {{Glossary("Node.js")}} have an object called [`global`](https://nodejs.org/api/globals.html#globals_global) as their global object.
 
-> **Note**: Unlike {{jsxref("Statements/var", "var")}}, the statements {{jsxref("Statements/let", "let")}} and {{jsxref("Statements/const", "const")}} do not create properties of the global object.
+The [`globalThis`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis) global property allows one to access the global object regardless of the current environment.
 
-## `window` object in the Browser
+[`var`](/en-US/docs/Web/JavaScript/Reference/Statements/var) statements and [function declarations](/en-US/docs/Web/JavaScript/Reference/Statements/function) at the top level create properties of the global object. On the other hand, {{jsxref("Statements/let", "let")}} and {{jsxref("Statements/const", "const")}} declarations never create properties of the global object.
 
-The `window` object is the Global Object in the Browser. Any Global Variables or Functions can be accessed as _properties_ of the `window` object.
-
-### Access Global Variables
-
-```js
-var foo = "foobar";
-foo === window.foo; // Returns: true
-```
-
-After defining a Global Variable `foo`, we can access its value directly from the `window` object, by using the variable name `foo` as a property name of the Global Object `window.foo`.
-
-#### Explanation:
-
-The global variable `foo` was stored in the `window` object, like this:
-
-```js
-foo: "foobar"
-```
-
-### Access Global Functions
-
-```js
-function greeting() {
-   console.log("Hi!");
-}
-
-window.greeting(); // It is the same as the normal invoking: greeting();
-```
-
-The example above explains how Global Functions are stored as _properties_ in the `window` object. We created a Global Function called `greeting`, then invoked it using the `window` object.
-
-#### Explanation:
-
-The global function `greeting` was stored in the `window` object, like this:
-
-```js
-greeting: function greeting() {
-   console.log("Hi!");
-}
-```
+The properties of the global object are automatically added to the {{glossary("global scope")}}.
 
 ## See also
 

From 7e27a47836369a529370b55141093d1cfbd4ab22 Mon Sep 17 00:00:00 2001
From: Hamish Willee 
Date: Tue, 19 Jul 2022 00:52:22 +1000
Subject: [PATCH 37/70] FF103 Native Error types are serializable (#18384)

* FF104 Native Error types are serializable

* Fix error - this is in FF103, not 104

* Update files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md

Co-authored-by: Joshua Chen 

* Remove stack info from release note

* Update files/en-us/mozilla/firefox/releases/103/index.md

Co-authored-by: Joshua Chen 
---
 files/en-us/mozilla/firefox/releases/103/index.md  |  7 +++++++
 .../structured_clone_algorithm/index.md            | 14 ++++++++++----
 .../reference/global_objects/error/index.md        |  2 ++
 .../reference/global_objects/evalerror/index.md    |  2 ++
 .../reference/global_objects/rangeerror/index.md   |  2 ++
 .../global_objects/referenceerror/index.md         |  2 ++
 .../reference/global_objects/syntaxerror/index.md  |  2 ++
 .../reference/global_objects/typeerror/index.md    |  2 ++
 .../reference/global_objects/urierror/index.md     |  2 ++
 9 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/files/en-us/mozilla/firefox/releases/103/index.md b/files/en-us/mozilla/firefox/releases/103/index.md
index ba711b16307891d..67045794013c0f1 100644
--- a/files/en-us/mozilla/firefox/releases/103/index.md
+++ b/files/en-us/mozilla/firefox/releases/103/index.md
@@ -25,6 +25,13 @@ This article provides information about the changes in Firefox 103 that will aff
 
 ### JavaScript
 
+- Native Error types can now be serialized using the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm).
+  This includes {{JSxRef("Error")}}, {{JSxRef("EvalError")}}, {{JSxRef("RangeError")}}, {{JSxRef("ReferenceError")}}, {{JSxRef("SyntaxError")}}, {{JSxRef("TypeError")}}, {{JSxRef("URIError")}} and {{JSxRef("AggregateError")}}.
+  Serialized properties include the [`name`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/name), [`message`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/message), [`cause`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause), [`fileName`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/fileName), [`lineNumber`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/lineNumber) and [`columnNumber`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/columnNumber).
+  
+  For {{JSxRef("AggregateError")}} the `message`, `name`, `cause` and `errors` properties are serialized.
+  See {{bug(1556604)}} for more details.
+
 #### Removals
 
 ### HTTP
diff --git a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md
index 4c06f21c74b7328..6ada80d16b7d543 100644
--- a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md
+++ b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md
@@ -27,9 +27,6 @@ It clones by recursing through the input object while maintaining a map of previ
     For example, if an object is marked readonly with a [property descriptor](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor), it will be read/write in the duplicate, since that's the default.
   - The prototype chain is not walked or duplicated.
 
-> **Note:** Native {{jsxref("Error")}} types can be cloned in Chrome.
-> Firefox can clone {{domxref("DOMException")}}, and is [working on the other error types](https://bugzilla.mozilla.org/show_bug.cgi?id=1556604).
-
 ## Supported types
 
 
@@ -112,7 +109,16 @@ It clones by recursing through the input object while maintaining a map of previ
     
-      
+      
+    
+    
+      
+      
            
     
            
       {{domxref("DOMException")}}Most browsers only clone the properties {{domxref("DOMException.name","name")}} and {{domxref("DOMException.message","message")}} (in theory stack traces and other attributes may also be cloned).Browsers must serialize the properties {{domxref("DOMException.name","name")}} and {{domxref("DOMException.message","message")}}.
+      Other attributes may also be serialized/cloned.
            Native Error types
+        
            The error name must be one of: {{jsxref("Error")}}, {{JSxRef("EvalError")}}, {{JSxRef("RangeError")}}, {{JSxRef("ReferenceError")}}, {{JSxRef("SyntaxError")}}, {{JSxRef("TypeError")}}, {{JSxRef("URIError")}} (or will be set to "Error").
            
+        
            Browsers must serialize the properties name and message, and are expected to serialise "interesting" other properties of the errors such as stack, cause, etc.
            
+        
            {{JSxRef("AggregateError")}} support is expected to be added to the specification in whatwg/html#5749 (and is already supported in some browsers).
            
+                  		
     
            
               
 
            
diff --git a/files/en-us/web/javascript/reference/global_objects/error/index.md b/files/en-us/web/javascript/reference/global_objects/error/index.md
index 4f7007c52893334..b7bbcc75f023380 100644
--- a/files/en-us/web/javascript/reference/global_objects/error/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/error/index.md
@@ -17,6 +17,8 @@ browser-compat: javascript.builtins.Error
 
 Runtime errors result in new `Error` objects being created and thrown.
 
+`Error` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}}.
+
 ### Error types
 
 Besides the generic `Error` constructor, there are other core error constructors in JavaScript. For client-side exceptions, see [Exception handling statements](/en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling#exception_handling_statements).
diff --git a/files/en-us/web/javascript/reference/global_objects/evalerror/index.md b/files/en-us/web/javascript/reference/global_objects/evalerror/index.md
index 77cf8c5734c62e2..121cfc718965d2e 100644
--- a/files/en-us/web/javascript/reference/global_objects/evalerror/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/evalerror/index.md
@@ -13,6 +13,8 @@ browser-compat: javascript.builtins.EvalError
 
 The **`EvalError`** object indicates an error regarding the global {{jsxref("Global_Objects/eval", "eval()")}} function. This exception is not thrown by JavaScript anymore, however the `EvalError` object remains for compatibility.
 
+`EvalError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}}.
+
 ## Constructor
 
 - {{jsxref("EvalError/EvalError", "EvalError()")}}
diff --git a/files/en-us/web/javascript/reference/global_objects/rangeerror/index.md b/files/en-us/web/javascript/reference/global_objects/rangeerror/index.md
index 9d32075d20a7867..77a44e035b39c1e 100644
--- a/files/en-us/web/javascript/reference/global_objects/rangeerror/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/rangeerror/index.md
@@ -22,6 +22,8 @@ This can be encountered when:
 - when attempting to create an array of an illegal length with the {{jsxref("Array")}} constructor, or
 - when passing bad values to the numeric methods {{jsxref("Number.prototype.toExponential()")}}, {{jsxref("Number.prototype.toFixed()")}} or {{jsxref("Number.prototype.toPrecision()")}}.
 
+`RangeError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}}.
+
 ## Constructor
 
 - {{jsxref("RangeError/RangeError", "RangeError()")}}
diff --git a/files/en-us/web/javascript/reference/global_objects/referenceerror/index.md b/files/en-us/web/javascript/reference/global_objects/referenceerror/index.md
index 1c58bbd8c18afce..8bd1addd0e244bb 100644
--- a/files/en-us/web/javascript/reference/global_objects/referenceerror/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/referenceerror/index.md
@@ -13,6 +13,8 @@ browser-compat: javascript.builtins.ReferenceError
 
 The **`ReferenceError`** object represents an error when a variable that doesn't exist (or hasn't yet been initialized) in the current scope is referenced.
 
+`ReferenceError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}}.
+
 ## Constructor
 
 - {{jsxref("Global_Objects/ReferenceError/ReferenceError", "ReferenceError()")}}
diff --git a/files/en-us/web/javascript/reference/global_objects/syntaxerror/index.md b/files/en-us/web/javascript/reference/global_objects/syntaxerror/index.md
index df8e3a479178178..1514e4afd8ddec1 100644
--- a/files/en-us/web/javascript/reference/global_objects/syntaxerror/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/syntaxerror/index.md
@@ -13,6 +13,8 @@ browser-compat: javascript.builtins.SyntaxError
 
 The **`SyntaxError`** object represents an error when trying to interpret syntactically invalid code. It is thrown when the JavaScript engine encounters tokens or token order that does not conform to the syntax of the language when parsing code.
 
+`SyntaxError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}}.
+
 ## Constructor
 
 - {{jsxref("Global_Objects/SyntaxError/SyntaxError", "SyntaxError()")}}
diff --git a/files/en-us/web/javascript/reference/global_objects/typeerror/index.md b/files/en-us/web/javascript/reference/global_objects/typeerror/index.md
index 44959bc235aabfd..b2ad35bc635e4d3 100644
--- a/files/en-us/web/javascript/reference/global_objects/typeerror/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/typeerror/index.md
@@ -19,6 +19,8 @@ A `TypeError` may be thrown when:
 - when attempting to modify a value that cannot be changed; or
 - when attempting to use a value in an inappropriate way.
 
+`TypeError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}}.
+
 ## Constructor
 
 - {{jsxref("Global_Objects/TypeError/TypeError", "TypeError()")}}
diff --git a/files/en-us/web/javascript/reference/global_objects/urierror/index.md b/files/en-us/web/javascript/reference/global_objects/urierror/index.md
index b13cfd5956a04ca..6a40466dc31afbb 100644
--- a/files/en-us/web/javascript/reference/global_objects/urierror/index.md
+++ b/files/en-us/web/javascript/reference/global_objects/urierror/index.md
@@ -13,6 +13,8 @@ browser-compat: javascript.builtins.URIError
 
 The **`URIError`** object represents an error when a global URI handling function was used in a wrong way.
 
+`URIError` is a {{Glossary("serializable object")}}, so it can be cloned with {{domxref("structuredClone()")}} or copied between [Workers](/en-US/docs/Web/API/Worker) using {{domxref("Worker.postMessage()", "postMessage()")}}.
+
 ## Constructor
 
 - {{jsxref("Global_Objects/URIError/URIError", "URIError()")}}

From fd9ca3cc2bb05c49c0fdee3eb94fa94b8e32dcde Mon Sep 17 00:00:00 2001
From: "Queen Vinyl Da.i'gyu-Kazotetsu" 
Date: Mon, 18 Jul 2022 08:17:37 -0700
Subject: [PATCH 38/70] Demix invalid event from GlobalEventHandlers (#18451)

---
 files/en-us/_redirects.txt                    |  3 +-
 files/en-us/_wikihistory.json                 | 11 ---
 .../web/api/globaleventhandlers/index.md      |  2 -
 .../globaleventhandlers/oninvalid/index.md    | 95 -------------------
 .../htmlinputelement/invalid_event/index.md   | 35 +++----
 5 files changed, 16 insertions(+), 130 deletions(-)
 delete mode 100644 files/en-us/web/api/globaleventhandlers/oninvalid/index.md

diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt
index dbb28aaee3fcf6f..4c39f63889ca563 100644
--- a/files/en-us/_redirects.txt
+++ b/files/en-us/_redirects.txt
@@ -8124,7 +8124,7 @@
 /en-US/docs/Web/API/GlobalEventHandlers/GlobalEventHandlers.ondurationchange	/en-US/docs/Web/API/HTMLMediaElement/durationchange_event
 /en-US/docs/Web/API/GlobalEventHandlers/GlobalEventHandlers.onemptied	/en-US/docs/Web/API/HTMLMediaElement/emptied_event
 /en-US/docs/Web/API/GlobalEventHandlers/GlobalEventHandlers.onended	/en-US/docs/Web/API/HTMLMediaElement/ended_event
-/en-US/docs/Web/API/GlobalEventHandlers/GlobalEventHandlers.oninvalid	/en-US/docs/Web/API/GlobalEventHandlers/oninvalid
+/en-US/docs/Web/API/GlobalEventHandlers/GlobalEventHandlers.oninvalid	/en-US/docs/Web/API/HTMLInputElement/invalid_event
 /en-US/docs/Web/API/GlobalEventHandlers/GlobalEventHandlers.onloadeddata	/en-US/docs/Web/API/GlobalEventHandlers/onloadeddata
 /en-US/docs/Web/API/GlobalEventHandlers/GlobalEventHandlers.onloadedmetadata	/en-US/docs/Web/API/GlobalEventHandlers/onloadedmetadata
 /en-US/docs/Web/API/GlobalEventHandlers/GlobalEventHandlers.onloadstart	/en-US/docs/Web/API/GlobalEventHandlers/onloadstart
@@ -8164,6 +8164,7 @@
 /en-US/docs/Web/API/GlobalEventHandlers/onfocus	/en-US/docs/Web/API/Window/focus_event
 /en-US/docs/Web/API/GlobalEventHandlers/onformdata	/en-US/docs/Web/API/HTMLFormElement/formdata_event
 /en-US/docs/Web/API/GlobalEventHandlers/oninput	/en-US/docs/Web/API/HTMLElement/input_event
+/en-US/docs/Web/API/GlobalEventHandlers/oninvalid	/en-US/docs/Web/API/HTMLInputElement/invalid_event
 /en-US/docs/Web/API/GlobalEventHandlers/onkeydown	/en-US/docs/Web/API/Element/keydown_event
 /en-US/docs/Web/API/GlobalEventHandlers/onkeypress	/en-US/docs/Web/API/Element/keypress_event
 /en-US/docs/Web/API/GlobalEventHandlers/onkeyup	/en-US/docs/Web/API/Element/keyup_event
diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json
index 696ac1003e75b64..5f9e08a0ea50cf5 100644
--- a/files/en-us/_wikihistory.json
+++ b/files/en-us/_wikihistory.json
@@ -44291,17 +44291,6 @@
       "jpmedley"
     ]
   },
-  "Web/API/GlobalEventHandlers/oninvalid": {
-    "modified": "2020-10-15T21:44:05.936Z",
-    "contributors": [
-      "mfluehr",
-      "fscholz",
-      "sideshowbarker",
-      "wbamberg",
-      "rolfedh",
-      "Guillaume-Heras"
-    ]
-  },
   "Web/API/GlobalEventHandlers/onload": {
     "modified": "2020-10-15T21:12:46.292Z",
     "contributors": [
diff --git a/files/en-us/web/api/globaleventhandlers/index.md b/files/en-us/web/api/globaleventhandlers/index.md
index eb45e6d124f5192..b44491169c3b241 100644
--- a/files/en-us/web/api/globaleventhandlers/index.md
+++ b/files/en-us/web/api/globaleventhandlers/index.md
@@ -35,8 +35,6 @@ These event handlers are defined on the {{domxref("GlobalEventHandlers")}} mixin
   - : An [event handler](/en-US/docs/Web/Events/Event_handlers) for processing {{domxref("HTMLFormElement/formdata_event", "formdata")}} events, fired after the entry list representing the form's data is constructed.
 - {{domxref("GlobalEventHandlers.ongotpointercapture")}}
   - : An [event handler](/en-US/docs/Web/Events/Event_handlers) representing the code to be called when the {{domxref("HTMLElement/gotpointercapture_event", "gotpointercapture")}} event type is raised.
-- {{domxref("GlobalEventHandlers.oninvalid")}}
-  - : An [event handler](/en-US/docs/Web/Events/Event_handlers) representing the code to be called when the {{domxref("HTMLInputElement/invalid_event", "invalid")}} event is raised.
 - {{domxref("GlobalEventHandlers.onload")}}
   - : An [event handler](/en-US/docs/Web/Events/Event_handlers) representing the code to be called when the {{domxref("Window/load_event", "load")}} event is raised.
 - {{domxref("GlobalEventHandlers.onloadeddata")}}
diff --git a/files/en-us/web/api/globaleventhandlers/oninvalid/index.md b/files/en-us/web/api/globaleventhandlers/oninvalid/index.md
deleted file mode 100644
index c75361696d421f5..000000000000000
--- a/files/en-us/web/api/globaleventhandlers/oninvalid/index.md
+++ /dev/null
@@ -1,95 +0,0 @@
----
-title: GlobalEventHandlers.oninvalid
-slug: Web/API/GlobalEventHandlers/oninvalid
-page-type: web-api-instance-property
-tags:
-  - API
-  - Event Handler
-  - GlobalEventHandlers
-  - Property
-  - Reference
-browser-compat: api.GlobalEventHandlers.oninvalid
----
-{{ ApiRef("HTML DOM") }}
-
-The **`oninvalid`** property of the
-{{domxref("GlobalEventHandlers")}} mixin is an [event handler](/en-US/docs/Web/Events/Event_handlers) that
-processes {{domxref("HTMLInputElement/invalid_event", "invalid")}} events.
-
-The `invalid` event fires when a submittable element has been checked and
-doesn't satisfy its constraints. The validity of submittable elements is checked before
-submitting their owner form, or after the
-[`checkValidity()`](/en-US/docs/Learn/Forms/Form_validation)
-method of the element or its owner form is called.
-
-## Syntax
-
-```js
-target.oninvalid = functionRef;
-var functionRef = target.oninvalid;
-```
-
-### Value
-
-`functionRef` is a function name or a [function expression](/en-US/docs/Web/JavaScript/Reference/Operators/function). The function receives a {{domxref("Event")}} object as its sole
-argument.
-
-## Example
-
-This example demonstrates `oninvalid` and
-{{domxref("HTMLFormElement.onsubmit", "onsubmit")}} event handlers on a form.
-
-### HTML
-
-```html
-
            
-  
-
-  
-  
-
-  
-
            
-
-```
-
-### JavaScript
-
-```js
-const form = document.getElementById('form');
-const error = document.getElementById('error');
-const city = document.getElementById('city');
-const thanks = document.getElementById('thanks');
-
-city.oninvalid = invalid;
-form.onsubmit = submit;
-
-function invalid(event) {
-  error.removeAttribute('hidden');
-}
-
-function submit(event) {
-  form.setAttribute('hidden', '');
-  thanks.removeAttribute('hidden');
-
-  // For this example, don't actually submit the form
-  event.preventDefault();
-}
-```
-
-### Result
-
-{{EmbedLiveSample("Example")}}
-
-## Specifications
-
-{{Specifications}}
-
-## Browser compatibility
-
-{{Compat}}
-
-## See also
-
-- {{domxref("HTMLInputElement/invalid_event", "invalid")}} event
-- [DOM on-event handlers](/en-US/docs/Web/Events/Event_handlers)
diff --git a/files/en-us/web/api/htmlinputelement/invalid_event/index.md b/files/en-us/web/api/htmlinputelement/invalid_event/index.md
index e0229528f0fbff3..71238a1e71e735a 100644
--- a/files/en-us/web/api/htmlinputelement/invalid_event/index.md
+++ b/files/en-us/web/api/htmlinputelement/invalid_event/index.md
@@ -16,31 +16,24 @@ browser-compat: api.HTMLInputElement.invalid_event
 
 The **`invalid`** event fires when a submittable element has been checked for validity and doesn't satisfy its constraints.
 
-
-  
-    
-      
-      
-    
-    
-      
-      
-    
-    
-      
-      
-    
-    
-      
-      
-    
-  
-
            BubblesNo
            CancelableYes
            Interface{{DOMxRef("Event")}}
            Event handler property{{domxref("GlobalEventHandlers.oninvalid")}}
            
-
 This event can be useful for displaying a summary of the problems with a form on submission. When a form is submitted, `invalid` events are fired at each form control that is invalid. The validity of submittable elements is checked before submitting their owner {{HtmlElement("form")}}, or after the [`checkValidity()`](/en-US/docs/Learn/Forms#constraint_validation_api) method of the element or its owner `
            ` is called.
 
 It is not checked on {{domxref("Element/blur_event", "blur")}}.
 
+## Syntax
+
+Use the event name in methods like {{domxref("EventTarget.addEventListener", "addEventListener()")}}, or set an event handler property.
+
+```js
+addEventListener('invalid', (event) => {});
+
+oninvalid = (event) => { };
+```
+
+## Event type
+
+A generic {{domxref("Event")}}.
+
 ## Examples
 
 If a form is submitted with an invalid value, the submittable elements are checked and, if an error is found, the `invalid` event will fire on the `invalid` element. In this example, when an invalid event fires because of an invalid value in the input, the invalid value is logged.

From b5503b2b62eede4d35267b94fda07a53bec082f8 Mon Sep 17 00:00:00 2001
From: "Queen Vinyl Da.i'gyu-Kazotetsu" 
Date: Mon, 18 Jul 2022 08:18:31 -0700
Subject: [PATCH 39/70] Demix slotchange from GlobalEventHandlers (#18225)

---
 files/en-us/_redirects.txt                    |  1 +
 .../mozilla/firefox/releases/93/index.md      |  2 +-
 .../web/api/globaleventhandlers/index.md      |  4 +-
 .../globaleventhandlers/onslotchange/index.md | 62 -------------------
 .../web/api/shadowroot/onslotchange/index.md  |  2 +-
 5 files changed, 4 insertions(+), 67 deletions(-)
 delete mode 100644 files/en-us/web/api/globaleventhandlers/onslotchange/index.md

diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt
index 4c39f63889ca563..8fabfe6679a72dc 100644
--- a/files/en-us/_redirects.txt
+++ b/files/en-us/_redirects.txt
@@ -8194,6 +8194,7 @@
 /en-US/docs/Web/API/GlobalEventHandlers/onselect	/en-US/docs/Web/API/HTMLInputElement/select_event
 /en-US/docs/Web/API/GlobalEventHandlers/onselectionchange	/en-US/docs/Web/API/HTMLInputElement/selectionchange_event
 /en-US/docs/Web/API/GlobalEventHandlers/onselectstart	/en-US/docs/Web/API/Document/selectstart_event
+/en-US/docs/Web/API/GlobalEventHandlers/onslotchange	/en-US/docs/Web/API/HTMLSlotElement/slotchange_event
 /en-US/docs/Web/API/GlobalEventHandlers/onsubmit	/en-US/docs/Web/API/HTMLFormElement/submit_event
 /en-US/docs/Web/API/GlobalEventHandlers/ontouchcancel	/en-US/docs/Web/API/Element/touchcancel_event
 /en-US/docs/Web/API/GlobalEventHandlers/ontouchend	/en-US/docs/Web/API/Element/touchend_event
diff --git a/files/en-us/mozilla/firefox/releases/93/index.md b/files/en-us/mozilla/firefox/releases/93/index.md
index 4bf92431a5272a0..8609707b0d4ade8 100644
--- a/files/en-us/mozilla/firefox/releases/93/index.md
+++ b/files/en-us/mozilla/firefox/releases/93/index.md
@@ -45,7 +45,7 @@ This article provides information about the changes in Firefox 93 that will affe
 
 - The {{domxref("Element.securitypolicyviolation_event","onsecuritypolicyviolation")}} global event handler property is now supported.
   This can be used to assign a handler for processing [`securitypolicyviolation`](/en-US/docs/Web/API/Element/securitypolicyviolation_event) events fired when there is a [Content Security Policy](/en-US/docs/Web/HTTP/CSP) violation ({{bug(1727302)}}).
-- The `onslotchange` event handler property is now supported on {{domxref("GlobalEventHandlers.onslotchange","GlobalEventHandlers")}} and {{domxref("ShadowRoot.onslotchange","ShadowRoot")}}.
+- The `onslotchange` event handler property is now supported on {{domxref("HTMLSlotElement.onslotchange","HTMLSlotElement")}} and {{domxref("ShadowRoot.onslotchange","ShadowRoot")}}.
   This can be used to assign a handler for processing [`slotchange`](/en-US/docs/Web/API/HTMLSlotElement/slotchange_event) events, which are fired on {{HTMLElement("slot")}} elements when the node(s) contained in the slot change ({{bug(1501983)}}).
 
 #### Removals
diff --git a/files/en-us/web/api/globaleventhandlers/index.md b/files/en-us/web/api/globaleventhandlers/index.md
index b44491169c3b241..2f020de2c6fa896 100644
--- a/files/en-us/web/api/globaleventhandlers/index.md
+++ b/files/en-us/web/api/globaleventhandlers/index.md
@@ -62,9 +62,7 @@ These event handlers are defined on the {{domxref("GlobalEventHandlers")}} mixin
 - {{domxref("GlobalEventHandlers.onseeking")}}
   - : An [event handler](/en-US/docs/Web/Events/Event_handlers) representing the code to be called when the {{event("seeking")}} event is raised.
 - {{domxref("GlobalEventHandlers.onshow")}} {{Deprecated_Inline}}
-  - : An [event handler](/en-US/docs/Web/Events/Event_handlers) representing the code to be called when the {{domxref("Element/show_event", "show")}} event is raised.
-- {{domxref("GlobalEventHandlers.onslotchange")}}
-  - : An [event handler](/en-US/docs/Web/Events/Event_handlers) representing the code to be called when the {{domxref("HTMLSlotElement/slotchange_event", "slotchange")}} event is raised.
+  - : An [event handler](/en-US/docs/Web/Events/Event_handlers) representing the code to be called when the {{event("show")}} event is raised.
 - {{domxref("GlobalEventHandlers.onstalled")}}
   - : An [event handler](/en-US/docs/Web/Events/Event_handlers) representing the code to be called when the {{domxref("HTMLMediaElement/stalled_event", "stalled")}} event is raised.
 - {{domxref("GlobalEventHandlers.onsuspend")}}
diff --git a/files/en-us/web/api/globaleventhandlers/onslotchange/index.md b/files/en-us/web/api/globaleventhandlers/onslotchange/index.md
deleted file mode 100644
index 25e5bc56d9490dc..000000000000000
--- a/files/en-us/web/api/globaleventhandlers/onslotchange/index.md
+++ /dev/null
@@ -1,62 +0,0 @@
----
-title: GlobalEventHandlers.onslotchange
-slug: Web/API/GlobalEventHandlers/onslotchange
-page-type: web-api-instance-property
-tags:
-  - API
-  - Event Handler
-  - Experimental
-  - GlobalEventHandlers
-  - Property
-  - Reference
-  - Shadow DOM API
-  - slot
-  - slotchange
-  - onslotchange
-browser-compat: api.GlobalEventHandlers.onslotchange
----
-{{ApiRef('DOM')}}{{SeeCompatTable}}
-
-The **`onslotchange`** property of the {{domxref("GlobalEventHandlers")}} mixin is an [event handler](/en-US/docs/Web/Events/Event_handlers) that processes {{domxref("HTMLSlotElement/slotchange_event", "slotchange")}} events.
-
-The `slotchange` event is fired on {{DOMxRef("HTMLSlotElement")}} instances ({{HTMLElement("slot")}} elements) when the node(s) contained in the slot change.
-
-## Examples
-
-The following snippet is a slightly modified version of our [slotchange example](https://github.com/mdn/web-components-examples/tree/main/slotchange) which uses `onslotchange` rather than adding a listener for the `slotchange` event.
-
-First the code gets an array of all the ``s and then assigns a handler function to the `onslotchange` property on the template's second slot — this second slot is the one that has its contents changed in the example.
-Every time the element in the slot changes, we log a report to the console saying which slot has changed, and what the new node inside the slot is.
-
-```js
-let slots = this.shadowRoot.querySelectorAll('slot');
-slots[1].onslotchange = function(e) {
-  let nodes = slots[1].assignedNodes();
-  console.log('Element in Slot "' + slots[1].name + '" changed to "' + nodes[0].outerHTML + '".');
-};
-```
-
-We might alternatively handle the event at a higher level.
-The snippet below shows the equivalent code if the handler is assigned to `onslotchange` on the `shadowRoot`.
-Every time the element in any slot changes, we log a report to the console saying which slot has changed, and what the new node inside the slot is.
-
-```js
-this.shadowRoot.onslotchange = function(e) {
-  const nodes = e.originalTarget.assignedNodes();
-  console.log(`Element in Slot "${e.originalTarget.name}" changed to "${nodes[0].outerHTML}".`);
-};
-```
-
-## Specifications
-
-{{Specifications}}
-
-## Browser compatibility
-
-{{Compat}}
-
-## See also
-
-- [Using templates and slots](/en-US/docs/Web/Web_Components/Using_templates_and_slots)
-- {{domxref("HTMLSlotElement/slotchange_event", "slotchange")}} event
-- {{domxref("HTMLSlotElement")}}
diff --git a/files/en-us/web/api/shadowroot/onslotchange/index.md b/files/en-us/web/api/shadowroot/onslotchange/index.md
index 1faaf569bd1cbb1..e4d969b228f67e3 100644
--- a/files/en-us/web/api/shadowroot/onslotchange/index.md
+++ b/files/en-us/web/api/shadowroot/onslotchange/index.md
@@ -47,4 +47,4 @@ this.shadowRoot.onslotchange = function(e) {
 - [Using templates and slots](/en-US/docs/Web/Web_Components/Using_templates_and_slots)
 - {{domxref("HTMLSlotElement/slotchange_event", "slotchange")}} event
 - {{domxref("HTMLSlotElement")}}
-- {{domxref("GlobalEventHandlers.onslotchange")}}
+- {{domxref("HTMLSlotElement.onslotchange")}}

From f453fe94963d1865eed3cebef90663013ebba9cb Mon Sep 17 00:00:00 2001
From: Nick Schonning 
Date: Mon, 18 Jul 2022 13:58:42 -0400
Subject: [PATCH 40/70] fix: various typos (#18483)

---
 .../silly_story_generator/index.md            |  2 +-
 .../learn/javascript/objects/basics/index.md  |  2 +-
 .../information_for_web_authors/index.md      |  2 +-
 .../readablestreambyobreader/read/index.md    |  2 +-
 .../using_readable_byte_streams/index.md      | 36 +++++++++----------
 .../structured_clone_algorithm/index.md       |  2 +-
 6 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/files/en-us/learn/javascript/first_steps/silly_story_generator/index.md b/files/en-us/learn/javascript/first_steps/silly_story_generator/index.md
index 9da9e0b5522cc78..82bf8291a624639 100644
--- a/files/en-us/learn/javascript/first_steps/silly_story_generator/index.md
+++ b/files/en-us/learn/javascript/first_steps/silly_story_generator/index.md
@@ -55,7 +55,7 @@ You have been provided with some raw HTML/CSS and a few text strings and JavaScr
 - Generates a silly story when the "Generate random story" button is pressed.
 - Replaces the default name "Bob" in the story with a custom name, only if a custom name is entered into the "Enter custom name" text field before the generate button is pressed.
 - Converts the default US weight and temperature quantities and units in the story into UK equivalents if the UK radio button is checked before the generate button is pressed.
-- Generates a new random silly story everytime the button is pressed.
+- Generates a new random silly story every time the button is pressed.
 
 The following screenshot shows an example of what the finished program should output:
 
diff --git a/files/en-us/learn/javascript/objects/basics/index.md b/files/en-us/learn/javascript/objects/basics/index.md
index 8cd7620c89485b0..ab40b69b67af562 100644
--- a/files/en-us/learn/javascript/objects/basics/index.md
+++ b/files/en-us/learn/javascript/objects/basics/index.md
@@ -177,7 +177,7 @@ person['name']['first']
 This looks very similar to how you access the items in an array, and it is basically the same thing — instead of using an index number to select an item, you are using the name associated with each member's value.
 It is no wonder that objects are sometimes called **associative arrays** — they map strings to values in the same way that arrays map numbers to values.
 
-Dot notation is generally preferred over bracket notation because it is more succint and easier to read.
+Dot notation is generally preferred over bracket notation because it is more succinct and easier to read.
 However there are some cases where you have to use brackets.
 For example, if an object property name is defined at runtime then you can't use dot notation to access the value, but you can pass the name as a variable inside brackets as shown with `input` below:
 
diff --git a/files/en-us/web/accessibility/information_for_web_authors/index.md b/files/en-us/web/accessibility/information_for_web_authors/index.md
index a8961ae5493a26b..9d7056cc37b0438 100644
--- a/files/en-us/web/accessibility/information_for_web_authors/index.md
+++ b/files/en-us/web/accessibility/information_for_web_authors/index.md
@@ -21,7 +21,7 @@ tags:
 
 ## How-to's
 
-1. [Accessiblity for frontend developers](https://accessibility.digital.gov/front-end/getting-started/)
+1. [Accessibility for frontend developers](https://accessibility.digital.gov/front-end/getting-started/)
 
     A brief guide from the U.S. General Services administration’s Technology Transformation Services covering several accessibility topics with links to "how-to" videos and to related WCAG references.
 
diff --git a/files/en-us/web/api/readablestreambyobreader/read/index.md b/files/en-us/web/api/readablestreambyobreader/read/index.md
index a91d5e44f80fbd6..6694ff24501605e 100644
--- a/files/en-us/web/api/readablestreambyobreader/read/index.md
+++ b/files/en-us/web/api/readablestreambyobreader/read/index.md
@@ -14,7 +14,7 @@ browser-compat: api.ReadableStreamBYOBReader.read
 {{APIRef("Streams")}}
 
 The **`read()`** method of the {{domxref("ReadableStreamBYOBReader")}} interface is used to read data into a view on a user-supplied buffer from an associated [readable byte stream](/en-US/docs/Web/API/Streams_API/Using_readable_byte_streams).
-A request for data will be statisfied from the stream's internal queues if there is any data present.
+A request for data will be satisfied from the stream's internal queues if there is any data present.
 If the stream queues are empty, the request may be supplied as a zero-copy transfer from the underlying byte source.
 
 The method takes as an argument a view on a buffer that supplied data is to be read into, and returns a {{jsxref("Promise")}}.
diff --git a/files/en-us/web/api/streams_api/using_readable_byte_streams/index.md b/files/en-us/web/api/streams_api/using_readable_byte_streams/index.md
index 0698ef6b59b7876..1be9334360946bd 100644
--- a/files/en-us/web/api/streams_api/using_readable_byte_streams/index.md
+++ b/files/en-us/web/api/streams_api/using_readable_byte_streams/index.md
@@ -24,7 +24,7 @@ This article explains how readable byte streams compare to normal "default" stre
 
 > **Note:** Readable byte streams are almost identical to "normal" readable streams and almost all of the concepts are the same.
 > This article assumes that you already understand those concepts and will only be covering them superficially (if at all).
-> If you're not familiar with the relevent concepts, please first read: [Using readable streams](/en-US/docs/Web/API/Streams_API/Using_readable_streams), [Streams concepts and usage overview](/en-US/docs/Web/API/Streams_API#concepts_and_usage), and [Streams API concepts](/en-US/docs/Web/API/Streams_API/Concepts).
+> If you're not familiar with the relevant concepts, please first read: [Using readable streams](/en-US/docs/Web/API/Streams_API/Using_readable_streams), [Streams concepts and usage overview](/en-US/docs/Web/API/Streams_API#concepts_and_usage), and [Streams API concepts](/en-US/docs/Web/API/Streams_API/Concepts).
 
 ## Overview
 
@@ -70,17 +70,17 @@ This live example shows how to create a readable byte stream with a _push_ under
 
 Unlike with a pull underlying byte source, data can arrive at any time.
 Therefore the underlying source must use `controller.byobRequest` to transfer incoming data if one exists, and otherwise enqueue the data into the stream's internal queues.
-Further, since the data can arrive at any time the monitoring behaviour is set up in the `underlyingSource.start()` callback function.
+Further, since the data can arrive at any time the monitoring behavior is set up in the `underlyingSource.start()` callback function.
 
 The example is highly influenced by a push byte source example in the stream specification.
 It uses a mocked "hypothetical socket" source that supplies data of arbitrary sizes.
-The reader is deliberately delayed at various points to allow the underlying source to use both transfer and enqueing to send data to the stream.
+The reader is deliberately delayed at various points to allow the underlying source to use both transfer and enqueuing to send data to the stream.
 Backpressure support is not demonstrated.
 
 > **Note:** An underlying byte source can also be used with a default reader.
 > If automatic buffer allocation is enabled the controller will supply fixed-size buffers for zero-copy transfers when there is an outstanding request from a reader and the stream's internal queues are empty.
 > If automatic buffer allocation is not enabled then all data from the byte stream will always be enqueued.
-> This is similar to the behaviour shown in the "pull: underlying byte source examples.
+> This is similar to the behavior shown in the "pull: underlying byte source examples.
 
 #### Mocked underlying socket source
 
@@ -153,13 +153,13 @@ class MockHypotheticalSocket {
   getNumberRandomBytesSocket() {
     //Capped to remaining data and the max min return-per-read range
     const remaining_data = this.max_data - this.data_read;
-    let numberBytesRecieved = 0;
+    let numberBytesReceived = 0;
     if (remaining_data < this.min_per_read) {
-      numberBytesRecieved = remaining_data;
+      numberBytesReceived = remaining_data;
     } else {
-      numberBytesRecieved = this.getRandomIntInclusive(this.min_per_read, Math.min(this.max_per_read, remaining_data));
+      numberBytesReceived = this.getRandomIntInclusive(this.min_per_read, Math.min(this.max_per_read, remaining_data));
     }
-    return numberBytesRecieved;
+    return numberBytesReceived;
   }
 
   /* Return random number between two values */
@@ -253,9 +253,9 @@ This ensures that the stream is handed a {{domxref("ReadableByteStreamController
 
 Since data can arrive at the socket before the consumer is ready to handle it, everything about reading the underlying source is configured in the `start()` callback method (we don't wait on a pull to start handling data).
 The implementation opens the "socket" and calls `select2()` to request data.
-When the retured promise resolves the code checks if `controller.byobRequest` exists (is not `null`), and if so calls `socket.readInto()` to copy data into the request and transfer it.
-If `byobRequest` does not exist there is no outstanding request from a consuming stream that can be satisifed as as zero-copy transfer.
-In this case, `constroller.enqueue()` used to copy data to the stream internal queues.
+When the returned promise resolves the code checks if `controller.byobRequest` exists (is not `null`), and if so calls `socket.readInto()` to copy data into the request and transfer it.
+If `byobRequest` does not exist there is no outstanding request from a consuming stream that can be satisfied as as zero-copy transfer.
+In this case, `controller.enqueue()` used to copy data to the stream internal queues.
 
 The `select2()` request for more data is reposted until a request is returned with no data.
 A this point the controller is used to close the stream.
@@ -400,7 +400,7 @@ reader.closed
 #### Result
 
 The logging from the underlying push source (left) and consumer (right) are shown below.
-Not the period in the middle where data is equeued rather than transferred as a zero-copy operation.
+Not the period in the middle where data is enqueued rather than transferred as a zero-copy operation.
 
 {{EmbedLiveSample("Underlying push source with default reader","100%","500px")}}
 
@@ -564,9 +564,9 @@ function makeReadableByteFileStream(filename) {
     },
     async pull(controller) {
       // Called when there is a pull request for data
-      const theview = controller.byobRequest.view;
+      const theView = controller.byobRequest.view;
       const {bytesRead, buffer} = 
-        await fileHandle.read(theview.buffer, theview.offset, theview.length, position)
+        await fileHandle.read(theView.buffer, theView.offset, theView.length, position)
       if (bytesRead === 0) {
         await fileHandle.close();
         controller.close();
@@ -787,9 +787,9 @@ function makeReadableByteFileStream(filename) {
     },
     async pull(controller) {
       // Called when there is a pull request for data
-      const theview = controller.byobRequest.view;
+      const theView = controller.byobRequest.view;
       const {bytesRead, buffer} = 
-        await fileHandle.read(theview.buffer, theview.offset, theview.length, position)
+        await fileHandle.read(theView.buffer, theView.offset, theView.length, position)
       if (bytesRead === 0) {
         await fileHandle.close();
         controller.close();
@@ -1002,8 +1002,8 @@ function makeReadableByteFileStream(filename) {
     async pull(controller) {
       // Called when there is a pull request for data
       if (controller.byobRequest) {
-         const theview = controller.byobRequest.view;
-         const {bytesRead, buffer} = await fileHandle.read(theview.buffer, theview.offset, theview.length, position)
+         const theView = controller.byobRequest.view;
+         const {bytesRead, buffer} = await fileHandle.read(theView.buffer, theView.offset, theView.length, position)
          if (bytesRead === 0) {
            await fileHandle.close();
            controller.close();
diff --git a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md
index 6ada80d16b7d543..ac6192f8d675f3f 100644
--- a/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md
+++ b/files/en-us/web/api/web_workers_api/structured_clone_algorithm/index.md
@@ -116,7 +116,7 @@ It clones by recursing through the input object while maintaining a map of previ
       
            Native Error types
       
         
            The error name must be one of: {{jsxref("Error")}}, {{JSxRef("EvalError")}}, {{JSxRef("RangeError")}}, {{JSxRef("ReferenceError")}}, {{JSxRef("SyntaxError")}}, {{JSxRef("TypeError")}}, {{JSxRef("URIError")}} (or will be set to "Error").
            
-        
            Browsers must serialize the properties name and message, and are expected to serialise "interesting" other properties of the errors such as stack, cause, etc.
            
+        
            Browsers must serialize the properties name and message, and are expected to serialize "interesting" other properties of the errors such as stack, cause, etc.
            
         
            {{JSxRef("AggregateError")}} support is expected to be added to the specification in whatwg/html#5749 (and is already supported in some browsers).