Merge branch 'main' into patch-18

.markdownlint-cli2.jsonc

@@ -81,9 +81,9 @@
     }
   },
   "customRules": [
-    "./markdownlint/TOP001_descriptiveLinkText.js",
-    "./markdownlint/TOP002_noCodeInHeadings.js",
-    "./markdownlint/TOP003_defaultSectionContent.js",
-    "./markdownlint/TOP004_lessonHeadings.js"
+    "./markdownlint/TOP001_descriptiveLinkText/TOP001_descriptiveLinkText.js",
+    "./markdownlint/TOP002_noCodeInHeadings/TOP002_noCodeInHeadings.js",
+    "./markdownlint/TOP003_defaultSectionContent/TOP003_defaultSectionContent.js",
+    "./markdownlint/TOP004_lessonHeadings/TOP004_lessonHeadings.js"
   ]
 }

LAYOUT_STYLE_GUIDE.md

@@ -76,7 +76,7 @@ The following questions are an opportunity to reflect on key topics in this less
 
 ### Additional resources
 
-This section contains helpful links to related content. It isn’t required, so consider it supplemental.
+This section contains helpful links to related content. It isn't required, so consider it supplemental.
 
 - It looks like this lesson doesn't have any additional resources yet. Help us expand this section by contributing to our curriculum.
 

advanced_html_css/accessibility/keyboard_navigation.md

@@ -4,7 +4,7 @@ Some users aren't able to use a mouse to navigate or operate their computer, and
 
 ### Lesson overview
 
-By the end of this lesson, you should be able to:
+This section contains a general overview of topics that you will learn in this lesson.
 
 - Know the two things that interactive elements must have for keyboard users.
 - Understand what focus styles are and why you shouldn't completely remove them.
@@ -15,15 +15,16 @@ By the end of this lesson, you should be able to:
 
 Remember our Rock, Paper, Scissors example that *didn't* use semantic HTML from the... well, Semantic HTML lesson? Another issue with using `<div>` and `<span>` elements is that, by default, they aren't focusable and they don't have any event handling by default. In order to fix our non-semantic Rock, Paper, Scissors example for keyboard users, we would need to take some extra steps, similar to the below code snippets:
 
-~~~html
+```html
 <!-- The `tabindex` attribute makes the `<div>` elements focusable. -->
 <div class='button-container'>
   <div class='rock button' tabindex='0'>Rock</div>
   <div class='paper button' tabindex='0'>Paper</div>
   <div class='scissors button' tabindex='0'>Scissors</div>
 </div>
-~~~
-~~~javascript
+```
+
+```javascript
 // We also need to manually add in event handling for both mouse and keyboard events.
 const buttons = document.querySelectorAll('.button');
 
@@ -37,7 +38,7 @@ buttons.forEach(button => {
   button.addEventListener('click', nameAlerter)
   button.addEventListener('keydown', nameAlerter)
 })
-~~~
+```
 
 Of course, this example then makes it *less* understandable for screen reader users (remember, these "buttons" won't provide any context). Not only does using the `<button>` element provide the context screen reader users need, but they're focusable and have event handling for keyboards *by default*: pressing the <kbd>Space</kbd> or <kbd>Enter</kbd> keys on a keyboard when a `<button>` has focus will trigger the "click" event.
 
@@ -47,13 +48,13 @@ Of course, this example then makes it *less* understandable for screen reader us
 
 Another aspect of focusable elements is their focus styles, which are usually an outline or border surrounding the element when it receives focus. One of the things you may have done, or may still do, is completely remove these focus styles by using CSS rules similar to the example below:
 
-~~~css
+```css
 /* These are so ugh-ly! Let's get rid of them. */
 *:focus {
   outline: none;
   border: none;
 }
-~~~
+```
 
 You probably assume that you're about to be told not to do this. Well... **You should never completely remove focus styles**. You should either leave these default focus styles alone, or you should replace them with your own focus styles. Whether it's adding a `transform: scale()` CSS property to a button, adding an outline to a link, or increasing the border width and opacity on an input, adding your own focus styles is the only alternative you should consider to the default focus styles.
 
@@ -63,21 +64,21 @@ You probably assume that you're about to be told not to do this. Well... **You s
 
 The tab order is the order in which elements on the page will receive focus when pressing the <kbd>Tab</kbd> key, and is by default in the same order as the order of elements listed in the HTML file:
 
-~~~html
+```html
 <!-- This element is first in the tab order. -->
 <div tabindex='0'>This is the first element listed in the HTML.</div>
 
 <!-- This element is second in the tab order. -->
 <div tabindex='0'>This is the second element listed in the HTML.</div>
-~~~
+```
 
-Sometimes you may find it necessary to either change the visual order of elements on a page using CSS (the `float` or `order` properties, for example), or the tab order of elements themselves using the `tabindex` attribute. Regardless of which method you may use, you should make sure the tab order matches the visual order of elements. If the tab order is different from the visual order, users could be left confused or frustrated trying to navigate the page with a keyboard, expecting one element to receive focus based on the visual layout and instead another element receives focus. 
+Sometimes you may find it necessary to either change the visual order of elements on a page using CSS (the `float` or `order` properties, for example), or the tab order of elements themselves using the `tabindex` attribute. Regardless of which method you may use, you should make sure the tab order matches the visual order of elements. If the tab order is different from the visual order, users could be left confused or frustrated trying to navigate the page with a keyboard, expecting one element to receive focus based on the visual layout and instead another element receives focus.
 
 The best way to avoid this issue is to just place elements in your HTML file in the order that you want them to actually receive focus.
 
 ### Hidden content
 
-Sometimes you may want to hide some content until a specific event occurs, such as a user clicking on a button to open a menu or a modal box. When you want to hide content for this sort of purpose, you need to make sure the content is not only visually hidden, but also hidden from assistive technologies until that content is meant to be visible. 
+Sometimes you may want to hide some content until a specific event occurs, such as a user clicking on a button to open a menu or a modal box. When you want to hide content for this sort of purpose, you need to make sure the content is not only visually hidden, but also hidden from assistive technologies until that content is meant to be visible.
 
 If you don't properly hide such content, then keyboard users would be able to tab into that content before they're meant to, but in doing so they would lose track of any visual focus on the page. These users would be left confused or even frustrated when they're trying to tab through a page, only for their focus indicator to disappear into that hidden content.
 
@@ -92,16 +93,17 @@ One way to prevent this frustrating behavior is to give each individual item in
 </div>
 
 ### Knowledge check
-This section contains questions for you to check your understanding of this lesson. If you’re having trouble answering the questions below on your own, review the material above to find the answer.
 
-* [What are two things that interactive elements must have for keyboard users?](#interative-elements-keyboard)
-* [What are focus styles?](#focus-styles)
-* [Why should you never completely remove focus styles from an element?](#focus-never-remove)
-* [What is the tab order?](#tab-order)
-* [What is the best way to hide hidden content from assistive technologies?](#best-way-hide-content)
+The following questions are an opportunity to reflect on key topics in this lesson. If you can't answer a question, click on it to review the material, but keep in mind you are not expected to memorize or master this knowledge.
+
+- [What are two things that interactive elements must have for keyboard users?](#interative-elements-keyboard)
+- [What are focus styles?](#focus-styles)
+- [Why should you never completely remove focus styles from an element?](#focus-never-remove)
+- [What is the tab order?](#tab-order)
+- [What is the best way to hide hidden content from assistive technologies?](#best-way-hide-content)
 
 ### Additional resources
 
-This section contains helpful links to other content. It isn’t required, so consider it supplemental.
+This section contains helpful links to related content. It isn’t required, so consider it supplemental.
 
-* [Skip Links](https://webaim.org/techniques/skipnav/) are another form of accessibility for keyboard users and can be especially helpful for those who require more effort to tab through the contents of a page.
+- [Skip Links](https://webaim.org/techniques/skipnav/) are another form of accessibility for keyboard users and can be especially helpful for those who require more effort to tab through the contents of a page.

advanced_html_css/accessibility/meaningful_text.md

@@ -4,48 +4,49 @@ Meaningful text is pretty straight forward: when a user reads text or has it ann
 
 ### Lesson overview
 
-By the end of this lesson, you should be able to:
+This section contains a general overview of topics that you will learn in this lesson.
 
 - Know how to provide meaningful links.
 - Know how to provide meaningful text in forms.
 - Know how to provide meaningful `alt` attributes for images.
 
 ### Links
+
 Let's take a look at two different examples of a link:
 
-~~~html
+```html
 <!-- Example 1: Where's "here"? -->
 <a href='...'>Click here</a> to start your career in web development!
 
 <!-- Example 2: I love that place! -->
 Visit <a href='...'>The Odin Project</a> to start your career in web development!
-~~~
+```
 
 To a sighted user, the link in Example 1 makes perfect sense. However, in addition to being able to navigate a page via landmarks and headings (as mentioned in the Semantic HTML lesson), a screen reader may be able to navigate between each element of a specific type, such as links. If a user were to navigate between all of the links on a page, the only thing that would get announced in Example 1 is, "Click here, link." Where's "here" exactly? Without any surrounding context, the link is meaningless. Not only that, but if you have multiple links on a page with that same text content, then users will be told to "click here" many times.
 
-The link in Example 2, however, not only makes sense in context for all users, but it also makes sense *out of context* for screen reader users when it gets announced: "The Odin Project, link." 
+The link in Example 2, however, not only makes sense in context for all users, but it also makes sense *out of context* for screen reader users when it gets announced: "The Odin Project, link."
 
 <span id="meaningful-links-rules">When you add links to a page, there are a few rules you should be following:</span>
 
 1. Make sure that the text content of the `<a>` element somehow indicates where the link redirects to and that it's brief (around 100 characters). So avoid using phrases like "click here" or "this page".
-2. If a link would open or download a file, include text that tells the user what kind of file it is as well as the file size.
-3. If a link would automatically open in a new tab or window with the `target="_blank"` attribute, you should indicate this to the user in some way.
+1. If a link would open or download a file, include text that tells the user what kind of file it is as well as the file size.
+1. If a link would automatically open in a new tab or window with the `target="_blank"` attribute, you should indicate this to the user in some way.
 
-~~~html
+```html
 <!-- Example 1: Now the user is aware that this link will open or download a PDF file. -->
 <a href='...'>2021 Sign Up Statistics (PDF, 1MB)</a>
 
 <!-- Example 2: And now the user knows this link opens in a new tab! -->
 <a href='...'>GitHub (opens in new tab)</a>
-~~~
+```
 
 The next time you need to use links, try saying the contents of the element out loud to yourself. Does it reasonably indicate where that link would take you, such as the title of the page, article, or video? Are you aware whether it'll open in a new tab automatically or not, or that it'll open a download dialog? If you've been testing out using a screen reader up to this point, then an even better way to test whether a link has meaningful text is with the screen reader itself!
 
 ### Forms
 
 Providing meaningful errors to users when they are filling out or submitting a form can turn the experience from frustrating to... well, maybe not fun, but at the very least just a bit less frustrating. Let's take a look at a few error examples, ranging from not helpful at all to very helpful:
 
-~~~html
+```html
 <!-- Example 1: Huh? -->
 <div class='input-error'>Error: Invalid input.</div>
 
@@ -54,7 +55,7 @@ Providing meaningful errors to users when they are filling out or submitting a f
 
 <!-- Example 3: Even better! -->
 <div class='input-error'>Error: 'JohnSmith@@test.com' is not valid. Example of a valid email: example@yourdomain.com.</div>
-~~~
+```
 
 Even if you could tell what input caused the error in Example 1, which may not always be the case, the error doesn't provide any meaningful text. What input is invalid? Why is it invalid? How can you fix it? None of these questions are answered. Now imagine how meaningless this error must be to users of assistive technologies, who may not be able to see where an error is rendered on the page and may only have "invalid input" announced to them.
 
@@ -68,28 +69,29 @@ Another way to provide meaningful text in forms is with instructions, such as wh
 
 At this point you should be pretty familiar with the `alt` attribute on `img` elements. Whether you are or not, let's see if you can tell which of the following examples is valid:
 
-~~~html
+```html
 <!-- Example 1 -->
 <img src='...' alt='' />
 
 <!-- Example 2 -->
 <img src='...' alt='Odin' />
-~~~
+```
 
 Believe it or not, both examples above are valid! While Example 1 doesn't actually have any meaningful text (perhaps a meaningful *lack of* text), you should still understand its importance. <span id="empty-alt-attribute">When you're using an image purely for decoration, or the image just isn't really important for the user to be aware of, you generally don't want users of assistive technologies to be made aware of it.</span> In those cases, you should **always** use an empty string for the value of the `alt` attribute as seen in Example 1 (this is also known as a null value, not to be confused with the JavaScript data type). If you omitted the `alt` attribute, the presence of the image could still be announced, which may confuse the user (especially if the file name was a random string of letters and numbers).
 
 For Example 2, the screen reader would announce, "Odin, graphic", making the user aware that there's an image and what it's an image of. What the alternative text should be for an image will ultimately depend on various factors, though. Read [Alternative Text - WebAIM](https://webaim.org/techniques/alttext) to learn about when and how you should be adding alternative text for images based on the function of the image and the context surrounding it.
 
 ### Knowledge check
-This section contains questions for you to check your understanding of this lesson. If you’re having trouble answering the questions below on your own, review the material above to find the answer.
 
-* [What are three rules you should follow in order to provide meaningful links?](#meaningful-links-rules)
-* [What information should you inform users of in order to provide meaningful error messages in forms?](#meaningful-error-msg)
-* [When should you use the empty string/null value for the `alt` attribute?](#empty-alt-attribute)
+The following questions are an opportunity to reflect on key topics in this lesson. If you can't answer a question, click on it to review the material, but keep in mind you are not expected to memorize or master this knowledge.
+
+- [What are three rules you should follow in order to provide meaningful links?](#meaningful-links-rules)
+- [What information should you inform users of in order to provide meaningful error messages in forms?](#meaningful-error-msg)
+- [When should you use the empty string/null value for the `alt` attribute?](#empty-alt-attribute)
 
 ### Additional resources
 
-This section contains helpful links to other content. It isn’t required, so consider it supplemental.
+This section contains helpful links to related content. It isn’t required, so consider it supplemental.
 
-* [Making Accessible Links: 15 Golden Rules For Developers](https://www.sitepoint.com/15-rules-making-accessible-links/) is a little old, but is still a great list of 15 rules for creating, well, accessible links. Some of the rules the article goes over were mentioned in this lesson, but there are some other rules that can help make sure you're creating a11y friendly links.
-* [Usable and Accessible Form Validation and Error Recovery](https://webaim.org/techniques/formvalidation/) goes over a few different ways you can provide errors to users (using the `alert` in JavaScript, providing all errors at the top of the page, and using inline errors), as well as the pros and cons of each.
+- [Making Accessible Links: 15 Golden Rules For Developers](https://www.sitepoint.com/15-rules-making-accessible-links/) is a little old, but is still a great list of 15 rules for creating, well, accessible links. Some of the rules the article goes over were mentioned in this lesson, but there are some other rules that can help make sure you're creating a11y friendly links.
+- [Usable and Accessible Form Validation and Error Recovery](https://webaim.org/techniques/formvalidation/) goes over a few different ways you can provide errors to users (using the `alert` in JavaScript, providing all errors at the top of the page, and using inline errors), as well as the pros and cons of each.