-**1. Because:** +## Issue -Closes #XXXXX +If this PR closes an open issue in another TOP repo, replace the #XXXXX with the URL of the issue, e.g. Closes https://github.com/TheOdinProject/curriculum/issues/XXXXX +If this PR does not close, but is related to another issue or PR, you can link it as above without the 'Closes' keyword, e.g. 'Related to #2013'. -**2. This PR:** - +_Note:_ any pull request created for an issue that already has someone else assigned **will be closed without review**. +--> +Closes #XXXXX +## Additional Information + -**3. Additional Information:** - +## Pull Request Requirements + +- [ ] I have thoroughly read and understand [The Odin Project curriculum contributing guide](https://github.com/TheOdinProject/curriculum/blob/main/CONTRIBUTING.md) +- [ ] The title of this PR follows the `location of change: brief description of change` format, e.g. `Intro to HTML and CSS lesson: Fix link text` +- [ ] The `Because` section summarizes the reason for this PR +- [ ] The `This PR` section has a bullet point list describing the changes in this PR +- [ ] If this PR addresses an open issue, it is linked in the `Issue` section +- [ ] If any lesson files are included in this PR, they have been previewed with the [Markdown preview tool](https://www.theodinproject.com/lessons/preview) to ensure it is formatted correctly +- [ ] If any lesson files are included in this PR, they follow the [Layout Style Guide](https://github.com/TheOdinProject/curriculum/blob/main/LAYOUT_STYLE_GUIDE.md) diff --git a/.github/labeler.yml b/.github/labeler.yml index e08049291d0..b0958c5aea8 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -1,6 +1,3 @@ -'Status: Needs Triage': - - '**/*' - 'Content: Advanced HTML/CSS': - 'advanced_html_css/**/*' @@ -22,6 +19,9 @@ 'Content: NodeJS': - 'nodeJS/**/*' +'Content: React': + - 'react/**/*' + 'Content: Ruby': - 'ruby/**/*' @@ -31,5 +31,9 @@ 'Content: Foundations': - 'foundations/**/*' +'Content: Markdownlint': + - 'markdownlint/**/*' + - '**/*.markdownlint-cli2.jsonc' + 'Type: Chore': - 'archive/**/*' diff --git a/.github/workflows/testing.yml b/.github/workflows/codespell.yml similarity index 87% rename from .github/workflows/testing.yml rename to .github/workflows/codespell.yml index 94acdfa5448..9289a3e13c3 100644 --- a/.github/workflows/testing.yml +++ b/.github/workflows/codespell.yml @@ -8,11 +8,10 @@ jobs: name: Check for spelling errors runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - uses: codespell-project/actions-codespell@master with: check_filenames: true check_hidden: true skip: ./.git,*.png,*.csv,./archive,./legacy_submissions - only_warn: 1 ignore_words_file: './.codespellignore' diff --git a/.github/workflows/markdownlint.yml b/.github/workflows/markdownlint.yml new file mode 100644 index 00000000000..2e0b3deb895 --- /dev/null +++ b/.github/workflows/markdownlint.yml @@ -0,0 +1,33 @@ +name: MarkdownLint +on: + pull_request: + paths: + - '**.md' + - '!*' + - '!archive/**' + - '!templates/**' + - '!markdownlint/docs/**' + - '!.github/**' + +jobs: + lesson_lint: + name: Lint lesson/project files + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: tj-actions/changed-files@v46 + id: changed-files + with: + files: | + **.md + !* + !archive/** + !templates/** + !markdownlint/docs/** + !.github/** + separator: ',' + - uses: DavidAnson/markdownlint-cli2-action@v14 + if: steps.changed-files.outputs.all_changed_files + with: + globs: ${{ steps.changed-files.outputs.all_changed_files }} + separator: ',' diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index 07d6d50b4a2..0a751a93397 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -16,7 +16,7 @@ jobs: issues: write pull-requests: write steps: - - uses: actions/stale@v5 + - uses: actions/stale@v9 with: stale-issue-label: "Status: Stale" days-before-issue-stale: 30 @@ -25,4 +25,5 @@ jobs: close-issue-message: "This issue was closed because it has been inactive for 14 days since being marked as stale." days-before-pr-stale: -1 days-before-pr-close: -1 + operations-per-run: 100 repo-token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index 03c21866632..9560b5e84fa 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ test.rb .DS_Store *.swp .vscode/ +node_modules/ diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 00000000000..e3b03c6969e --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,104 @@ +// https://github.com/DavidAnson/markdownlint +{ + "config": { + "default": true, + // heading-style + // Enforces ATX style headings, e.g. ### A level 3 heading + "MD003": { + "style": "atx" + }, + // ul-style + // Enforces dash syntax for unordered lists + "MD004": { + "style": "dash" + }, + // line-length + // Avoids errors related to line lengths in the MD files + "MD013": { + "code_blocks": false, + "headings": false, + "tables": false, + // Arbitrary length - Revisit to possibly set a standard + "line_length": 9999 + }, + // heading-start-left + // Enforces 0 heading indentation + // Overwritten by custom TOP011 rule as certain headings need to be indented + "MD023": false, + // no-trailing-punctuation + // Prevents most punctuation in headings, except for exclamation and question marks + "MD026": { + "punctuation": ".:,;" + }, + // ol-prefix + // Enforces lazy numbering for ordered lists + // MD029 Disabled and overridden by TOP010 rule + "MD029": false, + // no-inline-html + // Only allows specified HTML to be inline + "MD033": { + "allowed_elements": [ + "p", + "a", + "div", + "span", + "kbd", + "script", + "iframe", + "details", + "summary", + "pre" + ] + }, + // first-line-heading/first-line-h1 + // Enforces the first heading on a lesson page to be an H3, since the page template renders an H1 and H2 automatically + "MD041": { + "level": 3 + }, + // proper-names + // Enforces proper spelling of the names array, except for code blocks and HTML elements + "MD044": { + "code_blocks": false, + "html_elements": false, + "names": ["CSS", "HTML", "JavaScript"] + }, + // code-block-style + // Prevents indented code blocks from being used + "MD046": { + "style": "fenced" + }, + // code-fence-style + // Disabled because the TOP008 custom rule covers this + "MD048": false, + // emphasis-style + // Enforces asterisk syntax instead of underscore syntax + "MD049": { + "style": "asterisk" + }, + // strong-style + // Enforces asterisk syntax instead of underscore syntax + "MD050": { + "style": "asterisk" + }, + // link-fragments + // Disabled as it uses a different heading conversion algo to the TOP website + "MD051": false + }, + // Custom rules specific to the project + // Docs for each rule can be found in `./markdownlint/docs` + "customRules": [ + "./markdownlint/TOP001_descriptiveLinkTextLabels/TOP001_descriptiveLinkTextLabels.js", + "./markdownlint/TOP002_noCodeInHeadings/TOP002_noCodeInHeadings.js", + "./markdownlint/TOP003_defaultSectionContent/TOP003_defaultSectionContent.js", + "./markdownlint/TOP004_lessonHeadings/TOP004_lessonHeadings.js", + "./markdownlint/TOP005_blanksAroundMultilineHtmlTags/TOP005_blanksAroundMultilineHtmlTags.js", + "./markdownlint/TOP006_fullFencedCodeLanguage/TOP006_fullFencedCodeLanguage.js", + "./markdownlint/TOP007_useMarkdownLinks/TOP007_useMarkdownLinks.js", + "./markdownlint/TOP008_useBackticksForFencedCodeBlocks/TOP008_useBackticksForFencedCodeBlocks.js", + "./markdownlint/TOP009_lessonOverviewItemsSentenceStructure/TOP009_lessonOverviewItemsSentenceStructure.js", + "./markdownlint/TOP010_useLazyNumbering/TOP010_useLazyNumbering.js", + "./markdownlint/TOP011_headingIndentation/TOP011_headingIndentation.js", + "./markdownlint/TOP012_noteBoxHeadings/TOP012_noteBoxHeadings.js", + "./markdownlint/TOP013_descriptiveHeadings/TOP013_descriptiveHeadings.js" + ] +} diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000000..635b9d07931 --- /dev/null +++ b/.prettierignore @@ -0,0 +1,2 @@ +# We use markdownlint for our lesson and project files +**/*.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 5845dc33fb1..00000000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1 +0,0 @@ -The Odin Project's Code of Conduct is found in their main repository's `doc` folder. [LINK](https://github.com/TheOdinProject/theodinproject/blob/main/doc/code_of_conduct.md) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..f0b44f6e52d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,106 @@ +# The Odin Project Curriculum Contributing Guide + +Thank you for expressing interest in contributing to The Odin Project (TOP) curriculum! Before continuing through this guide, be sure you've read our [general contributing guide](https://github.com/TheOdinProject/.github/blob/main/CONTRIBUTING.md), as it contains information that is important for all of our repos. + +This contributing guide assumes you have followed the instructions in our general contributing guide to fork and clone our curriculum repo. + +## Table of Contents + +- [How to Contribute](#how-to-contribute) +- [Curriculum Linting](#curriculum-linting) +- [Adding Images to the Curriculum](#adding-images-to-the-curriculum) + +## How to Contribute + +There are 2 main ways you can contribute to our curriculum: + +1. If you're new to contributing to open-source, only need to edit 1 file, or if you just want to make a really quick pull request (PR), you can click the "Improve this lesson on GitHub" link found at the end of each lesson. This will open the lesson file in its "edit" mode, allowing you to make any edits and submit a PR all through GitHub. +1. If you're more experienced with contributing or need to edit more than 1 file, you can follow our instructions on [setting up a local clone](https://github.com/TheOdinProject/.github/blob/main/CONTRIBUTING.md) from our general contributing guide. You should also read the sections that follow on how to open a PR. + +Regardless of the way you choose to open a PR, while working on an existing or a new lesson you **must** follow our [Layout Style Guide](https://github.com/TheOdinProject/curriculum/blob/main/LAYOUT_STYLE_GUIDE.md) to ensure the layout and formatting is consistent across our curriculum. + +Before submitting a PR for any lesson, you must also use our [Lesson Preview Tool](https://www.theodinproject.com/lessons/preview) to ensure the lesson Markdown is correctly formatted and rendering properly. + +## Curriculum Linting + +To help enforce the layout specified in our layout style guide, we use [markdownlint](https://github.com/DavidAnson/markdownlint). Whenever a PR is opened or has updates made to it, a workflow will run to check any files changed in the PR against common rules as well as custom rules specific to TOP. To make the workflow easier, we also strongly suggest that users who have a local clone run this linter locally before committing any changes. There are 2 ways you can do so: + +1. Install the [Markdownlint VSCode Plugin](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). This plugin will automatically pick up our markdownlint configuration and flag issues with a squiggly underline. +1. Install the `markdownlint-cli2` dependency. This will require you to have installed Node, which we cover in our Foundations path. Simply run `npm install` within the directory of your curriculum clone and you can run one of our npm scripts to easily lint or fix files. Note that running these scripts without a supplied file path will result in help documentation being output to the terminal. + - Lint a file: `npm run lint -- "./path/to/file"` + - Autofix a file: `npm run fix -- "./path/to/file"` + +> [!IMPORTANT] +> npm scripts always run from the root of the curriculum repo (the same location as this file and `package.json`). Therefore, you *must* provide the full lesson/project file path relative to the repo root, even if your terminal is inside a subdirectory (such as the same directory as the lesson file). + +> [!TIP] +> In some cases, you may need to run a fix script more than once to catch and fix all fixable errors. This typically occurs when a line has multiple errors affecting the same parts and fix actions collide, so Markdownlint only applies some of the fixes. + +> [!NOTE] +> With either of these two methods, keep in mind that not all issues that get flagged will have an autofix available. Some rules require fixes that are more dependent on context and cannot - and should not - be automatically fixed, such as our custom rule `TOP001` for descriptive link text. +> +> The following markdownlint rules are at least partially fixable via the `fix` script: +> +> - [MD004](https://github.com/DavidAnson/markdownlint/blob/main/doc/md004.md) ul-style +> - [MD005](https://github.com/DavidAnson/markdownlint/blob/main/doc/md005.md) list-indent +> - [MD007](https://github.com/DavidAnson/markdownlint/blob/main/doc/md007.md) ul-indent +> - [MD009](https://github.com/DavidAnson/markdownlint/blob/main/doc/md009.md) no-trailing-spaces +> - [MD010](https://github.com/DavidAnson/markdownlint/blob/main/doc/md010.md) no-hard-tabs +> - [MD011](https://github.com/DavidAnson/markdownlint/blob/main/doc/md011.md) no-reversed-links +> - [MD012](https://github.com/DavidAnson/markdownlint/blob/main/doc/md012.md) no-multiple-blanks +> - [MD014](https://github.com/DavidAnson/markdownlint/blob/main/doc/md014.md) commands-show-output +> - [MD018](https://github.com/DavidAnson/markdownlint/blob/main/doc/md018.md) no-missing-space-atx +> - [MD019](https://github.com/DavidAnson/markdownlint/blob/main/doc/md019.md) no-multiple-space-atx +> - [MD022](https://github.com/DavidAnson/markdownlint/blob/main/doc/md022.md) blanks-around-headings +> - [MD023](https://github.com/DavidAnson/markdownlint/blob/main/doc/md023.md) headings-start-left +> - [MD026](https://github.com/DavidAnson/markdownlint/blob/main/doc/md026.md) no-trailing-punctuation +> - [MD027](https://github.com/DavidAnson/markdownlint/blob/main/doc/md027.md) no-multiple-space-blockquote +> - [MD028](https://github.com/DavidAnson/markdownlint/blob/main/doc/md028.md) no-blanks-blockquote +> - [MD030](https://github.com/DavidAnson/markdownlint/blob/main/doc/md030.md) list-marker-space +> - [MD031](https://github.com/DavidAnson/markdownlint/blob/main/doc/md031.md) blanks-around-fences +> - [MD032](https://github.com/DavidAnson/markdownlint/blob/main/doc/md032.md) blanks-around-lists +> - [MD037](https://github.com/DavidAnson/markdownlint/blob/main/doc/md037.md) no-space-in-emphasis +> - [MD038](https://github.com/DavidAnson/markdownlint/blob/main/doc/md038.md) no-space-in-code +> - [MD039](https://github.com/DavidAnson/markdownlint/blob/main/doc/md039.md) no-space-in-links +> - [MD044](https://github.com/DavidAnson/markdownlint/blob/main/doc/md044.md) proper-names +> - [MD047](https://github.com/DavidAnson/markdownlint/blob/main/doc/md047.md) single-trailing-newline +> - [MD049](https://github.com/DavidAnson/markdownlint/blob/main/doc/md049.md) emphasis-style +> - [MD050](https://github.com/DavidAnson/markdownlint/blob/main/doc/md050.md) strong-style +> - [MD053](https://github.com/DavidAnson/markdownlint/blob/main/doc/md053.md) link-image-reference-definitions +> - [TOP002](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP002.md) no-code-in-headings +> - [TOP003](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP003.md) default-section-content +> - [TOP005](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP005.md) blanks-around-multiline-html-tags +> - [TOP006](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP006.md) full-fenced-code-language +> - [TOP007](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP007.md) use-markdown-links +> - [TOP008](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP008.md) use-backticks-for-fenced-code-blocks +> - [TOP010](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP010.md) use-lazy-numbering +> - [TOP011](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP011.md) heading-indentation +> - [TOP012](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP012.md) note-box-headings + +## Adding Images to the Curriculum + +Adding images to the curriculum is a two-step process, involving two PRs. For a general overview, you need to: + +1. Upload the image(s) to the repository. +1. Create `statically.io` links to the images and add those links to the appropriate lesson(s). + +### Uploading Images to the Repository + +1. Have a copy of the image you want to upload on your local machine. +1. If it doesn’t already exist, create a directory with the same name in the same directory as the lesson you want to add an image to. +1. If it doesn’t already exist, create an `imgs` directory inside of the directory you made in the previous step. +1. Add your image to the directory you made in step 3, naming it the order it appears on the page starting from 00 (i.e. the second image in a lesson will be `01.png` (or whatever extension)). If replacing an image, just replace the appropriate image file. +1. PR the addition of the image(s). Here is an [example PR](https://github.com/TheOdinProject/curriculum/pull/22421) where this process was followed. + +### Creating Statically Links + +1. Go to the PR that added the image(s) to the repo. +1. Right-click the commit ID where it was merged and select `copy link`. + +  +1. Go to https://wise-king-sullyman.github.io/better-statically-converter-react/ +1. Paste the URL you copied into the text box on the main screen of that site, then hit Enter. +1. The site will generate the statically CDN link to each image that was merged into the curriculum with that PR. You can click each link to auto-copy that link to your clipboard. +1. Use each of these links to link to your desired images in the curriculum content you’re editing/adding. +1. PR the addition of the image links (and any other content you’ve added/changed in the lesson). + diff --git a/LAYOUT_STYLE_GUIDE.md b/LAYOUT_STYLE_GUIDE.md index 980644a308d..5843f973169 100644 --- a/LAYOUT_STYLE_GUIDE.md +++ b/LAYOUT_STYLE_GUIDE.md @@ -1,57 +1,59 @@ -# Layout Style Guide +# Layout style guide -[Inspired by google's styleguide](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md) +Inspired by [Google's styleguide](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md). -TOP uses Markdown for the layout and formatting of lesson and project files to get properly formatted HTML for the TOP website. +TOP uses Markdown for the layout and formatting of lesson and project files to get properly formatted HTML for the TOP website. **The goals of this style guide are to help create Markdown that is:** -* Readable for as many users as possible. -* Editable by any contributor. -* Consistent across the TOP website. - -**Contents:** - -1. [Lesson layout](#lesson-layout) -1. [Project layout](#project-layout) -1. [Headings](#headings) - 1. [ATX-style headings](#atx-style-headings) -1. [Newlines](#newlines) -1. [Lists](#lists) - 1. [Use lazy numbering for long lists](#use-lazy-numbering-for-long-lists) - 1. [Nested list spacing](#nested-list-spacing) -1. [Code](#code) - 1. [Inline](#inline) - 1. [Codeblocks](#codeblocks) - 1. [Declare the language](#declare-the-language) - 1. [Nest codeblocks within lists](#nest-codeblocks-within-lists) -1. [Links](#links) -1. [Images](#images) -1. [Codepen Embeds](#codepen-embeds) -1. [English Writing Style](#english-writing-style) +- Readable for as many users as possible. +- Editable by any contributor. +- Consistent across the TOP website. +**A note on language**: TOP follows American English and American style punctuation. When adding content to the curriculum, be sure to follow this practice for consistency across lessons. + +**Using formatters**: Many projects have a standard in how their code is formatted which should always be followed when contributing. If you're using a formatter (such as Prettier), you should always be sure you aren't accidentally committing code that goes against that standard. This can be achieved by simply disabling the formatter, saving your files without formatting, or configuring your formatter to adhere to the project's standard. + +## Table of Contents + +1. [Lesson layout](#lesson-layout) +1. [Project layout](#project-layout) +1. [Headings](#headings) +1. [Newlines](#newlines) +1. [Lists](#lists) +1. [Code](#code) +1. [Note boxes](#note-boxes) +1. [Links](#links) +1. [Images](#images) +1. [Keyboard shortcuts](#keyboard-shortcuts) +1. [Codepen embeds](#codepen-embeds) +1. [Mermaid diagrams](#mermaid-diagrams) +1. [Markdown styling](#markdown-styling) ## Layouts +Markdownlint: [`lesson-headings`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP004.md), [`default-section-content`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP003.md) + In general, the following layouts should be used for all lessons and projects. Text that should be replaced with the author's own content will be in all CAPS, with any additional information regarding a section listed at the end of the layout code block. When adding new lessons or projects, make a copy of either the [lesson template](./templates/lesson-template.md) or the [project template](./templates/project-template.md) in the appropriate folder where the new lesson/project should be placed. Then begin editing the template copy. The [lesson example](./templates/lesson-example.md) and [project example](./templates/project-example.md) files both show how this style guide can be put to use in an actual lesson/project. They don't cover every situation (the lesson example doesn't show a lesson with an assignment and one without, for example), but they should give you a better representation of how lessons/projects should look after this style guide is applied. -### Lesson Layout +### Lesson layout -~~~markdown +Markdownlint: [`lesson-overview-items-sentence-structure`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP009.md) +```markdown ### Introduction A BRIEF INTRODUCTION. -### Lesson Overview +### Lesson overview This section contains a general overview of topics that you will learn in this lesson. -* A LESSON OVERVIEW ITEM. +- A LESSON OVERVIEW ITEM. ### CUSTOM SECTION HEADING @@ -61,346 +63,590 @@ CUSTOM SECTION CONTENT.
-1. A RESOURCE OR EXERCISE ITEM
- * AN INSTRUCTION ITEM
+#### OPTIONAL CUSTOM ASSIGNMENT HEADING
+
+1. A RESOURCE OR EXERCISE ITEM
+ - AN INSTRUCTION ITEM
-### Knowledge Check
+### Knowledge check
+
+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.
-This section contains questions for you to check your understanding of this lesson on your own. If you’re having trouble answering a question, click it and review the material it links to.
+- [A KNOWLEDGE CHECK QUESTION](A-KNOWLEDGE-CHECK-URL)
-* A KNOWLEDGE CHECK QUESTION.
+### Additional resources
-### 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.
+```
-* It looks like this lesson doesn't have any additional resources yet. Help us expand this section by contributing to our curriculum.
+1. `### Introduction`: A brief summary on what the lesson is about and/or why the topics or concepts it covers are important. Replace the `A BRIEF INTRODUCTION.` text with your own lesson introduction.
-~~~
+1. `### Lesson overview`: A bulleted list of items that provide a general overview of what the user will learn about in the lesson. Lesson overviews should include general, higher level statements that cover the core concepts of the lesson. They should serve and be phrased as a list of key items that a user should be expected to *learn about* throughout the lesson, rather than a list of things they should be able to *do* by the end of it.
-1. `### Introduction`: A brief summary on what the lesson is about and/or why the topics or concepts it covers are important. Replace the `A BRIEF INTRODUCTION.` text with your own lesson introduction.
+ Replace the `A LESSON OVERVIEW ITEM.` text with your own lesson overview item, then add any additional bulleted lesson overview items. The lesson should ideally have no more than 7 lesson overview items, but this number might vary by lesson. **If the lesson does not have a lesson overview, remove this entire section from the lesson.**
-2. `### Lesson Overview`: A bulleted list of items that provide a general overview of what the user will learn about in the lesson. Lesson Overviews should include general, higher level statements that cover the core concepts of the lesson. They should serve and be phrased as a list of key items that a user should be expected to *learn about* throughout the lesson, rather than a list of things they should be able to *do* by the end of it.
+1. `### CUSTOM SECTION HEADING`: A custom section that contains some of the main content of the lesson. Replace the `CUSTOM SECTION HEADING` text with a proper section heading and the `CUSTOM SECTION CONTENT.` text with your own content, then add any additional custom sections. **If the lesson does not have any custom sections, remove this entire section from the lesson.**
- Replace the `A LESSON OVERVIEW ITEM.` text with your own lesson overview item, then add any additional bulleted lesson overview items. The lesson should ideally have no more than 7 lesson overview items, but this number might vary by lesson. **If the lesson does not have a lesson overview, remove this entire section from the lesson.**
+1. `### Assignment`: A numbered list of external resources the user must read or watch, or practical exercises the user must complete (such as our exercise repos), in order to fully complete the lesson. If an assignment is intended to have multiple lists, each list should include a level 4 heading by replacing the `#### OPTIONAL CUSTOM ASSIGNMENT HEADING` with a proper level 4 heading, otherwise this custom heading can be omitted.
-3. `### CUSTOM SECTION HEADING`: A custom section that contains some of the main content of the lesson. Replace the `CUSTOM SECTION HEADING` text with a proper section heading and the `CUSTOM SECTION CONTENT.` text with your own content, then add any additional custom sections. **If the lesson does not have any custom sections, remove this entire section from the lesson.**
+ Each assignment item should include some brief text that further informs the user on why it is included in the assignment or what purpose it serves. When necessary, an assignment item should also explicitly state any instructions that should be followed. Examples of instructions can include (but aren't limited to) a specific section the user should read, whether the user should complete any specific exercises, and whether the user should redirect themselves to additional links within the resource.
-4. `### Assignment`: A numbered list of external resources the user must read or watch, or practical exercises the user must complete (such as our exercise repos), in order to fully complete the lesson.
+ Replace the `A RESOURCE OR EXERCISE ITEM.` text with your own text and a link to the resource or exercise (or any applicable instructions if an exercise isn't external), then add any additional numbered assignment items. The lesson should ideally have no more than 3-5 assignment items (reading several sections on a web page or completing a folder of 5 exercises would be considered a single assignment item). **If the lesson does not have an assignment, remove this entire section from the lesson.**
- Each assignment item should include some brief text that further informs the user on why it is included in the assignment or what purpose it serves. When necessary, an assignment item should also explicitly state any instructions that should be followed. Examples of instructions can include (but aren't limited to) a specific section the user should read, whether the user should complete any specific exercises, and whether the user should redirect themselves to additional links within the resource.
+ If an assignment item includes any instructions, replace the `AN INSTRUCTION ITEM` text with a single instruction, then add any additional bulleted instruction items.
- Replace the `A RESOURCE OR EXERCISE ITEM.` text with your own text and a link to the resource or exercise (or any applicable instructions if an exercise isn't external), then add any additional numbered assignment items. The lesson should ideally have no more than 3-5 assignment items (reading several sections on a web page or completing a folder of 5 exercises would be considered a single assignment item). **If the lesson does not have an assignment, remove this entire section from the lesson.**
+ If a user should only read specific sections within a resource (e.g. "Skip Chapter 7") or complete only specific exercises (e.g. "Complete the first two exercises in the repo"), each instruction item should be its own bullet.
- If an assignment item includes any instructions, replace the `AN INSTRUCTION ITEM` text with a single instruction, then add any additional bulleted instruction items.
-
- If a user should only read specific sections within a resource (e.g. "Skip Chapter 7") or complete only specific exercises (e.g. "Complete the first two exercises in the repo"), each instruction item should be its own bullet.
-
- **If an assignment item does not have any instructions, remove the bulleted `AN INSTRUCTION ITEM` text from it.**
+ **If an assignment item does not have any instructions, remove the bulleted `AN INSTRUCTION ITEM` text from it.**
-5. `### Knowledge Check`: A bulleted list of specific questions that a user should be able to answer on their own after reading the lesson and completing any assignment or practice. A knowledge check should only link either to a section within the lesson (either with a Heading 3 `###` or Heading 4 `####`, or by wrapping text in a `` element with an `id` attribute) or a resource previously linked to in the lesson. This link should help users review the necessary material in order to answer the knowledge check without requiring them to re-read the entire lesson.
+1. `### Knowledge check`: A bulleted list of specific questions that should aid users in reflecting on the lesson's key topics. A knowledge check should only link either to a section within the lesson (either with a Heading 3 `###` or Heading 4 `####`, or by wrapping text in a `` element with an `id` attribute), or a resource previously linked to in the lesson. This link should help users review the applicable material without requiring them to re-read the entire lesson.
- Replace the `A KNOWLEDGE CHECK URL` text with the actual link to the section/resource and the `A KNOWLEDGE CHECK QUESTION.` text with your own question/problem that the user should be able to answer/solve. Then add any additional bulleted knowledge check items. The lesson should ideally have no more than 7 knowledge checks, but this number might vary by lesson. **If the lesson does not have a knowledge check, remove this entire section from the lesson.**
+ Replace the `A KNOWLEDGE CHECK URL` text with the actual link to the section/resource and the `A KNOWLEDGE CHECK QUESTION.` text with your own question/problem that the user should be able to answer/solve. Then add any additional bulleted knowledge check items. The lesson should ideally have no more than 7 knowledge checks, but this number might vary by lesson. **If the lesson does not have a knowledge check, remove this entire section from the lesson.**
- In order to link to a Heading 3 `###` or Heading 4 `####` within the lesson, replace the `href` value for the knowledge check link with a hashtag `#` followed immediately by the section title in lowercase and any spaces replaced with a hyphen `-`. For example, a Heading 3 section titled `### Creating a Method` would be linked to with `href="#creating-a-method"`.
-
- In order to link to a `` element within the lesson, replace the `href` value with the exact `id` attribute of the `` element (this will be case sensitive). For example, a `` element would be linked to with `href="#Knowledge-Check-3"`.
+ In order to link to a Heading 3 `###` or Heading 4 `####` within the lesson, replace the value within the parenthesis for the knowledge check link with a hashtag `#` followed immediately by the section title in lowercase and any spaces replaced with a hyphen `-`. For example, a Heading 3 section titled `### Creating a method` would be linked to with `(#creating-a-method)`.
-6. `### Additional Resources`: A bulleted list of optional resources for the user to read. Additional resources should be related to the content of the lesson in some way, without being necessary to gain an understanding of the lesson content. An additional resource should include brief text that further informs the user on why it is included or what purpose it serves.
+ In order to link to a `` element within the lesson, replace the value within the parenthesis with the exact `id` attribute of the `` element (this will be case sensitive). For example, a `` element would be linked to with `(#Knowledge-Check-3)`.
- **If the lesson doesn't include any additional resources, leave this section as-is**. Otherwise, replace the default bulleted resource item with your own resource, then add any additional bulleted resource items. The lesson should ideally have no more than 3-5 additional resources.
+1. `### Additional resources`: A bulleted list of optional resources for the user to read. Additional resources should be related to the content of the lesson in some way, without being necessary to gain an understanding of the lesson content. An additional resource should include brief text that further informs the user on why it is included or what purpose it serves, and generally should stand out in some way from the lesson content and other additional resources. A good rule of thumb is to try and answer, "what purpose does this resource serve?"
-### Project Layout
+ **If the lesson doesn't include any additional resources, leave this section as-is**. Otherwise, replace the default bulleted resource item with your own resource, then add any additional bulleted resource items. The lesson should ideally have no more than 3-5 additional resources.
-~~~markdown
+### Project layout
-### Introduction
+```markdown
+### Introduction
A BRIEF INTRODUCTION.
-### PRE-ASSIGNMENT SECTION HEADING
+### OPTIONAL PRE-ASSIGNMENT SECTION HEADING
-PRE-ASSIGNMENT SECTION CONTENT.
+OPTIONAL PRE-ASSIGNMENT SECTION CONTENT.
### Assignment
-1. A REQUIREMENT/USER STORY.
+#### OPTIONAL CUSTOM ASSIGNMENT HEADING
-#### Extra Credit
+1. A REQUIREMENT/USER STORY.
-* AN OPTIONAL ADD-ON/USER STORY.
+#### Extra credit
-
+- AN OPTIONAL ADD-ON/USER STORY.
-### POST-ASSIGNMENT SECTION HEADING
+
-POST-ASSIGNMENT SECTION CONTENT.
+### OPTIONAL POST-ASSIGNMENT SECTION HEADING
-~~~
+OPTIONAL POST-ASSIGNMENT SECTION CONTENT.
+```
-1. `### Introduction`: A brief summary on what the project is and an overview of what the user will be building. Replace the `A BRIEF INTRODUCTION.` text with your own project introduction.
+1. `### Introduction`: A brief summary on what the project is and an overview of what the user will be building. Replace the `A BRIEF INTRODUCTION.` text with your own project introduction.
-2. `### PRE-ASSIGNMENT SECTION HEADING`: *Optional*. A section that contains content that should come before the actual project assignment. This section will most likely not be needed for most projects, but when it is needed simply replace the `PRE-ASSIGNMENT SECTION HEADING` text with a proper section heading and the `PRE-ASSIGNMENT SECTION CONTENT.` text with your own content. Then add any additional pre-assignment sections. **If the project does not have a pre-assignment section, remove this entire section from the project.**
+1. `### OPTIONAL PRE-ASSIGNMENT SECTION HEADING`: A section that contains content that should come before the actual project assignment. This section will most likely not be needed for most projects, but when it is needed simply replace the `OPTIONAL PRE-ASSIGNMENT SECTION HEADING` text with a proper section heading and the `OPTIONAL PRE-ASSIGNMENT SECTION CONTENT.` text with your own content. Then add any additional pre-assignment sections. **If the project does not have a pre-assignment section, remove this entire section from the project.**
-3. `### Assignment`: A numbered list of items that describe detailed requirements or user stories that must be followed in order to complete the project. Replace the `A REQUIREMENT/USER STORY.` with your own requirement, then add any additional numbered requirement items.
+1. `### Assignment`: A numbered list of items that describe detailed requirements or user stories that must be followed in order to complete the project. Replace the `A REQUIREMENT/USER STORY.` with your own requirement, then add any additional numbered requirement items. If an assignment is intended to have multiple lists, each list should include a level 4 heading by replacing the `#### OPTIONAL CUSTOM ASSIGNMENT HEADING` with a proper level 4 heading, otherwise this custom heading can be omitted.
-4. `#### Extra Credit`: A bulleted list of items that describe any optional add-ons or user stories that might make a user's project stand out. Replace the `AN OPTIONAL ADD-ON/USER STORY.` text with your own add-on, then add any additional bulleted add-on items. **If the project does not have any extra credit items, remove the extra credit section from the assignment.**
+1. `#### Extra credit`: A bulleted list of items that describe any optional add-ons or user stories that might make a user's project stand out. Replace the `AN OPTIONAL ADD-ON/USER STORY.` text with your own add-on, then add any additional bulleted add-on items. **If the project does not have any extra credit items, remove the extra credit section from the assignment.**
-5. `### POST-ASSIGNMENT SECTION HEADING`: *Optional*. A section that contains content that should come after the actual project assignment. This section will most likely not be needed for most projects, but when it is needed simply replace the `POST-ASSIGNMENT SECTION HEADING` text with a proper section heading and the `POST-ASSIGNMENT SECTION CONTENT.` text with your own content. Then add any additional post-assignment sections. **If the project does not have a post-assignment section, remove this entire section from the project.**
+1. `### OPTIONAL POST-ASSIGNMENT SECTION HEADING`: A section that contains content that should come after the actual project assignment. This section will most likely not be needed for most projects, but when it is needed simply replace the `OPTIONAL POST-ASSIGNMENT SECTION HEADING` text with a proper section heading and the `OPTIONAL POST-ASSIGNMENT SECTION CONTENT.` text with your own content. Then add any additional post-assignment sections. **If the project does not have a post-assignment section, remove this entire section from the project.**
## Headings
-### Title Case
+### Accessible headings
+
+Markdownlint: [`descriptive-headings`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP013.md)
+
+For accessibility, headings must briefly summarize their section's contents, rather than just saying something overly generic like "Note", "Remember" or "Warning".
+
+### Indentation
+
+Markdownlint: [`heading-indentation`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP011.md)
+
+Headings must not be indented, regardless of level and even if they are inside an assignment `div`. The only exception is when the heading is for a [note box](#note-boxes).
+
+### Case
+
+Headings should always use sentence case:
-Headings should always use [Wikipedia Style Title Case](https://titlecaseconverter.com/rules/#WP):
+```markdown
+
+### This Is Not Sentence case
-~~~markdown
-### This Is Wikipedia Style Title Case
+
+### This is sentence case
-### This is not Wikipedia style title case
-~~~
+
+### This is also sentence case with HTML
+```
-You can use the [Title Case Converter](https://titlecaseconverter.com/) tool to help convert text to Wikipedia Title Case; just select the Wikipedia "Styles" option.
+### No code snippets
-### No Code Snippets
+Markdownlint: [`no-code-headings`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP002.md)
Headings should never contain any code snippets.
```markdown
-
-### The `id` Property
+
+### The `id` property
-
-### The id Property
+
+### The id property
```
+### Trailing punctuation
+
+Markdownlint: [`no-trailing-punctuation`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md026.md)
+
+Headings must not end with `.`, `,`, `:` or `;`.
+
### ATX-style headings
-Use Heading 3 `###` for main section titles ("Lesson Overview", "Assignment", custom sections, etc):
+Markdownlint: [`heading-style`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md003.md), [`no-missing-space-atx`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md018.md), [`no-multiple-space-atx`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md019.md), [`no-emphasis-as-heading`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md036.md)
-~~~markdown
-### Section Heading
-~~~
+Use Heading 3 `###` for main section titles ("Lesson overview", "Assignment", custom sections, etc):
+
+```markdown
+### Section heading
+```
### Sub-heading
-Use either Heading 4 `####` for sub-headings that are on their own line or `**Sub-heading**` for inline:
+Use either Heading 4 `####` for sub-headings that are on their own line or Markdown's bold syntax, e.g. `**Sub-heading**`, for inline sub-headings:
-~~~markdown
+```markdown
...text before.
#### Sub-heading
Text after...
-**Inline Sub-heading:** Some text defining this sub-heading...
-~~~
+**Inline sub-heading:** Some text defining this sub-heading...
+```
## Newlines
-Each Markdown file should have an empty newline at the very end, after all of the file's contents.
+Markdownlint: [`no-multiple-blanks`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md012.md), [`blanks-around-multiline-html-tags`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP005.md), [`blanks-around-headings`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md022.md), [`blanks-around-fences`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md031.md), [`blanks-around-lists`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md032.md), [`single-trailing-newline`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md047.md)
-Always add a newline before and after a heading, a list, an Assignment panel, or any other content that is not strictly text:
+Each Markdown file should have an empty newline at the very end, after all of the file's contents.
-~~~markdown
+Always add a newline before and after a heading, a list, an Assignment panel, HTML tags used for page markup, or any other content that is not strictly text:
+
+```markdown
Content before...
-### Section Heading
+### Section heading
1. A list item
...content after.
-~~~
+
+
+
+#### Note box heading
+
+Note box contents.
+
+
+```
## Lists
-### Use lazy numbering for long lists
+Markdownlint: [`list-marker-space`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md030.md)
+
+The Odin Project follows [Google's documentation style guide on lists](https://developers.google.com/style/lists#numbered-lettered-bulleted-lists).
+
+### Capitalization and end punctuation
-Markdown is smart enough to let the resulting HTML render your numbered lists
-correctly. For longer lists that may change, especially long nested lists, use
-"lazy" numbering:
+Capitalization and end punctuation depend on the type of list and the contents of the list.
-~~~markdown
-1. Foo.
-1. Bar.
- 1. Foofoo.
- 1. Barbar.
-1. Baz.
-~~~
+Generally, start each list item with a capital letter and end each list item with a period or other appropriate sentence-ending punctuation.
-However, if the list is small and you don't anticipate changing it, prefer fully
-numbered lists, because it's nicer to read in source:
+```markdown
+- Use Git to make open-source contributions.
+- Understand how the web works.
+- Explain what OOP principles are.
+```
+
+Do not use end punctuation in the following cases:
+
+- If the item consists of a single word, don't use end punctuation.
+- If the item doesn't include a verb, don't use end punctuation.
+
+For more detailed examples of the exceptions, refer to [Google's style guide on lists](https://developers.google.com/style/lists#capitalization-and-end-punctuation)
+
+### Lazy numbering
+
+Markdownlint: [`lazy-numbering-for-ordered-lists`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP010.md)
+
+Markdown is smart enough to let the resulting HTML render your numbered lists correctly. For longer lists that may change, especially long nested lists, use "lazy" numbering. The following Markdown:
+
+```markdown
+1. Foo
+1. Bar
+1. Foofoo
+1. Barbar
+1. Baz
+```
+
+Will result in the following output:
+
+1. Foo
+1. Bar
+1. Foofoo
+1. Barbar
+1. Baz
+
+### Nested lists
+
+Markdownlint: [`list-indent`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md005.md), [`ul-indent`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md007.md)
-~~~markdown
-1. Foo.
-2. Bar.
-3. Baz.
-~~~
+When nesting lists, use a 2 space indent when nesting inside a bulleted list and a 3 space indent when nesting inside a numbered list. The following Markdown:
-### Nested list spacing
+```markdown
+1. The first item
+1. A second item
+ - A sub-item for the second item with 3 spaces before the hyphen
+
+- A bulleted list item
+ - A sub-bullet with a 2 space indent
+- A new list item
+```
-When nesting lists, use a 4 space indent for both numbered and bulleted lists:
+Will result in the following output:
-~~~markdown
-1. 2 spaces after a numbered list.
- 4 space indent for wrapped text.
-2. 2 spaces again.
+1. The first item
+1. A second item
+ - A sub-item for the second item with 3 spaces before the hyphen
-* 3 spaces after a bullet.
- 4 space indent for wrapped text.
- 1. 2 spaces after a numbered list.
- 8 space indent for the wrapped text of a nested list.
- 2. Looks nice, don't it?
-* 3 spaces after a bullet.
-~~~
+- A bulleted list item
+ - A sub-bullet with a 2 space indent
+- A new list item
### Multi-line list items
-When list items wrap into multiple lines, consider adding newlines per item
-to make it more readable:
+When list items should wrap onto multiple lines – such as to create a line break between a lengthy list item – insert an empty line before and after each wrapped line and use a 2 to 3 space indent on the wrapped line. You should use a 2 space indent for bulleted lists and a 3 space indent for numbered lists. The following Markdown:
+
+```markdown
+1. This is a lengthy list item.
+
+ This is related information to the first item, but visually separated out.
-~~~markdown
+1. A new list item
-1. This is a long long long long long long long long long long long long long
- long long long long long long list item.
+- This is a lengthy bulleted list item.
-2. This is another long long long long long long long long long long long long
- long long long long long long long list item.
+ This is related information to the first item, but visually separated out.
-~~~
+- A new bulleted list item
+```
-This will add a paragraph tag to your list item: `
-~~~javascript
+````markdown
+```javascript
const obj = {
name: "object",
marker: "X"
}
-~~~
-
+```
+````
#### Declare the language
-It is best practice to explicitly declare the language immediately after the opening tilde marks, so that neither the
+Markdownlint: [fenced-code-language](https://github.com/DavidAnson/markdownlint/blob/main/doc/md040.md), [`full-fenced-code-language`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP006.md)
+
+It is best practice to explicitly declare the language immediately after the opening backticks, so that neither the
syntax highlighter nor the next editor must guess.
-#### No Extraneous Characters
+If a language has both a long and short form that markdown will accept, for example `javascript` will also be accepted as `js`, and `text` will also be accepted as `txt`, the long form must be used.
+
+#### No extraneous characters
+
+Markdownlint: [`commands-show-output`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md014.md)
Codeblocks should only contain actual code snippets, terminal commands, or commented out text. Never include leading terminal content, such as the dollar sign `$` you might see preceding any commands you type in.
```bash
-// The below example is incorrect
+# Incorrect
$ cd Documents
-// The below is correct
+# Correct
cd Documents
```
#### Nest codeblocks within lists
-If you need a codeblock within a list, make sure to indent it so as to not break
-the list:
+If you need a codeblock within a list, you should follow the same indenting rules for [multi-line list items](#multi-line-list-items), with the codeblock being indented with 2 spaces for a bulleted list item and 3 spaces for a numbered list item. The following Markdown:
+
+````markdown
+- Bullet.
+
+ ```javascript
+ // We start indenting with 2 space for the codeblock
+ function tester() {
+ const yay = 'From here we can indent like we normally would'
+ }
+ ```
+
+- Next bullet.
+````
+
+Will result in the following output:
+
+- Bullet.
+
+ ```javascript
+ // We start indenting with 2 space for the codeblock
+ function tester() {
+ const yay = 'From here we can indent like we normally would'
+ }
+ ```
+
+- Next bullet.
+
+## Note boxes
+
+Markdownlint: [`note-box-headings`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP012.md)
+
+Note boxes can be added by wrapping the content in a `div` with the class `lesson-note`. This will add styling to make the note stand out visually to users.
+
+All note boxes must open with a level 4 heading (`####`), which will also require the note box div to have the `markdown="1"` attribute so the heading renders correctly. Note box [headings must be sufficiently descriptive](#accessible-headings) for accessibility.
+
+Note box headings must match the note box's indentation level, such as if the note box is indented as a child of a list item.
+
+### Variations
+
+Different types of note boxes can be set by adding an extra class together with `lesson-note`:
+
+- `lesson-note--tip` for tips
+- `lesson-note--warning` for warnings about potential issues/pitfalls, and are more severe than a tip
+- `lesson-note--critical` for the most important warnings, such as critical information about handling sensitive data
+
+#### Example
+
+```markdown
+
+
+#### A descriptive title
+
+A sample note box.
+
+
+```
+
+```markdown
+
-~~~markdown
-* Bullet.
+#### A descriptive title
- ~~~ruby
- puts foo;
- ~~~
+A sample note box, variation: tip.
-* Next bullet.
-~~~
+
+```
## Links
Long links make source Markdown difficult to read and break the 80 character wrapping. **Wherever possible, shorten your links**.
-### Use informative Markdown link titles
+### Use Markdown links
+
+Markdownlint: [`use-markdown-links`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP007.md), [`no-bare-urls`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md034.md)
+
+Instead of using HTML anchor tags for links, use Markdown links instead.
+
+```markdown
+
+See the lesson template for a more easily copyable lesson file.
+
+
+See the [lesson template](./templates/lesson-template.md) for a more easily copyable lesson file.
+```
+
+### Use informative titles
+
+Markdownlint: [`descriptive-link-text-labels`](https://github.com/TheOdinProject/curriculum/blob/main/markdownlint/docs/TOP001.md), [`no-empty-links`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md042.md)
Markdown link syntax allows you to set a link title, just as HTML does. Use it wisely.
Titling your links as "link" or "here" tells the reader precisely nothing when quickly scanning your doc and is a waste of space. Instead, write the sentence naturally, then go back and wrap the most appropriate phrase with the link:
-~~~markdown
+```markdown
See the [lesson template](./templates/lesson-template.md) for a more easily copyable lesson file.
Or, check out the [project template](./templates/project-template.md) for a more easily copyable project file.
-~~~
+```
+
+Typically you want to ensure the link text describes the purpose of the link or where the link will redirect a user, and can often be the title of a blog article or video. You should also do your best to avoid including "this" and "here" in the link text to avoid our linter from flagging it as an error, even if the link text is descriptive. Often times "this" or "here" aren't necessary as part of the link text, and may cause some confusion despite a descriptive text ("Where's here??").
+
+```markdown
+
+Check out [this video on flex-grow from CoolYoutuber](...url)
+Go look at our [installations guide here](...url)
+
+
+Check out this [video on flex-grow from CoolYoutuber](...url)
+Go look at our [installations guide](...url)
+```
+
+Additionally, if there are multiple links in a lesson that redirect to the same `href`, the link text for each link must be the same. For example:
+
+```markdown
+
+Go to [Google](www.google.com)
+Try [searching on Google](www.google.com)
+First go to the [Google homepage](www.google.com)
+
+
+Go to [Google](www.google.com)
+Try searching on [Google](www.google.com)
+First go to the [Google](www.google.com) homepage
+```
-### Don't place links throughout lessons
+### Don't scatter links throughout lessons
-Links to required reading should not be placed throughout a lesson, and should instead be placed in either the `### Assignment` or `### Additional Resources` section. Links that refer a user to a previous lesson as a refresher, or a link to a Wikipedia page that offers a definition/explanation of a term are fine to place outside of these two sections.
+Links to required reading should not be scattered throughout a lesson, and should instead be placed in either the `### Assignment` or `### Additional resources` section. Links that refer a user to a previous lesson as a refresher, or a link to a Wikipedia page that offers a definition/explanation of a term are fine to place outside of these two sections.
## Images
+Markdownlint: [`no-alt-text`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md045.md)
+
Images in Markdown follow the same syntax as links, except they begin with an exclamation point `!`:
-~~~markdown
+```markdown
-~~~
+```
The text in square brackets will be included as the image's alt text. Similar to link titles, the alt text should be informative, but shouldn't be overly verbose.
In order to properly add images to a lesson, follow the instructions in our [Adding Images to the Curriculum](https://github.com/TheOdinProject/curriculum/wiki/Adding-Images-to-the-Curriculum) Wiki page to get a statically URL as seen in the codeblock above.
-## Codepen Embeds
+## Keyboard shortcuts
+
+For keyboard shortcuts we use the HTML keyboard input element ``.
+
+Example code which will be rendered as: Ctrl + Shift + ?
+
+```html
+Ctrl + Shift + ?
+```
+
+### Style standardization
+
+- Use separate `` elements for individual keys:
+
+ ```markdown
+ Ctrl + Shift
+ ```
+
+- Use capitalized common abbreviations for the keys and avoid using symbols like `⌘`:
+
+ ```markdown
+ Cmd
+ Alt
+ B
+ Opt
+ ```
+
+- Use symbols for character keys instead of spelling out the symbol like `period`:
+
+ ```markdown
+ .
+ ,
+ Ctrl + Shift + ?
+ ```
+
+## Codepen embeds
In order to embed a Codepen example into a lesson, you must be in the editor view for the Codepen you wish to embed and then click the `Embed` button at the bottom right of the page.
The following options should be selected when creating a Codepen embed:
-* **Default Tabs**: The "Result" tab must be selected in addition to one of the other three options (HTML, CSS, or JavaScript), depending on the main purpose of the Codepen. If the purpose is to show an HTML concept then the "HTML" option must also be selected, for example.
-* **Theme**: "Dark"
-* **Use Click-to-Load**: "Off"
-* **Make Code Editable**: "On"
+- **Default Tabs**: The "Result" tab must be selected in addition to one of the other three options (HTML, CSS, or JavaScript), depending on the main purpose of the Codepen. If the purpose is to show an HTML concept then the "HTML" option must also be selected, for example.
+- **Theme**: "Dark"
+- **Use Click-to-Load**: "Off"
+- **Make Code Editable**: "On"
Finally, the **HTML (Recommended)** code option must be the one that is copy + pasted into the lesson.
-### Maintainer Instructions
+### Maintainer instructions
When a user adds a Codepen embed to a lesson, a maintainer should fork the embed to the official [TOP Codepen](https://codepen.io/TheOdinProjectExamples/) account. When necessary, the name of new pens should be updated to better reflect their purpose, e.g. `Simple SVG Example` for a pen showing a simple SVG or `max-width | CSS Responsiveness` for a pen about the `max-width` property.
After forking a pen to the TOP account and ensuring the embeds options from above are selected, the lesson the original embed is from should be updated to include the forked, TOP version instead.
-## English Writing Style
+## Mermaid diagrams
-As a general note, TOP follows American English and American style punctuation. When adding content to the curriculum, be sure to follow this practice for consistency across lessons.
+To add a Mermaid diagram to a lesson, visit the [Mermaid docs](https://mermaid.js.org/syntax/flowchart.html) to learn the diagram syntax for the specific type of diagram you want to add. After you've figured out the content you want in the diagram, you can add it to a lesson's markdown by surrounding the content with `` tags with a `class="mermaid"` ie: + +```markdown ++ +mermaid diagram content here + ++``` + +This has full support in the [Lesson Preview tool](https://www.theodinproject.com/lessons/preview), so be sure to check that the diagram renders correctly with the lesson content before contributing. + +## Markdown styling + +Markdownlint: [`no-space-in-emphasis`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md037.md), [`emphasis-style`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md049.md), [`strong-style`](https://github.com/DavidAnson/markdownlint/blob/main/doc/md050.md) + +While Markdown supports the use of both asterisks `*` and underscores `_` to make text bold or italic, asterisks should always be used. + +```markdown +**This** is how *we* do things. + +__This__ is _not_ how we do things. +``` diff --git a/README.md b/README.md index 17f7e8d897a..848565da050 100644 --- a/README.md +++ b/README.md @@ -10,18 +10,20 @@ Our community can be found on the [TOP Discord server](https://discord.gg/fbFCkY ## Contributing -The Odin Project depends on open-source contributions to improve, grow, and thrive. We welcome contributors of all experience levels and backgrounds to help maintain this awesome curriculum and community. If you would like to contribute to our curriculum, be sure to thoroughly read our [contributing guide](https://github.com/TheOdinProject/theodinproject/blob/main/CONTRIBUTING.md) in our main TOP repo. +The Odin Project depends on open-source contributions to improve, grow, and thrive. We welcome contributors of all experience levels and backgrounds to help maintain this awesome curriculum and community. If you would like to contribute to our curriculum, be sure to thoroughly read our [contributing guide](https://github.com/TheOdinProject/curriculum/blob/main/CONTRIBUTING.md). Some of the things you can do to contribute to our curriculum include: -* Correct typos and other grammar errors. -* Rewrite parts of existing lessons to make them clearer and easier to understand. -* Fix broken links. -* Add new resource links you think would make a lesson better. -* Work on entirely new lessons after getting approval. + +- Correct typos and other grammar errors. +- Rewrite parts of existing lessons to make them clearer and easier to understand. +- Fix broken links. +- Add new resource links you think would make a lesson better. +- Work on entirely new lessons after getting approval. **Happy Coding!** -\* See [license.md](https://github.com/TheOdinProject/curriculum/blob/main/license.md) for usage details. +See [license.md](https://github.com/TheOdinProject/curriculum/blob/main/license.md) for usage details. ___ -Created by [Erik Trautman](http://www.github.com/eriktrautman) + +Created by [Erik Trautman](http://www.github.com/eriktrautman). diff --git a/advanced_html_css/README.md b/advanced_html_css/README.md deleted file mode 100644 index c5fe466fb7f..00000000000 --- a/advanced_html_css/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# Advanced HTML and CSS - -This folder contains lesson markdown files that make up the Advanced HTML and CSS course. This course exists in the [Full Stack JavaScript](https://www.theodinproject.com/paths/full-stack-javascript) and the [Full Stack Ruby on Rails](https://www.theodinproject.com/paths/full-stack-ruby-on-rails) paths on the Odin Project Website. - -## Course Outline - -The following list represents how the lessons are divided into sections and presented on the website. - -**Disclaimer:** Given the ever updating nature of the curriculum, the outline might be outdated. See the [Advanced HTML and CSS course on the website](https://www.theodinproject.com/paths/full-stack-javascript/courses/advanced-html-and-css) -instead. - -### Animation - -1. [Transforms](animation/transforms.md) -2. [Transitions](animation/transitions.md) -3. [Keyframes](animation/keyframes.md) - -### Accessibility - -1. [Introduction to Web Accessibility](accessibility/introduction_to_web_accessibility.md) -2. [The Web Content Accessibility Guidelines (WCAG)](accessibility/the_web_content_accessibility_guidelines_wcag.md) -3. [Semantic HTML](accessibility/semantic_html.md) -4. [Accessible Colors](accessibility/accessible_colors.md) -5. [Keyboard Navigation](accessibility/keyboard_navigation.md) -6. [Meaningful Text](accessibility/meaningful_text.md) -7. [WAI-ARIA](accessibility/wai_aria.md) -8. [Accessibility Auditing](accessibility/accessibility_auditing.md) - -### Responsive Design - -1. [Introduction to Responsive Design](responsive_design/introduction_to_responsive_design.md) -2. [Natural Responsiveness](responsive_design/natural_responsiveness.md) -3. [Responsive Images](responsive_design/responsive_images.md) -4. [Media Queries](responsive_design/media_queries.md) -5. [**Project: Personal Portfolio**](responsive_design/project_personal_portfolio.md) \ No newline at end of file diff --git a/advanced_html_css/accessibility/accessibility_auditing.md b/advanced_html_css/accessibility/accessibility_auditing.md index b2a7ecccb1d..a9c78b732b4 100644 --- a/advanced_html_css/accessibility/accessibility_auditing.md +++ b/advanced_html_css/accessibility/accessibility_auditing.md @@ -1,51 +1,54 @@ ### Introduction -By now you should feel confident enough to start making your websites a little more accessible for a lot of users. What can really help you make sure you're implementing certain a11y features correctly, though, is learning how to view the accessibility tree in your DevTools and how to audit your web pages for any outstanding a11y issues. +Now that you are equipped with the necessary knowledge to make your websites more accessible to many users, the question arises: How can we verify the correct implementation of a11y features? Are there any mistakes to be corrected, or potential improvements to be made? In this lesson, we will answer those questions to help push your a11y skills over the top. -### Learning Outcomes -By the end of this lesson, you should be able to: +### Lesson overview -* Open the accessibility section within your browser's DevTools. -* Audit a web page with a third party auditing tool. +This section contains a general overview of topics that you will learn in this lesson. + +- Open the accessibility section within your browser's DevTools. +- Audit a web page with a third-party auditing tool. ### Accessibility DevTools Using your browser's DevTools is beyond useful for several things, from checking the styles applied to a page to debugging code, but you already know that! Here's something you may not know: you can even use the DevTools to look at various accessibility features as well, which can be great as a sort of "quick audit". You can check contrast ratios (as we mentioned in a previous lesson), view various accessibility properties, and view the accessibility tree, to name a few features. -### Accessibility Auditing +### Accessibility auditing -There are plenty of third party tools to audit the accessibility of a web page, each with their own pros and cons, though we're only going to mention three of those tools here. By getting into the habit of auditing your web pages, you'll be able to track down any outstanding a11y issues that you may have missed. If you decide to utilize one of these tools, or another auditing tool if you prefer one you come across, you should focus on fixing issues related to the concepts introduced in these lessons only for now. +There are plenty of third-party tools to audit the accessibility of a web page, each with its own pros and cons. Here, we're only going to mention three of those tools. By getting into the habit of auditing your web pages, you'll be able to track down any outstanding a11y issues that you may have missed. Whether you decide to utilize one of these tools or any other auditing tool you prefer, you should only focus on fixing issues related to the concepts introduced in this portion of the curriculum for now. -* [axe DevTools for Chrome](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US) is an extension-based tool that returns a list of issues ranked by severity level, and will note any issues for you to manually check. +- [axe DevTools for Chrome](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US) is an extension-based tool that returns a list of issues ranked by severity level, and will note any issues for you to manually check. -* [Lighthouse for Chrome](https://developers.google.com/web/tools/lighthouse) is available in the Chrome DevTools by default (it might also be listed as the Auditing tab) or it can be ran from the command line. Lighthouse provides more than just a11y auditing, including performance, best practices, search engine optimization (SEO), and progressive web app (PWA) if applicable. Any issues will be separated by category, and like the axe DevTools there may be a list of issues for you to manually check. +- [Lighthouse for Chrome](https://developers.google.com/web/tools/lighthouse) is available in the Chrome DevTools by default (it might also be listed as the Auditing tab) or it can be run from the command line. Lighthouse provides more than just a11y auditing, including performance, best practices, search engine optimization (SEO), and progressive web app (PWA) if applicable. Issues are separated by category, and like the axe DevTools, there may be a list of issues for you to manually check. -* [WebAIM's WAVE](https://wave.webaim.org/) is a website based tool where you enter the URL of the page you want to audit, though there are also browser extension and API options. WAVE will return a preview of the page with an overlay of icons on it, and issues are separated into categories of alerts, warnings, and contrast errors. Unfortunately the icons that are placed on the page may cause the layout to break, but that could be a minor issue if you're more focused on the a11y issues that are found. +- [WebAIM's WAVE](https://wave.webaim.org/) is a website-based tool where you enter the URL of the page you want to audit. There are also browser extensions and API options. WAVE will return a preview of the page with an overlay of icons on it, and issues are separated into categories of alerts, warnings, and contrast errors. Unfortunately, the icons that are placed on the page may cause the layout to break, but that could be a minor issue if you're more focused on the a11y issues that are found. -Of course, one of the best ways to check the accessibility of your websites is to get feedback from users who rely on these accessibility features. Obviously this isn't always an easy option, but when you can it will be worth hearing from those who may be affected by your site's accessibility (or lack of it). +Of course, one of the best ways to check the accessibility of your websites is to get feedback from users who rely on these accessibility features. This isn't always an easy option, but it's worth hearing from those who may be affected by your site's accessibility (or lack of it). ### Assignment+ 1. Read the following resources: - * [Accessibility features reference](https://developer.chrome.com/docs/devtools/accessibility/reference/#pane), starting from the Accessibility pane section, provides a brief overview of Chrome's accessibility features in the DevTools. - * [Emulate vision deficiencies](https://developer.chrome.com/blog/new-in-devtools-83/#vision-deficiencies) from the Chrome 83 update page. - * The [Open the Issues tab](https://developer.chrome.com/docs/devtools/issues/#open) section. You can ignore any mentions of anything that isn't accessibility related on this page, as we just want you to know how to open this tab in your DevTools. Once you do, you'll be able to see a11y issues in addition to any other issues found. - * Although there will be differences between the browsers, such as the value of the role property or how a11y properties are presented, also check out the "Features of the Accessibility panel" section mentioned below for MDN's documentation. There is some useful information that, while more tailored to Firefox, can still be useful to a Chrome user. + - [Accessibility features reference](https://developer.chrome.com/docs/devtools/accessibility/reference/#pane), starting from the Accessibility pane section, provides a brief overview of Chrome's accessibility features in the DevTools. + - The [Emulate vision deficiencies](https://developer.chrome.com/blog/new-in-devtools-83/#vision-deficiencies) section from the Chrome 83 update page. + - The [Open the Issues tab](https://developer.chrome.com/docs/devtools/issues/#open) section. You can ignore any mentions of anything that isn't accessibility-related on this page, as we just want you to know how to open this tab in your DevTools. Once you do, you'll be able to see a11y issues in addition to any other issues found. + - Although there will be differences between different browsers, such as the value of the role property or how a11y properties are presented, check out [the "Features of the Accessibility panel" section in MDN's documentation](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html#features-of-the-accessibility-panel). There is useful information that, while more tailored to Firefox, may still be useful for Chrome users. +-### Knowledge Check +### 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. +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 some of the various accessibility features available in your browser's DevTools? -* Which third party accessibility auditing tool is available in the Chrome DevTools by default? +- [What are some of the various accessibility features available in your browser's DevTools?](https://developer.chrome.com/docs/devtools/accessibility/reference/#pane) +- [Which third-party accessibility auditing tool is available in the Chrome DevTools by default?](#chrome-default-tool-knowledge-check) -### Additional Resources +### 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. -* [Involving Users in Evaluating Web Accessibility](https://www.w3.org/WAI/test-evaluate/involving-users/) goes over some helpful steps to take when you can get feedback from users. -* The [WCAG Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) provides a list of success criteria along with techniques for how to satisfy them and links to understanding them in more detail. This tool is a great go-to when you're really ready to push your website to the next accessible level. If you often use animations, success criterion 2.2.2 ("Play, Stop, Hide") and all of the 2.3 success criteria are definitely worth reading. -* [A11ycasts Playlist](https://www.youtube.com/playlist?list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g). We've included several videos from this playlist in these lessons, but there are other videos worth checking out for various accessibility topics. -* [screenreader-outputs](https://github.com/thatblindgeye/screenreader-outputs) is a GitHub repo that contains many examples of screen reader outputs. Sometimes nested elements or certain combinations of attributes and native labeling may result in accessible names or descriptions that are difficult to make sense of, so checking out this repo may help clear things up. +- [Involving Users in Evaluating Web Accessibility](https://www.w3.org/WAI/test-evaluate/involving-users/) goes over some helpful steps to take when you can get feedback from users. +- The [WCAG Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) provides a list of success criteria along with techniques for how to satisfy them and links to understanding them in more detail. This tool is a great go-to when you're really ready to push your website to the next accessible level. If you often use animations, success criterion 2.2.2 ("Play, Stop, Hide") and all of the 2.3 success criteria are definitely worth reading. +- [A11ycasts Playlist](https://www.youtube.com/playlist?list=PLNYkxOF6rcICWx0C9LVWWVqvHlYJyqw7g). We've included several videos from this playlist in these lessons, but there are other videos worth checking out for various accessibility topics. +- [screenreader-outputs](https://github.com/thatblindgeye/screenreader-outputs) is a GitHub repo that contains many examples of screen reader outputs. Sometimes nested elements or certain combinations of attributes and native labeling may result in accessible names or descriptions that are difficult to make sense of, so checking out this repo may help clear things up. diff --git a/advanced_html_css/accessibility/accessible_colors.md b/advanced_html_css/accessibility/accessible_colors.md index 2ca4bf58754..7a5efa8f775 100644 --- a/advanced_html_css/accessibility/accessible_colors.md +++ b/advanced_html_css/accessibility/accessible_colors.md @@ -2,14 +2,15 @@ Although adding color to a page can make it more visually appealing, using the wrong color combination or relying solely on color to convey information can end up making things more difficult to perceive and understand for some users. This doesn't mean you have to limit yourself when choosing color schemes for a website, but it does mean you have to take extra care when actually *using* those colors. -### Learning Outcomes -By the end of this lesson, you should be able to: +### Lesson overview -* Understand what a contrast ratio is. -* Know how to check contrast ratios. -* Understand why color alone should not be used to convey information. +This section contains a general overview of topics that you will learn in this lesson. -### Color Contrast +- Understand what a contrast ratio is. +- Know how to check contrast ratios. +- Understand why color alone should not be used to convey information. + +### Color contrast  @@ -20,21 +21,21 @@ A contrast ratio is the difference in brightnes There are two different conformance levels for contrast ratios, both of which have rules for normal text and large text. **Normal text** is defined as text with a font size that's less than 18 points/24px (or less than 14 points/18.66px for bold text), and **large text** is defined as text with a font size that is at least 18 points/24px (or at least 14 points/18.66px for bold text). 1. **Level AA** (minimum) requires a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text. -2. **Level AAA** (enhanced) requires a contrast ratio of at least 7:1 for normal text and 4.5:1 for large text. +1. **Level AAA** (enhanced) requires a contrast ratio of at least 7:1 for normal text and 4.5:1 for large text. Both conformance levels have exceptions that don't need to follow the contrast ratio rules: -* Incidental text, such as text that just *happens* to be within an image that has other significant visual content, or text that is purely decorative. -* Text that is part of an inactive or disabled user interface component, such as a button that is disabled and has a lowered opacity. -* Text that is part of a logo or brand name. +- Incidental text, such as text that just *happens* to be within an image that has other significant visual content, or text that is purely decorative. +- Text that is part of an inactive or disabled user interface component, such as a button that is disabled and has a lowered opacity. +- Text that is part of a logo or brand name. At this point you might be thinking, "18.66 pixels? 4.5:1? How the heck am I supposed to remember these numbers? Wait, how am I supposed to calculate the ratios in the first place?!" Luckily for you, you don't have to! [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) is a fantastic tool for checking contrast ratios. Just enter the HEX code of the foreground and background colors and it calculates what conformance levels, if any, the contrast ratio passes. The page also has a link for a link contrast checker, which goes over what the contrast ratio should be if a text link isn't underlined. -You can also check the contrast ratio of the text within an element using your browser's dev tools. In **Chrome**, you would click the "element picker" tool in the Elements tab, then hover over an element on the web page. If you select an element with text in the Elements tab, you can click on the color picker tool for the "color" property under Styles to view the contrast ratio as well. +You can also check the contrast ratio of the text within an element using your browser's dev tools. In **Chrome**, click the "element picker" tool in the Elements tab, then hover over an element on the web page. This displays a tooltip showing the contrast ratio under the Accessibility section. You can also view the contrast ratio by selecting an element with text in the Elements tab and clicking on the color picker tool for the "color" property in the Styles pane. -### Conveying Information +### Conveying information Now that you know to take the contrast ratio into account when adding color for text and backgrounds, let's see if you can tell which of the buttons in the image below is red: @@ -46,15 +47,16 @@ Let's look at another example. Let's say you want to create a form that has an i  -### 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. +### Knowledge check + +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 is a contrast ratio? -* What are two ways you can check a contrast ratio using your dev tools? -* What should you avoid when conveying information to users? +- [What is a contrast ratio?](#contrast-ratio) +- [What are two ways you can check a contrast ratio using your dev tools?](#dev-tools) +- [What should you avoid when conveying information to users?](#color-information) -### Additional Resources +### 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. -* [A Complete Guide to Dark Mode on the Web](https://css-tricks.com/a-complete-guide-to-dark-mode-on-the-web) from CSS-Tricks can be a great starting point for implementing a dark theme for your website. It covers different ways you can toggle a theme, how to take into account a user's preferred theme on their OS, and even saving a user's preference. Although providing a light and dark theme can be a great accessibility feature for users (not just an aesthetic preference), it can take a *lot* of work to implement, hence why it is considered an additional resource. +- [A Complete Guide to Dark Mode on the Web](https://css-tricks.com/a-complete-guide-to-dark-mode-on-the-web) from CSS-Tricks can be a great starting point for implementing a dark theme for your website. It covers different ways you can toggle a theme, how to take into account a user's preferred theme on their OS, and even saving a user's preference. Although providing a light and dark theme can be a great accessibility feature for users (not just an aesthetic preference), it can take a *lot* of work to implement, hence why it is considered an additional resource. diff --git a/advanced_html_css/accessibility/introduction_to_web_accessibility.md b/advanced_html_css/accessibility/introduction_to_web_accessibility.md index e80f4c95a15..b249e93ab88 100644 --- a/advanced_html_css/accessibility/introduction_to_web_accessibility.md +++ b/advanced_html_css/accessibility/introduction_to_web_accessibility.md @@ -4,13 +4,13 @@ At this point in the curriculum you've learned incredibly valuable concepts in w What you may not have too much an understanding of, though, is the topic of accessibility, often referred to as "a11y" (due to there being 11 letters between the first and last letters). Unfortunately, this is a topic that many people either don't know much about, or just don't take into account when developing websites. If you fit into either of those two categories, you may have adopted some habits that aren't exactly a11y friendly. Before we get into how you can break away from such habits and begin implementing a11y friendly concepts, it's important to first understand some basic information about web accessibility. -### Learning Outcomes +### 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. - Explain what web accessibility is. -### What is Web Accessibility? +### What is web accessibility? Web accessibility means that websites, tools, and technologies are designed and developed so that people with disabilities and other circumstantial limitations can use them with as few barriers as possible. @@ -18,31 +18,33 @@ There are different types of disabilities, including (but not limited to) audito Situational limitations are a little different. Using a phone outside on a bright day, browsing a site with one hand while you're busy doing something else with the other, or living in an area where the internet is slow or the bandwidth is expensive are all examples of situational limitations. These limitations, unlike a disability, occur to users only in specific situations, but are still important to keep in mind when developing a website. -### Why Web Accessibility Matters +### Why web accessibility matters Let's first look at a non-web example to gain a little perspective. Imagine being in a multi-storied building that has no elevator. For some people, this might only be an annoyance. "Huh, no elevator. I guess I'll walk up a few flights of stairs, then." A person that requires a wheelchair, however, would find it impossible, or at the very least much more difficult, to go anywhere beyond the first floor. Even if a person in a wheelchair had someone to lift the wheelchair up each step, it would be a much more difficult process. The point here is that an elevator would have made this building more accessible. -The building is your website, and the elevator is a collection of various accessibility features and tools (...it's a pretty big elevator). When you develop a website, you're developing it for users, and you need that website to actually be _usable_ by them. People with disabilities, older people with changing abilities, people who aren't as tech savvy, and people with some sort of situational limitation are still users, and websites should be as equally usable by them as possible. +The building is your website, and the elevator is a collection of various accessibility features and tools (...it's a pretty big elevator). When you develop a website, you're developing it for users, and you need that website to actually be *usable* by them. People with disabilities, older people with changing abilities, people who aren't as tech savvy, and people with some sort of situational limitation are still users, and websites should be as equally usable by them as possible. -One other pretty big reason that accessibility matters is that, depending on the country, there could actually be laws _requiring_ accessibility to be implemented. +One other pretty big reason that accessibility matters is that, depending on the country, there could actually be laws *requiring* accessibility to be implemented. ### Assignment-1. Go through [Diverse Abilities and Barriers](https://www.w3.org/WAI/people-use-web/abilities-barriers/) to get a better understanding of how some users with disabilities are affected by inaccessible sites. -2. Watch the videos on [Web Accessibility Perspectives](https://www.w3.org/WAI/perspective-videos/) to see how (and which) users can benefit from accessibility features. Each video is pretty short and has audio descriptions and transcripts. If you prefer, the page also has a link to a compiled version of all of the videos on YouTube. + +1. Go through the [Diverse Abilities and Barriers article from W3C](https://www.w3.org/WAI/people-use-web/abilities-barriers/) to get a better understanding of how some users with disabilities are affected by inaccessible sites. +1. Watch the [videos on Web Accessibility Perspectives by W3C](https://www.w3.org/WAI/perspective-videos/) to see how (and which) users can benefit from accessibility features. Each video is pretty short and has audio descriptions and transcripts. If you prefer, the page also has a link to a compiled version of all of the videos on YouTube. +-### Knowledge Check +### 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. +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 is web accessibility? -- Who truly benefits from accessibility features? +- [What is web accessibility?](#what-is-web-accessibility) +- [Who truly benefits from accessibility features?](#benefits-knowledge-check) -### Additional Resources +### 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. - [The Business Case for Digital Accessibility](https://www.w3.org/WAI/business-case/) goes over reasons for implementing accessibility beyond just being more inclusive to more users. - [How People with Disabilities Access Digital Content](https://www.youtube.com/watch?v=Lu7a5RU5lM0) is a rather long video (a whopping 45 minutes), but it goes over a lot of various assistive technologies and will offer you some more perspective on how users with disabilities may browse the websites you create. diff --git a/advanced_html_css/accessibility/keyboard_navigation.md b/advanced_html_css/accessibility/keyboard_navigation.md index 24f8f495089..0d0973ad5ab 100644 --- a/advanced_html_css/accessibility/keyboard_navigation.md +++ b/advanced_html_css/accessibility/keyboard_navigation.md @@ -2,27 +2,29 @@ Some users aren't able to use a mouse to navigate or operate their computer, and by extension the websites they visit. These users may instead rely on using a keyboard or another assistive technology that can simulate keyboard inputs, such as voice recognition software. Other users may even just prefer using a keyboard over a mouse, or may use a mix of both. These users require proper keyboard navigation, something that can easily be overlooked when developing a website. -### Learning Outcomes -By the end of this lesson, you should be able to: +### Lesson overview -* 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. -* Understand what the tab order is. -* Know how to properly hide hidden content from assistive technologies. +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. +- Understand what the tab order is. +- Know how to properly hide hidden content from assistive technologies. ### Focus Remember our Rock, Paper, Scissors example that *didn't* use semantic HTML from the... well, Semantic HTML lesson? Another issue with using `` and `` 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 -~~~ -~~~javascript +``` + +```javascript // We also need to manually add in event handling for both mouse and keyboard events. const buttons = document.querySelectorAll('.button'); @@ -36,47 +38,47 @@ 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 `-### 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. +### Knowledge check + +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? -* What are focus styles? -* Why should you never completely remove focus styles from an element? -* What is the tab order? -* What is the best way to hide hidden content from assistive technologies? +- [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 +### 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. diff --git a/advanced_html_css/accessibility/meaningful_text.md b/advanced_html_css/accessibility/meaningful_text.md index 04d7c9d635b..5dcd9c873ca 100644 --- a/advanced_html_css/accessibility/meaningful_text.md +++ b/advanced_html_css/accessibility/meaningful_text.md @@ -1,42 +1,44 @@ ### Introduction -Meaningful text is pretty straight forward: when a user reads text or has it announced to them, they should be able to immediately understand what it means even without any surrounding context. A lack of meaningful text can affect all users, but especially those who rely on assistive technologies. In this lesson we'll be going over a few instances where you should start making sure you provide meaningful text to users. +Meaningful text is pretty straightforward: when a user reads text or has it announced to them, they should be able to immediately understand what it means even without any surrounding context. A lack of meaningful text can affect all users, but especially those who rely on assistive technologies. In this lesson we'll be going over a few instances where you should start making sure you provide meaningful text to users. -### Learning Outcomes -By the end of this lesson, you should be able to: +### Lesson overview -* Know how to provide meaningful links. -* Know how to provide meaningful text in forms. -* Know how to provide meaningful `alt` attributes for images. +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 Click here to start your career in web development! Visit The Odin Project 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." When you add links to a page, there are a few rules you should be following: 1. Make sure that the text content of the `` 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 2021 Sign Up Statistics (PDF, 1MB) GitHub (opens in new tab) -~~~ +``` 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! @@ -44,7 +46,7 @@ The next time you need to use links, try saying the contents of the element out 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 +```htmlError: Invalid input.@@ -53,7 +55,7 @@ Providing meaningful errors to users when they are filling out or submitting a fError: 'JohnSmith@@test.com' is not valid. Example of a valid email: example@yourdomain.com.-~~~ +``` 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. @@ -63,32 +65,41 @@ The error in Example 3 is even more meaningful. It not only tells you what input Another way to provide meaningful text in forms is with instructions, such as when a password input lists any characters that the password must contain ("Must include at least one uppercase letter and one number..."). For instructions that are unique to an input, they should be placed alongside the input itself. Instructions that are more global across the form, such as indicating which inputs are required, should either be placed at the top of the form ("* indicates a required field"), or placed alongside the input or its label ("Name (required)"). -### Alternative Text +### Alternative text 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
+ + 1. 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. -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. 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. 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 simply 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 -### 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. +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? -* What information should you inform users of in order to provide meaningful error messages in forms? -* When should you use the empty string/null value for the `alt` attribute? +- [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 +### 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. diff --git a/advanced_html_css/accessibility/semantic_html.md b/advanced_html_css/accessibility/semantic_html.md index 89f546b558e..1a74fe65d2e 100644 --- a/advanced_html_css/accessibility/semantic_html.md +++ b/advanced_html_css/accessibility/semantic_html.md @@ -2,53 +2,54 @@ As useful as `` and `` elements can be as generic containers, they're not always the most a11y friendly elements to use. While it may be tempting or easier to just use them for everything, from containers to interactive areas, you should not only check whether there is a more appropriate element to use in certain situations, but also whether you're using an element correctly. -### Learning Outcomes -By the end of this lesson, you should be able to: +### Lesson overview -* Explain why semantic HTML is important for accessibility. -* Name the seven HTML elements that define landmarks on a page. +This section contains a general overview of topics that you will learn in this lesson. -### The Importance of Semantics +- Explain why semantic HTML is important for accessibility. +- Name the seven HTML elements that define landmarks on a page. -In terms of web accessibility, using semantic HTML is important because it provides meaning and context. Some elements have a *semantic meaning*, but don't really provide any *context* when announced by assistive technologies, such as the `` element. Then there are elements that have a semantic meaning *and* are announced with some sort of context to help users perceive or operate them, like a `