Overhaul code example guidelines

REVIEWING.md

@@ -208,6 +208,6 @@ for all their help.
 - [@vkWeb](https://github.com/vkWeb/)
 
 [get in touch with us]: https://developer.mozilla.org/en-US/docs/MDN/Community/Contributing/Getting_started#what_can_i_do_to_help
-[mdn code example guidelines]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
+[mdn code example guidelines]: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples
 [mdn writing style guide]: https://developer.mozilla.org/en-US/docs/MDN/Guidelines/Writing_style_guide
 [MDN Web Docs chat rooms]: https://developer.mozilla.org/en-US/docs/MDN/Community/Communication_channels

files/en-us/_redirects.txt

@@ -5413,7 +5413,7 @@
 /en-US/docs/MDN/Community/Issues/Issue_triage	/en-US/docs/MDN/Community/Issues
 /en-US/docs/MDN/Community/Users_teams	/en-US/docs/MDN/Community/Roles_teams
 /en-US/docs/MDN/Contribute/Changelog	/en-US/docs/MDN/Changelog
-/en-US/docs/MDN/Contribute/Code_sample_guidelines	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
+/en-US/docs/MDN/Contribute/Code_sample_guidelines	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples
 /en-US/docs/MDN/Contribute/Content	/en-US/docs/MDN/Writing_guidelines
 /en-US/docs/MDN/Contribute/Content/Content_blocks	/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN
 /en-US/docs/MDN/Contribute/Content/Custom_macros	/en-US/docs/MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros
@@ -5437,13 +5437,13 @@
 /en-US/docs/MDN/Contribute/Guidelines	/en-US/docs/MDN/Writing_guidelines
 /en-US/docs/MDN/Contribute/Guidelines/Best_practices	/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete
 /en-US/docs/MDN/Contribute/Guidelines/CSS_style_guide	/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN
-/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
-/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS
-/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
-/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML
-/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript
-/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell
-/en-US/docs/MDN/Contribute/Guidelines/Code_samples	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
+/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples
+/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS
+/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/General	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples
+/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/HTML	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML
+/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/JavaScript	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript
+/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/Shell	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell
+/en-US/docs/MDN/Contribute/Guidelines/Code_samples	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples
 /en-US/docs/MDN/Contribute/Guidelines/Content	/en-US/docs/MDN/Writing_guidelines/What_we_write
 /en-US/docs/MDN/Contribute/Guidelines/Content_blocks	/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN
 /en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions	/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete
@@ -5489,7 +5489,7 @@
 /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_version	https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md
 /en-US/docs/MDN/Contribute/Processes/Matching_features_to_browser_versiosn	https://github.com/mdn/browser-compat-data/blob/main/docs/matching-browser-releases/index.md
 /en-US/docs/MDN/Contribute/Processes/Short_surveys	/en-US/docs/MDN/Contribute
-/en-US/docs/MDN/Contribute/Sample_app_coding_guidelines	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
+/en-US/docs/MDN/Contribute/Sample_app_coding_guidelines	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples
 /en-US/docs/MDN/Contribute/Sample_server	/en-US/docs/MDN
 /en-US/docs/MDN/Contribute/Structures	/en-US/docs/MDN/Writing_guidelines/Page_structures
 /en-US/docs/MDN/Contribute/Structures/:-ms-input-placeholder_pseudo-class	/en-US/docs/Web/CSS/:placeholder-shown
@@ -5541,12 +5541,12 @@
 /en-US/docs/MDN/Getting_started	/en-US/docs/MDN/Community/Contributing/Getting_started
 /en-US/docs/MDN/Guidelines	/en-US/docs/MDN/Writing_guidelines
 /en-US/docs/MDN/Guidelines/CSS_style_guide	/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN
-/en-US/docs/MDN/Guidelines/Code_guidelines	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
-/en-US/docs/MDN/Guidelines/Code_guidelines/CSS	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS
-/en-US/docs/MDN/Guidelines/Code_guidelines/General	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide
-/en-US/docs/MDN/Guidelines/Code_guidelines/HTML	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML
-/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript
-/en-US/docs/MDN/Guidelines/Code_guidelines/Shell	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell
+/en-US/docs/MDN/Guidelines/Code_guidelines	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples
+/en-US/docs/MDN/Guidelines/Code_guidelines/CSS	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS
+/en-US/docs/MDN/Guidelines/Code_guidelines/General	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples
+/en-US/docs/MDN/Guidelines/Code_guidelines/HTML	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML
+/en-US/docs/MDN/Guidelines/Code_guidelines/JavaScript	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript
+/en-US/docs/MDN/Guidelines/Code_guidelines/Shell	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell
 /en-US/docs/MDN/Guidelines/Content	/en-US/docs/MDN/Writing_guidelines/What_we_write
 /en-US/docs/MDN/Guidelines/Conventions_definitions	/en-US/docs/MDN/Writing_guidelines/Experimental_deprecated_obsolete
 /en-US/docs/MDN/Guidelines/Does_this_belong_on_MDN	/en-US/docs/MDN/Writing_guidelines/What_we_write
@@ -5609,6 +5609,11 @@
 /en-US/docs/MDN/Writing_guidelines/Howto/Tag	/en-US/docs/MDN/Writing_guidelines/Howto
 /en-US/docs/MDN/Writing_guidelines/Research_technology	/en-US/docs/MDN/Writing_guidelines/Howto/Research_technology
 /en-US/docs/MDN/Writing_guidelines/What_we_write/Inclusion_criteria	/en-US/docs/MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion
+/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples
+/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS
+/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML
+/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/JavaScript
+/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/Shell	/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/Shell
 /en-US/docs/MDN/Yari	https://github.com/mdn/yari/tree/main/docs
 /en-US/docs/MDN_at_ten	/en-US/docs/MDN/At_ten
 /en-US/docs/MDN_at_ten/Contributing_to_MDN	/en-US/docs/MDN/Contribute

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

@@ -10,7 +10,7 @@ The term HTML5 is essentially a buzzword that refers to a set of modern web tech
 
 You may sometimes hear about "new HTML5 elements", or find HTML5 described as a new version of HTML. HTML5 was the successor to previous HTML versions and introduced new elements and capabilities to the language on top of the previous version, HTML 4.01, as well as improving or removing some existing functionality. However, as a Living Standard HTML now has no version. The up-to-date specification can be found at [html.spec.whatwg.org/](https://html.spec.whatwg.org/).
 
-Any modern site should use the [HTML doctype](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML#doctype) — this will ensure that you are using the latest version of HTML.
+Any modern site should use the [HTML doctype](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML#doctype) — this will ensure that you are using the latest version of HTML.
 
 > **Note:** Until 2019, the {{glossary("W3C")}} published a competing HTML5 standard with version numbers. Since [28 May 2019](https://www.w3.org/blog/news/archives/7753), the WHATWG Living Standard was announced by the W3C as the sole version of HTML.
 

files/en-us/learn/css/building_blocks/organizing/index.md

@@ -47,7 +47,7 @@ Here are some general suggestions for ways to keep your stylesheets organized an
 
 If you are working with a team on an existing project, the first thing to check is whether the project has an existing style guide for CSS. The team style guide should always win over your own personal preferences. There often isn't a right or wrong way to do things, but consistency is important.
 
-For example, have a look at the [CSS guidelines for MDN code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS).
+For example, have a look at the [CSS guidelines for MDN code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS).
 
 ### Keep it consistent
 

files/en-us/mdn/community/pull_requests/index.md

@@ -117,7 +117,7 @@ Do leave the door open to the author to ask for help, especially new contributor
 
 ### Reviewing a pull request
 
-When it comes to the changes in a pull request, content and prose must adhere to the [MDN Writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) and example code must follow the [code style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide).
+When it comes to the changes in a pull request, content and prose must adhere to the [MDN Writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide) and example code must follow the [code examples guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples).
 
 When you are reviewing a pull request, you should:
 

files/en-us/mdn/writing_guidelines/index.md

@@ -18,7 +18,7 @@ MDN Web Docs is an open-source project. The sections outlined below describe our
 
 - [Our writing style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide)
 
-  - : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide).
+  - : The writing style guide covers the language and style we use to write on MDN Web Docs. It also covers how to [format code examples](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples).
 
 - [How to write for MDN Web Docs](/en-US/docs/MDN/Writing_guidelines/Howto)
 

files/en-us/mdn/writing_guidelines/page_structures/code_examples/index.md

@@ -8,7 +8,7 @@ page-type: mdn-writing-guide
 
 On MDN, you'll see numerous code examples inserted throughout the pages to demonstrate usage of web platform features. This article discusses the different mechanisms available for adding code examples to pages, along with which ones you should use and when.
 
-> **Note:** If you want advice on the styling and linting of code as it appears on an MDN article, rather than the different ways of including code, see our [Code style guide](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide).
+> **Note:** If you want advice on the styling and linting of code as it appears on an MDN article, rather than the different ways of including code, see our [Code examples guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples).
 
 ## What types of code example are available?
 
@@ -213,4 +213,4 @@ This looks like so when rendered:
 ### Tips for using GitHub live samples
 
 - You obviously need to get a suitable code sample onto the [MDN GitHub organization](https://github.com/mdn/) first. This needs to be done using Git. If you are not familiar with Git, check out our [How do I use GitHub Pages?](/en-US/docs/Learn/Common_questions/Tools_and_setup/Using_GitHub_pages) article, and [Preparing to add the data](/en-US/docs/MDN/Writing_guidelines/Page_structures/Compatibility_tables) for more advanced uses.
-- Your code sample needs to be suitable to show what you are trying to demonstrate — it should contain one simple example that does one thing well, should have no offensive content in it, and should follow the MDN [Code sample guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide).
+- Your code sample needs to be suitable to show what you are trying to demonstrate — it should contain one simple example that does one thing well, should have no offensive content in it, and should follow the MDN [Code examples guidelines](/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_examples).

files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/css/index.md → files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/css/index.md

@@ -1,6 +1,6 @@
 ---
-title: Guidelines for styling CSS code examples
-slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/CSS
+title: Guidelines for writing CSS code examples
+slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/CSS
 page-type: mdn-writing-guide
 ---
 
@@ -10,6 +10,14 @@ The following guidelines cover how to write CSS example code for MDN Web Docs.
 
 ## General guidelines for CSS code examples
 
+### Choosing a format
+
+Opinions on correct indentation, whitespace, and line lengths have always been controversial. Discussions on these topics are a distraction from creating and maintaining content.
+
+On MDN Web Docs, we use [Prettier](https://prettier.io/) as a code formatter to keep the code style consistent (and to avoid off-topic discussions). You can consult our [configuration file](https://github.com/mdn/content/blob/main/.prettierrc.json) to learn about the current rules, and read the [Prettier documentation](https://prettier.io/docs/en/index.html).
+
+Prettier formats all the code and keeps the style consistent. Nevertheless, there are a few additional rules that you need to follow.
+
 ### 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.
@@ -26,7 +34,7 @@ Don't use preprocessor syntax, such as [Sass](https://sass-lang.com/), [Less](ht
 
 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 <!--is this valid in current times-->
+### 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.
 
@@ -154,61 +162,6 @@ In a stylesheet that contains [media query](/en-US/docs/Web/CSS/CSS_media_querie
   }
   ```
 
-- When a rule has multiple selectors, put each selector on a new line. This makes the selector list easier to read and can help to make code lines shorter.
-
-  Do this:
-
-  ```css example-good
-  h1,
-  h2,
-  h3 {
-    font-family: sans-serif;
-    text-align: center;
-  }
-  ```
-
-  Not this: <!--I thought this is the preferred style-->
-
-  ```css-nolint example-bad
-  h1, h2, h3 {
-    font-family: sans-serif;
-    text-align: center;
-  }
-  ```
-
-## Space after function parameters
-
-Function parameters should have spaces after their separating commas, but not before:
-
-```css example-good
-color: rgb(255, 0, 0);
-background-image: linear-gradient(to bottom, red, black);
-```
-
-## Syntax style
-
-There are a variety of CSS writing styles you can use, but we prefer the expanded style, with the selector/opening brace, close brace, and each declaration on a separate line. This maximizes readability, and again, promotes consistency on MDN Web Docs.
-
-In addition, keep these specifics in mind:
-
-- Include a space between the selector(s) and the opening curly brace.
-- Always include a semicolon at the end of the last declaration, even though it isn't strictly necessary.
-- Put the closing curly brace on a new line.
-- In each declaration, put a space after the separating colon, but not before.
-- Use two spaces for code indentation.
-
-```css example-good
-p {
-  color: white;
-  background-color: black;
-  padding: 1rem;
-}
-```
-
-```css-nolint example-bad
-p { color: white; background-color: black; padding: 1rem; }
-```
-
 ## Value to turn off properties
 
 When turning off borders (and any other properties that can take `0` or `none` as values), use `0` rather than `none`:

files/en-us/mdn/writing_guidelines/writing_style_guide/code_style_guide/html/index.md → files/en-us/mdn/writing_guidelines/writing_style_guide/code_examples/html/index.md

@@ -1,6 +1,6 @@
 ---
-title: Guidelines for styling HTML code examples
-slug: MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/HTML
+title: Guidelines for writing HTML code examples
+slug: MDN/Writing_guidelines/Writing_style_guide/Code_examples/HTML
 page-type: mdn-writing-guide
 ---
 
@@ -81,13 +81,13 @@ Omitting quotes can also cause problems. In the above example, the `alt` attribu
 Don't write out boolean attributes in full; you can just write the attribute name to set it. For example, you can write:
 
 ```html example-good
-required
+<input required></input>
 ```
 
 This is perfectly understandable and works fine; the longer version with the value is supported but not necessary:
 
-```html-nolint example-bad
-required="required"
+```html example-bad
+<input required="required"></input>
 ```
 
 ## Case
@@ -114,18 +114,6 @@ Use semantic class/ID names, and separate multiple words with hyphens. Don't use
 <p class="bigRedBox">Blah blah blah</p>
 ```
 
-## Double quotes
-
-Use double quotes for HTML, not single quotes, like so:
-
-```html example-good
-<p class="important">Yes</p>
-```
-
-```html-nolint example-bad
-<p class='important'>Nope</p>
-```
-
 ## Entity references
 
 Don't use entity references unnecessarily — use the literal character wherever possible (you'll still need to escape characters like angle brackets and quote marks).
@@ -142,8 +130,6 @@ Instead of:
 <p>&copy; 2018 Me</p>
 ```
 
-This is fine as long as you declare a UTF-8 character set.
-
 ## HTML elements
 
 There are some rules for writing about HTML elements on MDN Web Docs. Adhering to these rules produces consistent descriptions of elements and their components and also ensures correct linking to detailed documentation.