Update course format for accessibility (skills#18)

* Update course format for accessibility

* outline step files

* More automatic fixes

* Manual fixes

* manual fixes

* manual fixes

* manual fixes

Author: heiskr

.github/script/STEP renamed to .github/steps/-step.txt

@@ -0,0 +1 @@
+<!-- readme -->

.github/steps/0-welcome.md

@@ -0,0 +1,20 @@
+<!--
+  <<< Author notes: Step 1 >>>
+  Choose 3-5 steps for your course.
+  The first step is always the hardest, so pick something easy!
+  Link to docs.github.com for further explanations.
+  Encourage users to open new tabs for steps!
+-->
+
+## Step 1: Create a pull request
+
+_Welcome to "Managing Merge Conflicts"! :wave:_
+
+**What is a _merge conflict_?**: A **merge conflict** occurs when changes are made to the same part of the same file on two different branches. You usually find out about conflicts in a pull request so let's start by creating one.
+
+### :keyboard: Activity: Create a pull request
+
+1. Open a new browser tab, and work on the steps in your second tab while you read the instructions in this tab.
+1. We made a small change to a file in the repository in the `my-resume` branch.
+1. [Create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) setting `my-resume` as the head branch and `main` as the base branch. You can enter `Resolving merge conflicts` for the pull request title and body.
+1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.

.github/steps/1-create-a-pr.md

@@ -0,0 +1,27 @@
+<!--
+  <<< Author notes: Step 2 >>>
+  Start this step by acknowledging the previous step.
+  Define terms and link to docs.github.com.
+-->
+
+## Step 2: Resolve a merge conflict
+
+_Good start! Now let's look deeper at a merge conflict! :mag:_
+
+This can be intimidating, but have no fear, Git is smart when it comes to merging! Git only needs a human to decide how to [resolve the conflict](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line). Sometimes, the best way to resolve a merge conflict is to add content that's from both branches, or even something that isn't on either! This is why Git needs a human to look at the code and make the proper fixes.
+
+### :keyboard: Activity: Resolve a merge conflict
+
+1. Open the pull request that you just created, we created a conflict for you. Have no fear!
+1. At the bottom of the page, under "This branch has conflicts that must be resolved", click the **Resolve conflicts** button.
+1. Look for the highlighted sections that begins with `<<<<<<< my-resume` and ends with `>>>>>>> main`. These markers are added by Git to show you the content that is in conflict.
+1. Remove the changes made on the main branch by deleting all of the content below the `=======` and above `>>>>>>> main`.
+1. Next, remove the merge conflict markers by deleting the following lines:
+   ```
+   <<<<<<< my-resume
+   =======
+   >>>>>>> main
+   ```
+1. With the merge conflict markers removed, click **Mark as resolved**.
+1. Finally, click **Commit merge**.
+1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.

.github/steps/2-resolve-a-merge-conflict.md

@@ -0,0 +1,25 @@
+<!--
+  <<< Author notes: Step 3 >>>
+  Start this step by acknowledging the previous step.
+  Define terms and link to docs.github.com.
+-->
+
+## Step 3: Create your own conflict
+
+_Good job! You've solved a merge conflict! :tada:_
+
+Resolving a conflict doesn't automatically merge the pull request in GitHub. Instead, it stores the resolution of the conflict in a merge commit and allows you and your team to keep working. To resolve a conflict, GitHub performs what is known as a _reverse merge_. This means that the changes from the `main` branch were merged into your `my-resume` branch. With a reverse merge, only the `my-resume` branch is updated. This allows you to test the resolved changes on your branch before you merge it into `main`.
+
+Now, let's get a little evil. (It's for educational purposes!)
+
+### :keyboard: Activity: Create your own conflict
+
+We went ahead and added a new file called `references.md` and pushed that change to `main`, without updating your `my-resume` branch.
+
+1. Browse to the `my-resume` branch.
+1. Click the `Add file` dropdown menu and then on `Create new file`.
+1. Create a file named `references.md`.
+1. Enter some text that conflicts with what we added for `references.md` in the `main` branch.
+1. Scroll to the bottom of the page and enter a commit message for your change.
+1. Click the **Commit new file** button, making sure the "Commit directly to the `my-resume` branch" option is selected.
+1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.

.github/steps/3-create-your-own-conflict.md

@@ -0,0 +1,19 @@
+<!--
+  <<< Author notes: Step 4 >>>
+  Start this step by acknowledging the previous step.
+  Define terms and link to docs.github.com.
+-->
+
+## Step 4: Merge your pull request
+
+_Almost there! :heart:_
+
+You can now [merge](https://docs.github.com/en/get-started/quickstart/github-glossary#merge) your pull request!
+
+### :keyboard: Activity: Merge your pull request
+
+1. First, resolve any remaining conflicts in your pull request.
+   > Look back at step one if you need help.
+1. Click **Merge pull request**.
+1. Delete the branch `my-resume` (optional).
+1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.

.github/steps/4-merge-your-pull-request.md

@@ -0,0 +1,24 @@
+<!--
+  <<< Author notes: Finish >>>
+  Review what we learned, ask for feedback, provide next steps.
+-->
+
+## Finish
+
+_Congratulations friend, you've completed this course!_
+
+<img src=https://octodex.github.com/images/benevocats.jpg alt=celebrate width=300 align=right>
+
+Here's a recap of all the tasks you've accomplished in your repository:
+
+- You learned why merge conflicts happen.
+- You resolved a simple merge conflict.
+- You created a merge conflict, and resolved it!
+
+### What's next?
+
+- Make your own Markdown resume site with GitHub Pages! Learn how in our [GitHub Pages](https://github.com/skills/github-pages) course.
+- We'd love to hear what you thought of this course [in our discussion board](https://github.com/skills/.github/discussions).
+- [Take another GitHub Skills course](https://github.com/skills).
+- [Read the GitHub Getting Started docs](https://docs.github.com/en/get-started).
+- To find projects to contribute to, check out [GitHub Explore](https://github.com/explore).

.github/steps/X-finish.md

@@ -1,26 +1,24 @@
-name: Step 0, Start
+name: Step 0, Welcome
 
-# This step triggers after the learner creates a new repository from the template
-# This step sets STEP to 1
-# This step closes <details id=0> and opens <details id=1>
+# This step triggers after the learner creates a new repository from the template.
+# This workflow updates from step 0 to step 1.
 
-# This will run every time we create push a commit to `main`
-# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# This will run every time we create push a commit to `main`.
+# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
 on:
   workflow_dispatch:
   push:
     branches:
       - main
 
-# Reference https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+# Reference: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
 permissions:
-  # Need `contents: read` to checkout the repository
-  # Need `contents: write` to update the step metadata
+  # Need `contents: read` to checkout the repository.
+  # Need `contents: write` to update the step metadata.
   contents: write
 
 jobs:
-  # Get the current step from .github/script/STEP so we can
-  # limit running the main job when the learner is on the same step.
+  # Get the current step to only run the main job when the learner is on the same step.
   get_current_step:
     name: Check current step number
     runs-on: ubuntu-latest
@@ -29,7 +27,7 @@ jobs:
         uses: actions/checkout@v3
       - id: get_step
         run: |
-          echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT
+          echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT
     outputs:
       current_step: ${{ steps.get_step.outputs.current_step }}
 
@@ -38,28 +36,28 @@ jobs:
     needs: get_current_step
 
     # We will only run this action when:
-    # 1. This repository isn't the template repository
-    # 2. The STEP is currently 0
-    # Reference https://docs.github.com/en/actions/learn-github-actions/contexts
-    # Reference https://docs.github.com/en/actions/learn-github-actions/expressions
+    # 1. This repository isn't the template repository.
+    # 2. The step is currently 0.
+    # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts
+    # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions
     if: >-
       ${{ !github.event.repository.is_template
           && needs.get_current_step.outputs.current_step == 0 }}
 
-    # We'll run Ubuntu for performance instead of Mac or Windows
+    # We'll run Ubuntu for performance instead of Mac or Windows.
     runs-on: ubuntu-latest
 
     steps:
-      # We'll need to check out the repository so that we can edit the README
+      # We'll need to check out the repository so that we can edit the README.
       - name: Checkout
         uses: actions/checkout@v3
         with:
-          fetch-depth: 0 # Let's get all the branches
+          fetch-depth: 0 # Let's get all the branches.
 
       - name: Prepare a branch
         run: |
           echo "Make sure we are on step 0"
-          if [ "$(cat .github/script/STEP)" != 0 ]
+          if [ "$(cat .github/steps/-step.txt)" != 0 ]
           then
             echo "Current step is not 0"
             exit 0
@@ -83,10 +81,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      # Update README to close <details id=0> and open <details id=1>
-      # and set STEP to '1'
+      # In README.md, switch step 0 for step 1.
       - name: Update to step 1
-        uses: skills/action-update-step@v1
+        uses: skills/action-update-step@v2
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           from_step: 0

.github/workflows/0-start.yml renamed to .github/workflows/0-welcome.yml

@@ -1,25 +1,23 @@
-name: Step 1, Create a pull request 
+name: Step 1, Create a pull request
 
 # This step triggers after the learner creates a pull request for the my-resume branch
-# This step sets STEP to 2
-# This step closes <details id=1> and opens <details id=2>
+# This workflow updates from step 1 to step 2.
 
-# This will run every time we open a pull request
-# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# This will run every time we open a pull request.
+# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
 on:
   workflow_dispatch:
   pull_request:
     types: [opened]
 
-# Reference https://docs.github.com/en/actions/security-guides/automatic-token-authentication
+# Reference: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
 permissions:
-  # Need `contents: read` to checkout the repository
-  # Need `contents: write` to update the step metadata
+  # Need `contents: read` to checkout the repository.
+  # Need `contents: write` to update the step metadata.
   contents: write
 
 jobs:
-  # Get the current step from .github/script/STEP so we can
-  # limit running the main job when the learner is on the same step.
+  # Get the current step to only run the main job when the learner is on the same step.
   get_current_step:
     name: Check current step number
     runs-on: ubuntu-latest
@@ -28,49 +26,49 @@ jobs:
         uses: actions/checkout@v3
       - id: get_step
         run: |
-          echo "current_step=$(cat ./.github/script/STEP)" >> $GITHUB_OUTPUT
+          echo "current_step=$(cat ./.github/steps/-step.txt)" >> $GITHUB_OUTPUT
     outputs:
       current_step: ${{ steps.get_step.outputs.current_step }}
 
   on_create_pr:
-    name: On create PR 
+    name: On create PR
     needs: get_current_step
 
     # We will only run this action when:
-    # 1. This repository isn't the template repository
-    # 2. The STEP is currently 1
-    # Reference https://docs.github.com/en/actions/learn-github-actions/contexts
-    # Reference https://docs.github.com/en/actions/learn-github-actions/expressions
+    # 1. This repository isn't the template repository.
+    # 2. The step is currently 1.
+    # Reference: https://docs.github.com/en/actions/learn-github-actions/contexts
+    # Reference: https://docs.github.com/en/actions/learn-github-actions/expressions
     if: >-
       ${{ !github.event.repository.is_template
           && needs.get_current_step.outputs.current_step == 1 }}
 
-    # We'll run Ubuntu for performance instead of Mac or Windows
+    # We'll run Ubuntu for performance instead of Mac or Windows.
     runs-on: ubuntu-latest
 
     steps:
-      # We'll need to check out the repository so that we can edit the README
+      # We'll need to check out the repository so that we can edit the README.
       - name: Checkout
         uses: actions/checkout@v3
         with:
-          fetch-depth: 0 # Let's get all the branches
+          fetch-depth: 0 # Let's get all the branches.
 
       - name: Prepare a merge conflict
         run: |
           echo "Make sure we are on step 1"
-          if [ "$(cat .github/script/STEP)" != 1 ]
+          if [ "$(cat .github/steps/-step.txt)" != 1 ]
           then
             echo "Current step is not 1"
             exit 0
           fi
 
-          echo "Manually update STEP in my-resume to match STEP in main branch"
+          echo "Manually update step in my-resume to match step in main branch"
           git checkout my-resume
           git config user.name github-actions
           git config user.email [email protected]
-          sed -i.bak 's/1/2/' .github/script/STEP
-          git add .github/script/STEP
-          git commit --message="Update STEP in my-resume"
+          sed -i.bak 's/1/2/' .github/steps/-step.txt
+          git add .github/steps/-step.txt
+          git commit --message="Update step in my-resume"
           echo "Push"
           git push origin my-resume
 
@@ -85,10 +83,9 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      # Update README to close <details id=1> and open <details id=2>
-      # and set STEP to '2'
+      # In README.md, switch step 1 for step 2.
       - name: Update to step 2
-        uses: skills/action-update-step@v1
+        uses: skills/action-update-step@v2
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           from_step: 1