Update course format for accessibility

skills · May 30, 2023 · 1c320f4 · 1c320f4
1 parent 4fe698c
commit 1c320f4
Show file tree

Hide file tree

Showing 8 changed files with 66 additions and 72 deletions.
diff --git a/.github/script/STEP → .github/steps/-step.txt b/.github/script/STEP → .github/steps/-step.txt
diff --git a/.github/steps/0-welcome.md b/.github/steps/0-welcome.md
@@ -0,0 +1 @@
+<!-- readme -->
diff --git a/.github/workflows/0-start.yml → .github/workflows/0-welcome.yml b/.github/workflows/0-start.yml → .github/workflows/0-welcome.yml
@@ -1,23 +1,22 @@
-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 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
+# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
 on:
  create:
  workflow_dispatch:
 
-# 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
  contents: write
 
 jobs:
- # Get the current step from .github/script/STEP so we can
+ # Get the current step from .github/steps/-step.txt so we can
  # limit running the main job when the learner is on the same step.
  get_current_step:
  name: Check current step number
@@ -27,7 +26,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 }}
 
@@ -37,9 +36,9 @@ jobs:
 
  # 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
+ # 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}}
@@ -54,10 +53,9 @@ jobs:
  with:
  fetch-depth: 0 # Let's get all the branches
 
- # Update README to close <details id=0> and open <details id=1>
- # and set STEP to '1'
- - name: Update to step 1
- uses: skills/action-update-step@v1
+ # In README.md, switch step 0 for step 1.
+ - name: Update to step 1
+ uses: skills/action-update-step@v2
  with:
  token: ${{ secrets.GITHUB_TOKEN }}
  from_step: 0

diff --git a/.github/workflows/1-first-codespace.yml b/.github/workflows/1-first-codespace.yml
@@ -1,25 +1,24 @@
 name: Step 1, 1-Create codespace and push code
 
 # This step triggers after push to main
-# 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 push to main
-# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# 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
  contents: write
 
 jobs:
- # Get the current step from .github/script/STEP so we can
+ # Get the current step from .github/steps/-step.txt so we can
  # limit running the main job when the learner is on the same step.
  get_current_step:
  name: Check current step number
@@ -29,7 +28,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 }}
 
@@ -39,9 +38,9 @@ jobs:
 
  # 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
+ # 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 }}
@@ -65,10 +64,9 @@ jobs:
  FILE: "index.html"
  SEARCH: "Hello from the codespace"
 
- # Update README to close <details id=1> and open <details id=2>
- # and set STEP to '2'
- - name: Update to step 2
- uses: skills/action-update-step@v1
+ # In README.md, switch step 1 for step 2.
+ - name: Update to step 2
+ uses: skills/action-update-step@v2
  with:
  token: ${{ secrets.GITHUB_TOKEN }}
  from_step: 1

diff --git a/.github/workflows/2-custom-image.yml b/.github/workflows/2-custom-image.yml
@@ -1,25 +1,24 @@
 name: Step 2, 2-custom image check
 
 # This step triggers after First Codespace
-# This step sets STEP to 3
-# This step closes <details id=2> and opens <details id=3>
+# This workflow updates from step 2 to step 3.
 
 # This will run every time we push to main
-# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# 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
  contents: write
 
 jobs:
- # Get the current step from .github/script/STEP so we can
+ # Get the current step from .github/steps/-step.txt so we can
  # limit running the main job when the learner is on the same step.
  get_current_step:
  name: Check current step number
@@ -29,7 +28,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 }}
 
@@ -39,9 +38,9 @@ jobs:
 
  # We will only run this action when:
  # 1. This repository isn't the template repository
- # 2. The STEP is currently 2
- # Reference https://docs.github.com/en/actions/learn-github-actions/contexts
- # Reference https://docs.github.com/en/actions/learn-github-actions/expressions
+ # 2. The step is currently 2
+ # 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 == 2 }}
@@ -65,10 +64,9 @@ jobs:
  FILE: ".devcontainer/devcontainer.json"
  SEARCH: "mcr.microsoft.com/vscode/devcontainers/universal:latest"
 
- # Update README to close <details id=2> and open <details id=3>
- # and set STEP to '3'
- - name: Update to step 3
- uses: skills/action-update-step@v1
+ # In README.md, switch step 2 for step 3.
+ - name: Update to step 3
+ uses: skills/action-update-step@v2
  with:
  token: ${{ secrets.GITHUB_TOKEN }}
  from_step: 2

diff --git a/.github/workflows/3-customize-codespace.yml b/.github/workflows/3-customize-codespace.yml
@@ -1,25 +1,24 @@
 name: Step 3, 3-Customize Codespace
 
 # This step triggers after we push to main
-# This step sets STEP to 4
-# This step closes <details id=3> and opens <details id=4>
+# This workflow updates from step 3 to step 4.
 
 # This will run every time
-# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# 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
  contents: write
 
 jobs:
- # Get the current step from .github/script/STEP so we can
+ # Get the current step from .github/steps/-step.txt so we can
  # limit running the main job when the learner is on the same step.
  get_current_step:
  name: Check current step number
@@ -29,7 +28,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 }}
 
@@ -39,9 +38,9 @@ jobs:
 
  # We will only run this action when:
  # 1. This repository isn't the template repository
- # 2. The STEP is currently 3
- # Reference https://docs.github.com/en/actions/learn-github-actions/contexts
- # Reference https://docs.github.com/en/actions/learn-github-actions/expressions
+ # 2. The step is currently 3
+ # 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 == 3 }}
@@ -65,10 +64,9 @@ jobs:
  FILE: ".devcontainer/devcontainer.json"
  SEARCH: "postCreateCommand"
 
- # Update README to close <details id=3> and open <details id=4>
- # and set STEP to '4'
- - name: Update to step 4
- uses: skills/action-update-step@v1
+ # In README.md, switch step 3 for step 4.
+ - name: Update to step 4
+ uses: skills/action-update-step@v2
  with:
  token: ${{ secrets.GITHUB_TOKEN }}
  from_step: 3

diff --git a/.github/workflows/4-personalize-codespace.yml b/.github/workflows/4-personalize-codespace.yml
@@ -1,11 +1,10 @@
 name: Step 4, 4-Personalize your Codespace
 
 # This step triggers after push to main#setup.sh
-# This step sets STEP to X
-# This step closes <details id=4> and opens <details X>
+# This workflow updates from step 4 to step X.
 
 # This will run every time we push to main#setup.sh
-# Reference https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
+# Reference: https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows
 on:
  workflow_dispatch:
  push:
@@ -14,14 +13,14 @@ on:
  paths:
  - 'setup.sh'
 
-# 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
  contents: write
 
 jobs:
- # Get the current step from .github/script/STEP so we can
+ # Get the current step from .github/steps/-step.txt so we can
  # limit running the main job when the learner is on the same step.
  get_current_step:
  name: Check current step number
@@ -31,7 +30,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 }}
 
@@ -41,9 +40,9 @@ jobs:
 
  # We will only run this action when:
  # 1. This repository isn't the template repository
- # 2. The STEP is currently 4
- # Reference https://docs.github.com/en/actions/learn-github-actions/contexts
- # Reference https://docs.github.com/en/actions/learn-github-actions/expressions
+ # 2. The step is currently 4
+ # 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 == 4}}
@@ -67,10 +66,9 @@ jobs:
  FILE: "setup.sh"
  SEARCH: "install sl"
 
- # Update README to close <details id=4> and open <details id=X>
- # and set STEP to 'X'
- - name: Update to step X
- uses: skills/action-update-step@v1
+ # In README.md, switch step 4 for step X.
+ - name: Update to step X
+ uses: skills/action-update-step@v2
  with:
  token: ${{ secrets.GITHUB_TOKEN }}
  from_step: 4

diff --git a/README.md b/README.md
@@ -12,12 +12,9 @@
 _Create workflows that enable you to use Continuous Integration (CI) for your projects._
 
 <!--
- <<< Author notes: Start of the course >>>
+ <<< Author notes: Course start >>>
  Include start button, a note about Actions minutes,
  and tell the learner why they should take the course.
- Each step should be wrapped in <details>/<summary>, with an `id` set.
- The start <details> should have `open` as well.
- Do not use quotes on the <details> tag attributes.
 -->
 
 <details id=0 open>
@@ -29,9 +26,15 @@ GitHub Codespaces is a development environment that's hosted in the cloud.
 - **What you'll learn**: How to create a codespace, push code from a codespace, select a custom image, and customize a codespace.
 - **What you'll build**: A codespace with devcontainer.json files, customizations, and personalizations.
 - **Prerequisites**: If you need to learn about Visual Studio Code, read [Visual Studio Code Docs](https://code.visualstudio.com/docs) first.
-- **How long**: This course is four steps long and can be completed in less than an hour.
+- **How long**: This course can be completed in less than an hour.
 
-## How to start this course
+In this course, you will:
+
+1.
+2.
+3.
+
+### How to start this course
 
 <!-- For start course, run in JavaScript:
 'https://github.com/new?' + new URLSearchParams({