Diagrams: plain text descriptions with clean Mermaid, tables to prose

Author: taylorarndt

docs/01-understanding-github-web-structure.md

@@ -194,24 +194,10 @@ Your personal home (`github.com`) shows activity from repositories you follow. Y
 
 ## 5. Visual Map of a Repository Page
 
-This diagram shows the layout of a repository home page, from top to bottom:
-
-1. **Global Navigation** (landmark: "Navigation Menu") — GitHub logo, Search, Copilot, Pull Requests, Issues, Notifications bell, and your avatar.
-2. **Repository Tabs** (landmark: "Repository navigation") — Code, Issues (12), Pull requests (3), Actions, and more.
-3. **Repository Header** — The H1 heading "owner / repo-name" plus Star (42), Watch, and Fork (8) buttons.
-4. **Main content area** split into two columns:
-   - **Left: File Area** — Branch selector (main), Go to file button, Code button, and the File Table (a landmark) listing files like .github/, docs/, README.md with dates.
-   - **Right: Sidebar** — About section, description text, topics (accessibility), Releases (3), Contributors (5), Languages (Markdown 100%).
-5. **README** (landmark: "Repository files navigation") — The rendered README content.
-6. **Footer**
-
-<details>
-<summary>Visual diagram (Mermaid)</summary>
+A repository home page is laid out from top to bottom as follows. The Global Navigation bar (landmark: "Navigation Menu") contains the GitHub logo, Search, Copilot, Pull Requests, Issues, Notifications bell, and your avatar. Below that are the Repository Tabs (landmark: "Repository navigation") showing Code, Issues (12), Pull requests (3), Actions, and more. Next is the Repository Header, which is the H1 heading "owner / repo-name" plus Star (42), Watch, and Fork (8) buttons. The main content area is split into two columns. On the left is the File Area with the branch selector (main), Go to file button, Code button, and the File Table (a landmark) listing files like .github/, docs/, and README.md with dates. On the right is the Sidebar with the About section, description text, topics (accessibility), Releases (3), Contributors (5), and Languages (Markdown 100%). Below both columns is the rendered README (landmark: "Repository files navigation"), and at the bottom is the Footer.
 
 ```mermaid
 graph TD
-    accTitle: Repository page layout
-    accDescr: A GitHub repository page has a global navigation bar at top, then repository tabs, the repository header with star/watch/fork, a two-column layout with file area on left and sidebar on right, the rendered README below, and a footer.
     NAV["Global Navigation\nGitHub, Search, Copilot, PRs, Issues, Bell, You"]
     NAV --> TABS["Repository Tabs\nCode, Issues 12, Pull requests 3, Actions"]
     TABS --> HEADER["Repository Header\nowner / repo-name (H1)\nStar 42, Watch, Fork 8"]
@@ -222,14 +208,9 @@ graph TD
     README --> FOOTER["Footer"]
 ```
 
-</details>
-
 ### Screen reader navigation of this page
 
-- `1` → hear "owner/repo-name" (the H1, confirms you are on the right repo)
-- `D` → "Navigation Menu" → `D` → "Repository navigation" → `D` → "Main" (file tree area)
-- `T` → jump to the file table → `Ctrl+Alt+Down Arrow` to navigate rows
-- `D` → "Repository files navigation" → read the README
+Press 1 to hear "owner/repo-name" (the H1, confirms you are on the right repo). Press D to hear "Navigation Menu," then D again for "Repository navigation," then D again for "Main" (the file tree area). Press T to jump to the file table, then Ctrl+Alt+Down Arrow to navigate rows. Press D again to reach "Repository files navigation" and read the README.
 
 
 ## 6. Screen Reader Orientation Sequence

docs/02-navigating-repositories.md

@@ -29,23 +29,10 @@ Use this sequence before moving to graded chapters:
 
 When you navigate to a GitHub repository (e.g., `https://github.com/owner/repo-name`), you land on the **repository home page** (also called the Code tab). This page has several distinct regions:
 
-The repository home page is organized into these regions, from top to bottom:
-
-1. **Navigation bar** (GitHub global nav) — avatar menu, Notifications, search.
-2. **Repository header** — "owner / repo-name" as the H1 heading, plus Star, Watch, and Fork buttons.
-3. **Repository navigation tabs** (landmark) — Code (active), Issues, Pull requests, Actions, and more.
-4. **Main content area** split into two columns:
-   - **Left: File tree / code panel** — Branch selector, Files table (navigable as a table), last commit message.
-   - **Right: Sidebar** — About section, topics, releases.
-5. **README.md** (rendered) — A separate landmark region below the file tree.
-
-<details>
-<summary>Visual diagram (Mermaid)</summary>
+The repository home page is organized from top to bottom as follows. The Navigation bar (GitHub global nav) contains the avatar menu, Notifications, and search. Below that is the Repository header showing "owner / repo-name" as the H1 heading, plus Star, Watch, and Fork buttons. Next are the Repository navigation tabs (a landmark) with Code (active), Issues, Pull requests, Actions, and more. The main content area is split into two columns: on the left is the File tree / code panel with the branch selector, Files table (navigable as a table), and last commit message; on the right is the Sidebar with the About section, topics, and releases. Below both columns is the rendered README.md in a separate landmark region.
 
 ```mermaid
 graph TD
-    accTitle: Repository page layout
-    accDescr: A repository page has a navigation bar at top, then the repository header, navigation tabs, a two-column area with file tree on the left and sidebar on the right, and the rendered README below.
     NAV["Navigation bar\navatar menu, Notifications, search"]
     NAV --> HEADER["Repository header\nowner / repo-name (H1)\nStar, Watch, Fork"]
     HEADER --> TABS["Repository navigation tabs\nCode, Issues, Pull requests, Actions"]
@@ -55,8 +42,6 @@ graph TD
     SIDEBAR --> README
 ```
 
-</details>
-
 
 ## Landing on a Repository - What to Expect
 

docs/03-the-learning-room.md

@@ -25,13 +25,8 @@ Before starting Chapter 4 challenges, students should be able to:
 
 The learning-room is a single shared repository. It has a protected main branch, and each student opens pull requests against it. For example: Student A's PR #12 is open and assigned to Student B for review, Student B's PR #13 is assigned to Student C, Student C's PR #14 is assigned to Student A, and Student A's earlier PR #11 has already been merged. More PRs appear as students contribute.
 
-<details>
-<summary>Visual diagram (Mermaid)</summary>
-
 ```mermaid
 graph TD
-    accTitle: Learning room branch structure
-    accDescr: The shared learning-room repository has a protected main branch. Students open pull requests assigned to each other for peer review. Merged PRs are closed.
     LR["learning-room (SHARED)"]
     LR --> MAIN["main branch (protected)"]
     LR --> PR12["Student A's PR #12\nopen, assigned to Student B for review"]
@@ -41,8 +36,6 @@ graph TD
     LR --> MORE["More PRs as students contribute"]
 ```
 
-</details>
-
 ### Why one shared repo?
 
 - **Realistic** - Open source projects are shared spaces

docs/12-github-pull-requests-extension.md

@@ -192,13 +192,8 @@ gh pr list --search "review-requested:@me"
 
 The GitHub Pull Requests panel has two top-level sections. "My Pull Requests" contains four filters: Assigned to Me, Created by Me, Waiting for my Review, and All Open. The repository section shows Local Pull Request Branches (checked out locally), All Open Pull Requests, and All Closed Pull Requests.
 
-<details>
-<summary>Visual diagram (Mermaid)</summary>
-
 ```mermaid
 graph TD
-    accTitle: GitHub Pull Requests panel tree structure
-    accDescr: The panel has two sections. My Pull Requests contains Assigned to Me, Created by Me, Waiting for my Review, and All Open. The Repository section shows Local Branches, All Open, and All Closed.
     ROOT["GitHub Pull Requests"]
     ROOT --> MY["My Pull Requests"]
     MY --> ASSIGNED["Assigned to Me"]
@@ -211,8 +206,6 @@ graph TD
     REPO --> CLOSED["All Closed Pull Requests"]
 ```
 
-</details>
-
 #### Screen reader announcement example
 
 "Pull Request #42: Add Timeline Guide, opened by jeffb, 2 days ago, 3 files changed"

docs/15-issue-templates.md

@@ -195,13 +195,8 @@ Templates live in a specific folder in your repository:
 
 Templates live inside your-repo/.github/. The ISSUE_TEMPLATE/ subfolder contains: bug_report.md (Markdown template), feature_request.md (Markdown template), accessibility-bug.yml (YAML form template), and config.yml (template chooser configuration). The pull_request_template.md file sits directly in .github/, not inside ISSUE_TEMPLATE/.
 
-<details>
-<summary>Visual diagram (Mermaid)</summary>
-
 ```mermaid
 graph TD
-    accTitle: Issue template folder structure
-    accDescr: Templates live in your-repo/.github/. The ISSUE_TEMPLATE subfolder has bug_report.md, feature_request.md, accessibility-bug.yml, and config.yml. The pull_request_template.md sits directly in .github/.
     REPO["your-repo/"]
     REPO --> GH[".github/"]
     GH --> IT["ISSUE_TEMPLATE/"]
@@ -212,8 +207,6 @@ graph TD
     GH --> PRT["pull_request_template.md\nPR template (singular)"]
 ```
 
-</details>
-
 **Markdown templates (`.md`):** Traditional template format. Pre-fills a text editor with structured Markdown content. Contributors edit the template directly, replacing instructions and placeholder text with their own content.
 
 **YAML form templates (`.yml`):** Modern form-based templates. Creates a proper form interface with labeled fields, dropdowns, checkboxes, and validation. Contributors fill in fields rather than editing freeform Markdown. Better for accessibility because each field has an explicit label announced by screen readers.

docs/appendix-i-github-projects.md

@@ -27,14 +27,17 @@
 
 GitHub has two generations of project tooling. The current generation - called **Projects (v2)** - is what you'll find on any repository or organization page today.
 
-| Feature | Classic Projects (v1) | Projects v2 (current) |
-| ---  | ---  | ---  |
-| Layouts | Kanban board only | Board, Table, Roadmap |
-| Custom fields | None | Text, Number, Date, Select, Iteration |
-| Automations | None built-in | Native GitHub Actions integration |
-| Cross-repo | No | Yes |
-| Filtering | Limited | Full field/label/assignee/status queries |
-| API | Limited | Full GraphQL support |
+**Layouts:** Classic v1 offered Kanban board only. V2 offers Board, Table, and Roadmap.
+
+**Custom fields:** Classic v1 had none. V2 supports Text, Number, Date, Single Select, and Iteration fields.
+
+**Automations:** Classic v1 had no built-in automations. V2 has native GitHub Actions integration.
+
+**Cross-repo support:** Classic v1 did not support cross-repository tracking. V2 does.
+
+**Filtering:** Classic v1 had limited filtering. V2 supports full field, label, assignee, and status queries.
+
+**API:** Classic v1 had a limited API. V2 has full GraphQL support.
 
 If you see "Projects (Beta)" references in older documentation, those referred to the early rollout of v2. It is now stable and the default.
 
@@ -143,13 +146,15 @@ This is one of Projects v2's most powerful features. You can add fields beyond t
 
 ### Field Types
 
-| Type | Use Case | Example |
-| ---  | ---  | ---  |
-| **Text** | Free-form notes | "Acceptance criteria", "Design link" |
-| **Number** | Story points, estimates | "Points: 3" |
-| **Date** | Deadlines, start dates | "Due: 2025-06-15" |
-| **Single select** | Priority, size, type | Priority: P0 / P1 / P2 |
-| **Iteration** | Sprint/cycle tracking | See Section 7 |
+**Text:** Free-form notes for things like acceptance criteria or design links.
+
+**Number:** Numeric values such as story points or estimates (for example, "Points: 3").
+
+**Date:** Deadlines or start dates (for example, "Due: 2025-06-15").
+
+**Single select:** A dropdown with predefined options, useful for priority, size, or type fields (for example, Priority: P0, P1, or P2).
+
+**Iteration:** Sprint or cycle tracking. See Section 7 for details.
 
 ### Creating a Custom Field
 
@@ -234,13 +239,15 @@ From a project:
 
 ### Available Built-In Workflows
 
-| Workflow | What It Does |
-| ---  | ---  |
-| **Item added to project** | When an item is manually added, set its Status to a chosen value |
-| **Item reopened** | When an issue/PR is reopened, change its Status (e.g., back to "In Progress") |
-| **Item closed** | When an issue/PR is closed, set Status to "Done" automatically |
-| **Pull request merged** | When a PR is merged, set its Status to "Done" |
-| **Auto-add to project** | Items matching a filter (by label, type, repo) are automatically added to the project |
+**Item added to project:** When an item is manually added, its Status is set to a value you choose.
+
+**Item reopened:** When an issue or pull request is reopened, its Status changes back (for example, to "In Progress").
+
+**Item closed:** When an issue or pull request is closed, its Status is automatically set to "Done."
+
+**Pull request merged:** When a pull request is merged, its Status is set to "Done."
+
+**Auto-add to project:** Items matching a filter (by label, type, or repository) are automatically added to the project.
 
 ### Setting Up Auto-Add
 
@@ -307,18 +314,21 @@ A **view** is a saved configuration of layout + filters + grouping + sort. You c
 
 The filter bar accepts a query language similar to GitHub's issue search:
 
-| Query | Meaning |
-| ---  | ---  |
-| `status:In Progress` | Show only items with that Status value |
-| `assignee:@me` | Show only items assigned to you |
-| `label:accessibility` | Items with the accessibility label |
-| `milestone:"v2.0"` | Items in a specific milestone |
-| `no:assignee` | Items with no assignee |
-| `is:pr` | Only pull requests |
-| `is:issue` | Only issues |
-| `repo:owner/name` | Items from a specific repo (cross-repo projects) |
-
-Combine filters: `assignee:@me status:"In Progress"` shows your in-progress work.
+`status:In Progress` shows only items with that Status value.
+
+`assignee:@me` shows only items assigned to you.
+
+`label:accessibility` shows items with the accessibility label.
+
+`milestone:"v2.0"` shows items in a specific milestone.
+
+`no:assignee` shows items with no assignee.
+
+`is:pr` shows only pull requests. `is:issue` shows only issues.
+
+`repo:owner/name` shows items from a specific repository, useful in cross-repo projects.
+
+You can combine filters: `assignee:@me status:"In Progress"` shows your in-progress work.
 
 ### Grouping
 

docs/appendix-m-vscode-accessibility-reference.md

@@ -177,13 +177,8 @@ The Accessible Diff Viewer presents file diffs as a structured, line-by-line lis
 
 The Accessible Diff Viewer starts with a header showing the file path and change summary. It then shows each hunk (changed section) in order. Each hunk contains: the hunk location (line range), unchanged context lines, the modified, added, or removed lines with their prefix, and more context lines. After all hunks, a footer shows the totals for additions and deletions.
 
-<details>
-<summary>Visual diagram (Mermaid)</summary>
-
 ```mermaid
 graph TD
-    accTitle: Accessible Diff Viewer structure
-    accDescr: The viewer has a header with file path and change summary, then hunks containing line ranges, unchanged context, and modified lines. A footer shows total additions and deletions.
     ROOT["Accessible Diff Viewer"]
     ROOT --> HEADER["Header\nfile path, change summary"]
     ROOT --> H1["Hunk 1 of N"]
@@ -195,8 +190,6 @@ graph TD
     ROOT --> FOOTER["Footer\ntotals: X additions, Y deletions"]
 ```
 
-</details>
-
 #### Line prefixes
 
 | Prefix | Meaning | Screen Reader Announcement |

docs/appendix-q-github-actions-workflows.md

@@ -57,13 +57,8 @@ Workflow files live in a specific, mandatory location:
 
 Workflow files live at your-repository/.github/workflows/. Example files include: ci.yml (runs tests on every push or PR), lint.yml (checks code style), a11y-scan.yml (accessibility scanning), and deploy.yml (deploys the site when code merges to main).
 
-<details>
-<summary>Visual diagram (Mermaid)</summary>
-
 ```mermaid
 graph TD
-    accTitle: GitHub Actions workflows folder structure
-    accDescr: Workflow files live at your-repository/.github/workflows/. Contains ci.yml for tests, lint.yml for code style, a11y-scan.yml for accessibility scanning, and deploy.yml for deployment.
     REPO["your-repository/"]
     REPO --> GH[".github/"]
     GH --> WF["workflows/"]
@@ -73,8 +68,6 @@ graph TD
     WF --> DEPLOY["deploy.yml\nDeploys on merge to main"]
 ```
 
-</details>
-
 The `.github/` folder is hidden by convention (starts with a dot). To find it:
 
 - **On GitHub.com:** The file browser shows it - use `T` (go to file) or navigate the file table with `Ctrl+Alt+Arrow` keys