` | Major sections |
| `### Subsection` | `` | Subsections within a section |
| `#### Detail` | `` | Detailed topics within a subsection |
| `##### Fine detail` | `` | Rarely used, very specific topics |
| `###### Finest detail` | `` | Almost never needed |
### Rules for accessible headings
1. **One H1 per document.** The `#` heading is your document title. Every document gets exactly one
2. **Never skip levels.** Go from `##` to `###`, never from `##` to `####`. Skipping levels breaks the document outline for screen reader users who navigate by heading
3. **Make headings descriptive.** A heading of "Section 3" tells a screen reader user nothing. A heading of "Creating Your First Pull Request" tells them exactly what the section covers
4. **Do not use bold as a heading substitute.** Writing `**My Section**` on its own line looks like a heading visually, but it is not a heading in the document structure. Screen reader users navigating by heading (`H` key in Browse Mode) will never find it
> **Screen reader note:** Screen readers let you navigate by heading level. In NVDA and JAWS, pressing `H` moves to the next heading. Pressing `1` through `6` moves to the next heading at that specific level. This is one of the most important navigation methods on any page - and it only works if the document uses real headings in the correct hierarchy.
### Alternative heading syntax (not recommended)
Markdown also supports "setext" headings where you underline text with `=` or `-` characters:
```markdown
Heading Level 1
===============
Heading Level 2
---------------
```
This only works for levels 1 and 2, and it is harder to scan visually in raw Markdown. Stick with the `#` syntax - it is clearer, supports all six levels, and is what you will see in virtually every GitHub project.
## 6. Emphasis - Bold, Italic, and Bold Italic
Emphasis changes how text is read by screen readers - it is not just visual. When text is bold or italic, well-configured screen readers can announce emphasis changes, giving the listener additional context about importance.
### Bold
Wrap text in **two asterisks** or **two underscores** on each side.
**What you type:**
```markdown
This is **bold text** using asterisks.
This is __bold text__ using underscores.
```
**What renders:**
This is **bold text** using asterisks.
This is __bold text__ using underscores.
**Best practice:** Use asterisks (`**`). Underscores can cause problems in the middle of words (like `file__name__here`), while asterisks always work.
### Italic
Wrap text in **one asterisk** or **one underscore** on each side.
**What you type:**
```markdown
This is *italic text* using asterisks.
This is _italic text_ using underscores.
```
**What renders:**
This is *italic text* using asterisks.
This is _italic text_ using underscores.
### Bold and italic combined
Wrap text in **three asterisks** on each side.
**What you type:**
```markdown
This is ***bold and italic*** text.
```
**What renders:**
This is ***bold and italic*** text.
### When to use emphasis
The following table provides guidance on when to use each type of emphasis.
| Type | When to use | Example |
|---|---|---|
| **Bold** | Key terms, important warnings, UI element names | "Click the **Submit** button" |
| *Italic* | Book or document titles, introducing new terms, gentle emphasis | "See the *Contributing Guide* for details" |
| ***Bold italic*** | Extremely rare - critical warnings only | "***Do not force push to the main branch***" |
> **Screen reader note:** NVDA can announce emphasis changes if the user enables "Report font attributes" (under Speech settings). JAWS can announce emphasis with "Say all font changes" enabled. VoiceOver announces emphasis by default on macOS. Even when emphasis is not announced, the HTML semantic structure (`` for bold, `` for italic) is available to screen readers that choose to report it.
### Emphasis inside words
Asterisks work inside words. Underscores do not (in most Markdown processors including GitHub).
```markdown
This**works**fine.
This__does__not.
```
Renders as: This**works**fine. This__does__not.
Use asterisks when you need emphasis inside a word (rare, but it comes up in technical documentation).
## 7. Strikethrough
Strikethrough text shows deleted or outdated content with a line through it. Wrap text in **two tildes** on each side.
**What you type:**
```markdown
The meeting is ~~Tuesday~~ Wednesday at 3 PM.
~~This feature has been removed.~~
```
**What renders:**
The meeting is ~~Tuesday~~ Wednesday at 3 PM.
~~This feature has been removed.~~
> **Screen reader note:** Screen reader behavior with strikethrough varies. NVDA with "Report font attributes" enabled will announce "strikethrough" before the text. JAWS may announce it as "deleted." VoiceOver does not announce strikethrough by default - the text is simply read. Because of this inconsistency, do not rely on strikethrough alone to convey meaning. Add context in the surrounding text: "The meeting was changed from ~~Tuesday~~ to Wednesday."
> **GitHub note:** Strikethrough is part of the GitHub Flavored Markdown specification. It is not in standard Markdown or CommonMark.
## 8. Lists - Ordered and Unordered
Lists are one of the most common elements in GitHub documentation. Issue descriptions, PR checklists, README instructions, step-by-step guides - they all use lists.
### Unordered lists (bullet points)
Start each line with a dash (`-`), asterisk (`*`), or plus sign (`+`) followed by a space.
**What you type:**
```markdown
- First item
- Second item
- Third item
```
**What renders:**
- First item
- Second item
- Third item
**Best practice:** Use dashes (`-`). They are the most common convention on GitHub and visually distinct from the asterisks used for bold and italic.
> **Important:** Be consistent within a single list. Do not mix `-`, `*`, and `+` in the same list - some processors handle it inconsistently, and it makes the raw Markdown harder to read.
### Ordered lists (numbered)
Start each line with a number followed by a period and a space.
**What you type:**
```markdown
1. Clone the repository
2. Create a new branch
3. Make your changes
4. Open a pull request
```
**What renders:**
1. Clone the repository
2. Create a new branch
3. Make your changes
4. Open a pull request
### A helpful trick - Markdown renumbers for you
Here is something that surprises most new users. In Markdown, the actual numbers you type do not matter for the rendered output. Markdown automatically numbers the list sequentially. This means you can use `1.` for every item:
```markdown
1. Clone the repository
1. Create a new branch
1. Make your changes
1. Open a pull request
```
This still renders as 1, 2, 3, 4. The benefit is that when you insert a new step in the middle, you do not need to renumber everything. However, for readability of the raw Markdown, many authors prefer typing the correct numbers.
> **Screen reader note:** Screen readers announce list items with their position: "list, 4 items. 1. Clone the repository. 2. Create a new branch." and so on. The semantic list structure is preserved in the HTML output, so navigation commands like `L` (next list) and `I` (next list item) work correctly in NVDA and JAWS Browse Mode.
### Starting an ordered list at a specific number
If you need a list to start at a number other than 1, use that number for the first item. All subsequent items are numbered sequentially from there:
```markdown
3. This is step three
4. This is step four
5. This is step five
```
## 9. Nested Lists and Mixed Lists
Lists can contain other lists, creating an indented hierarchy. This is essential for complex instructions, outlines, and project structures.
### Nesting unordered lists
Indent the nested items by **two or four spaces** (GitHub accepts either, but four is most reliable).
**What you type:**
```markdown
- Accessibility testing tools
- Screen readers
- NVDA (Windows, free)
- JAWS (Windows, commercial)
- VoiceOver (macOS and iOS, built-in)
- Browser extensions
- axe DevTools
- WAVE
- Documentation tools
- Markdown editors
- Static site generators
```
**What renders:**
- Accessibility testing tools
- Screen readers
- NVDA (Windows, free)
- JAWS (Windows, commercial)
- VoiceOver (macOS and iOS, built-in)
- Browser extensions
- axe DevTools
- WAVE
- Documentation tools
- Markdown editors
- Static site generators
### Nesting ordered lists
The same indentation principle applies to numbered lists:
```markdown
1. Set up your environment
1. Install Git
2. Create a GitHub account
3. Configure your screen reader
2. Learn GitHub navigation
1. Understand the page structure
2. Master keyboard shortcuts
3. Practice with the Learning Room
```
### Mixing ordered and unordered lists
You can nest an unordered list inside an ordered list and vice versa:
```markdown
1. Before the workshop
- Create a GitHub account
- Install VS Code
- Test your screen reader
2. During Day 1
- File your first issue
- Open your first pull request
3. After the workshop
- Continue contributing
- Join community discussions
```
### Adding content inside list items
List items can contain paragraphs, code blocks, and other elements. Indent the content to align with the list item text (typically four spaces):
```markdown
1. Clone the repository
Open your terminal and run the following command:
```bash
git clone https://github.com/community-access/accessibility-agents.git
```
This downloads the entire repository to your computer.
2. Create a new branch
```bash
git checkout -b fix/broken-link
```
```
> **Screen reader note:** Nested lists are announced with their nesting level. NVDA says "list, nesting level 2" when entering an inner list. This helps you understand the hierarchy by ear.
## 10. Links
Links are how you connect documents, reference issues, point to external resources, and cite sources. Getting links right is critical for accessibility - links with bad text are one of the most common accessibility failures in documentation.
### Basic link syntax
Wrap the visible link text in square brackets, followed immediately by the URL in parentheses:
```markdown
[GitHub Documentation](https://docs.github.com)
```
**Renders as:** [GitHub Documentation](https://docs.github.com)
### Links with title text
Add a title in quotes after the URL. The title appears as a tooltip on hover:
```markdown
[GitHub Documentation](https://docs.github.com "Official GitHub docs and guides")
```
> **Screen reader note:** Link titles are not reliably announced by all screen readers. Do not put critical information only in the title text. The link text itself must be descriptive.
### Writing accessible link text
This is one of the most important accessibility skills in Markdown authoring. Screen reader users often navigate by pulling up a list of all links on a page (NVDA: `NVDA+F7` then select Links; JAWS: `Insert+F7`). In this list, only the link text is shown - not the surrounding sentence. Every link must make sense on its own.
The following table contrasts bad and good link text with an explanation.
| Bad (do not do this) | Good (do this instead) | Why |
|---|---|---|
| Click [here](url) for the guide | Read the [Contributing Guide](url) | "here" means nothing out of context |
| [Read more](url) | [Read the full accessibility audit report](url) | "Read more" is ambiguous in a link list |
| [https://docs.github.com](https://docs.github.com) | [GitHub Documentation](https://docs.github.com) | Screen readers read the entire URL character by character |
| [Link](url) | [Pre-Workshop Setup instructions](url) | "Link" tells you nothing about the destination |
### Reference-style links
For documents with many links, reference-style links keep the text readable by separating the URL from the prose. You define the link target once at the bottom of the document:
```markdown
Check the [Contributing Guide][contributing] before submitting a PR.
See also the [Code of Conduct][coc] for community standards.
[contributing]: https://github.com/community-access/accessibility-agents/blob/main/CONTRIBUTING.md
[coc]: https://github.com/community-access/accessibility-agents/blob/main/CODE_OF_CONDUCT.md
```
The reference labels (`[contributing]`, `[coc]`) do not appear in the rendered output. Readers just see clean, clickable links.
### Relative links within a repository
When linking to other files in the same repository, use relative paths instead of full URLs. This way, links work on any fork or branch:
```markdown
See the [Pre-Workshop Setup](00-pre-workshop-setup.md) guide.
Jump to the [Glossary](appendix-a-glossary.md#fork) entry for "fork."
Return to the [course guide](course-guide.md).
```
### Email links
```markdown
Contact us at
```
The angle brackets tell Markdown to create a `mailto:` link:
### Autolinked URLs
GitHub automatically converts full URLs in your text into clickable links, but always prefer explicit descriptive links in prose. Bare URLs should only appear in reference sections or code examples.
## 11. Images
Images in Markdown use a syntax similar to links, with an exclamation mark (`!`) at the beginning.
### Syntax
```markdown
```
The text inside the square brackets is the **alt text** - the description that screen readers read aloud instead of displaying the image. This is the single most important accessibility attribute for images.
### Writing good alt text
The following table provides guidance on alt text for different types of images.
| Image type | Good alt text | Bad alt text |
|---|---|---|
| Screenshot of a form | "GitHub new issue form with title field, body text area, and submit button" | "screenshot" |
| Logo | "Community Access logo" | "logo.png" |
| Decorative divider | Leave alt text empty: `` | "divider" |
| Chart or graph | "Bar chart showing screen reader usage: JAWS 40%, NVDA 35%, VoiceOver 15%, Other 10%" | "chart" |
| Photo of a person | "Jamie presenting at the accessibility workshop podium" | "photo" |
### Image with a link
To make an image clickable, wrap the image syntax inside a link:
```markdown
[](https://community-access.org)
```
### Image with a title
```markdown
```
### When to use details blocks for complex images
If an image contains complex information (like an architecture diagram or a data visualization), provide a full text description in a collapsible `` block:
```markdown
Full description of the architecture diagram
The architecture has three tiers:
1. The GitHub Hub agent receives all user requests
2. The Hub routes to specialist agents (issue-tracker, pr-review, analytics)
3. Each specialist agent returns structured markdown reports
```
> **Screen reader note:** Screen readers announce images as "graphic" followed by the alt text. If alt text is empty, the image is treated as decorative and skipped. If alt text is missing entirely (no square brackets), some screen readers will announce the filename, which is not helpful. Always include the square brackets, even if empty for decorative images.
## 12. Blockquotes
Blockquotes are used for callouts, important notes, cited text, and instructor guidance throughout this course. Start each line with a `>` character followed by a space.
### Basic blockquote
**What you type:**
```markdown
> This is a blockquote. It is used to highlight important information
> or to quote someone else's text.
```
**What renders:**
> This is a blockquote. It is used to highlight important information or to quote someone else's text.
### Multi-paragraph blockquotes
Add a `>` on the blank lines between paragraphs to keep them inside the blockquote:
```markdown
> This is the first paragraph of the blockquote.
>
> This is the second paragraph. The blank line with just ">" keeps
> both paragraphs inside the same blockquote.
```
### Nested blockquotes
```markdown
> This is the outer blockquote.
>
> > This is a nested blockquote inside the first one.
>
> Back to the outer level.
```
### Blockquotes with other elements
Blockquotes can contain any Markdown element - headings, lists, code, bold, links:
```markdown
> **Important:** Before starting the exercise:
>
> 1. Make sure you are on the `main` branch
> 2. Pull the latest changes: `git pull origin main`
> 3. Read the [challenge description](challenges.md) first
>
> If you get stuck, ask in the issue thread.
```
> **Screen reader note:** Screen readers announce the beginning and end of a blockquote. NVDA says "block quote" when entering and "out of block quote" when leaving. Content inside is read normally. This means blockquotes are an excellent way to highlight important information for all users.
### How we use blockquotes in this course
Throughout this workshop, blockquotes serve specific purposes:
- **Screen reader notes:** Tips specific to assistive technology users
- **Learning Room connections:** How the current topic connects to the practice repo
- **Important warnings:** Critical information that could prevent errors
- **Instructor guidance:** Notes from the facilitator about pacing or approach
## 13. Inline Code and Code Blocks
Code formatting is essential on GitHub. You will use it for command-line instructions, file names, configuration values, keyboard shortcuts, and actual source code.
### Inline code
Wrap text in single backticks (`` ` ``) to format it as code within a sentence.
**What you type:**
```markdown
Run `git status` to see which files have changed.
The configuration file is `package.json`.
Press `Ctrl+Shift+P` to open the Command Palette.
```
**What renders:**
Run `git status` to see which files have changed.
The configuration file is `package.json`.
Press `Ctrl+Shift+P` to open the Command Palette.
**When to use inline code:**
- Command names: `git clone`, `npm install`
- File names: `README.md`, `CONTRIBUTING.md`
- Keyboard shortcuts: `Ctrl+C`, `Alt+Tab`
- Variable or function names: `userName`, `getElementById()`
- Configuration values: `true`, `false`, `null`
- Branch names: `main`, `feature/add-alt-text`
### Code blocks (fenced)
For multi-line code, wrap it in triple backticks (` ``` `) on their own lines:
**What you type:**
````markdown
```
This is a code block.
All formatting is preserved exactly.
Indentation stays.
**Bold does not render** - it stays as plain text.
```
````
### Code blocks with syntax highlighting
Add a language identifier right after the opening triple backticks to enable syntax highlighting:
````markdown
```python
def greet(name: str) -> str:
"""Return a greeting for the given name."""
return f"Hello, {name}! Welcome to the workshop."
```
````
```python
def greet(name: str) -> str:
"""Return a greeting for the given name."""
return f"Hello, {name}! Welcome to the workshop."
```
The following table lists language identifiers you will encounter most often in this workshop.
| Language | Identifier | Used for |
|---|---|---|
| Python | `python` | Scripts, automation, Copilot examples |
| Bash / Shell | `bash` or `shell` | Terminal commands, Git operations |
| YAML | `yaml` | GitHub Actions workflows, issue templates |
| JSON | `json` | Configuration files, API responses |
| JavaScript | `javascript` or `js` | Web scripts, Node.js |
| HTML | `html` | Web page structure |
| CSS | `css` | Styling |
| Markdown | `markdown` | Markdown examples (yes, you can format Markdown inside Markdown) |
| Plain text | `text` or `plaintext` | When no highlighting is needed |
| Diff | `diff` | Showing code changes (additions in green, removals in red) |
### Showing diffs in code blocks
The `diff` language identifier highlights additions and removals:
````markdown
```diff
- old line that was removed
+ new line that was added
unchanged context line
```
````
```diff
- old line that was removed
+ new line that was added
unchanged context line
```
### Code blocks inside list items
Indent the code block to align with the list item text:
```markdown
1. Create a new branch:
```bash
git checkout -b feature/my-change
```
2. Make your changes and stage them:
```bash
git add .
```
```
### How to show literal backticks
If your code contains backticks, use more backticks for the fence:
`````markdown
````markdown
```python
print("Hello")
```
````
`````
Use four backticks to wrap content that contains triple backticks. Use five to wrap content that contains four. You get the idea.
> **Screen reader note:** Code blocks are announced as "code" regions. Screen readers read the content character by character when navigating with arrow keys, and as whole lines when navigating with `Down Arrow`. Syntax highlighting is visual only - it does not affect what screen readers announce. The code text is equally accessible whether highlighted or not.
## 14. Horizontal Rules
A horizontal rule creates a thematic break between sections - a visual line across the page. Use three or more dashes, asterisks, or underscores on a line by themselves.
**What you type (any of these work):**
```markdown
***
___
```
**Best practice:** Use `---` (three dashes). It is the most common convention and looks clean in raw Markdown. Always put a blank line before and after the rule.
> **Screen reader note:** Horizontal rules are announced as "separator" in NVDA, "horizontal separator" in JAWS, and "horizontal rule" in VoiceOver. They are useful as navigation landmarks - screen reader users can move between them, but do not overuse them. Headings are a better way to structure a document.
## 15. Escaping Special Characters
Many characters have special meaning in Markdown. If you want to display them as literal characters instead, put a backslash (`\`) before them.
### Characters that can be escaped
The following table lists every character that can be escaped in Markdown.
| Character | Name | Markdown meaning |
|---|---|---|
| `\` | Backslash | Escape character itself |
| `` ` `` | Backtick | Inline code |
| `*` | Asterisk | Bold, italic, or list item |
| `_` | Underscore | Bold or italic |
| `{}` | Curly braces | Used in some extensions |
| `[]` | Square brackets | Link text |
| `()` | Parentheses | Link URL |
| `#` | Hash | Heading |
| `+` | Plus sign | Unordered list |
| `-` | Dash | Unordered list or horizontal rule |
| `.` | Period | Ordered list (after a number) |
| `!` | Exclamation mark | Image |
| `|` | Pipe | Table column separator |
| `~` | Tilde | Strikethrough |
### Examples
**What you type:**
```markdown
This asterisk is literal: \*not bold\*
This hash is literal: \# not a heading
Show a pipe character: \|
```
**What renders:**
This asterisk is literal: \*not bold\*
This hash is literal: \# not a heading
Show a pipe character: \|
## 16. Tables
Tables organize data into rows and columns. They are used extensively on GitHub for comparison charts, reference data, settings documentation, and checklists.
### Basic table syntax
```markdown
| Name | Role | Platform |
|---|---|---|
| NVDA | Screen reader | Windows |
| JAWS | Screen reader | Windows |
| VoiceOver | Screen reader | macOS / iOS |
| TalkBack | Screen reader | Android |
```
**What renders:**
| Name | Role | Platform |
|---|---|---|
| NVDA | Screen reader | Windows |
| JAWS | Screen reader | Windows |
| VoiceOver | Screen reader | macOS / iOS |
| TalkBack | Screen reader | Android |
### How table syntax works
- The **first row** is always the header row
- The **second row** contains dashes (`---`) that separate the header from the data. You need at least three dashes per column
- Each **subsequent row** is a data row
- Columns are separated by pipe characters (`|`)
- Leading and trailing pipes are optional but recommended for readability
### Column alignment
Add colons (`:`) to the separator row to control text alignment:
```markdown
| Left aligned | Center aligned | Right aligned |
|:---|:---:|---:|
| Text | Text | Text |
| Longer text here | Centered text | 42 |
```
| Left aligned | Center aligned | Right aligned |
|:---|:---:|---:|
| Text | Text | Text |
| Longer text here | Centered text | 42 |
- `:---` = left aligned (default)
- `:---:` = center aligned
- `---:` = right aligned
### Formatting inside table cells
You can use inline formatting within table cells:
```markdown
| Feature | Status | Notes |
|---|---|---|
| **Bold text** | `code` | Works [with links](url) too |
| *Italic text* | ~~struck~~ | Use any inline formatting |
```
### Accessibility considerations for tables
1. **Always include a description before the table.** Add a one-sentence summary immediately above the table explaining what it contains. Screen reader users hear the table structure (rows and columns) but benefit from knowing what the table is about before entering it
2. **Keep tables simple.** Tables with more than 5-6 columns become difficult to navigate with a screen reader. Consider splitting wide tables into multiple narrower tables
3. **Use tables for data, not layout.** If you are using a table just to arrange content side by side, use a list instead
4. **Make the header row descriptive.** The header cell is announced before each data cell when navigating by column, so "Platform" is better than "Col 3"
> **Screen reader note:** Screen readers navigate tables with `Ctrl+Alt+Arrow` keys (NVDA and JAWS). `Ctrl+Alt+Right` moves to the next column. `Ctrl+Alt+Down` moves to the next row. The column header is announced each time you move to a new column. Table mode is entered automatically when the screen reader encounters a table.
### When not to use a table
If your "table" has only two columns where the first is a label and the second is a value, consider using a definition-style list or bold labels instead:
```markdown
**Name:** Community Access
**Founded:** 2020
**Mission:** Empowering blind and low vision technology professionals
```
This is often easier to read with a screen reader than a two-column table.
## Part 2 - GitHub Flavored Markdown (GFM)
## 17. What Is GitHub Flavored Markdown?
GitHub Flavored Markdown (GFM) is GitHub's own superset of standard Markdown. It takes everything from the CommonMark specification (the modern standard for Markdown) and adds features specifically designed for software collaboration: tables, task lists, strikethrough, autolinked references, alert blocks, Mermaid diagrams, math expressions, and footnotes.
Everything you learned in Part 1 works everywhere Markdown is supported. Everything in Part 2 is specific to GitHub (and some other platforms that have adopted GFM).
### Where GFM works
The following table shows where GFM is supported.
| Location | GFM supported | Notes |
|---|---|---|
| `.md` files in repos | Yes | Any Markdown file rendered on GitHub |
| Issue descriptions | Yes | Full GFM with autolinks |
| Issue comments | Yes | Full GFM with autolinks |
| Pull request descriptions | Yes | Full GFM with autolinks |
| Pull request comments | Yes | Full GFM with autolinks |
| Discussion posts | Yes | Full GFM with autolinks |
| Wiki pages | Yes | Full GFM |
| Gists | Yes | Full GFM |
| Commit messages | Partial | Basic formatting, autolinks - no Mermaid or math |
| GitHub Pages (Jekyll) | Depends | Jekyll has its own Markdown processor |
| VS Code preview | Mostly | Supports most GFM; Mermaid requires an extension |
## 18. Alert and Callout Blocks
GitHub introduced **alert blocks** in 2023. They render as colored, bordered callout boxes - great for emphasizing warnings, tips, or critical information. You will see these throughout this course to highlight screen reader notes, important warnings, and tips.
### Syntax
```markdown
> [!NOTE]
> Useful information that users should know, even when skimming.
> [!TIP]
> Helpful advice for doing something better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```
### How to write them
1. Start a blockquote with `>`
2. The first line must be exactly `> [!TYPE]` where TYPE is one of: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`
3. All subsequent lines start with `>` and a space, just like a regular blockquote
4. You can include any Markdown inside the alert: lists, code, links, bold
### Choosing the right alert type
The following table describes each alert type and when to use it.
| Type | Color | When to use | Example |
|---|---|---|---|
| `NOTE` | Blue | Supplementary information the reader should know | Additional context about a feature |
| `TIP` | Green | Best practice or shortcut | "Use `Ctrl+Shift+P` for faster access" |
| `IMPORTANT` | Purple | Something the reader absolutely must know | Required configuration step |
| `WARNING` | Yellow | A potential problem or non-obvious risk | "This changes are not reversible after merge" |
| `CAUTION` | Red | An action that could cause irreversible harm | "This deletes all branches and cannot be undone" |
### Multi-line alert with formatting
```markdown
> [!WARNING]
> **Do not skip the pre-workshop setup.**
>
> If you arrive without a configured environment, you will spend the first
> hour catching up while others are working on challenges. Complete
> [Chapter 0](00-pre-workshop-setup.md) before Day 1.
>
> Checklist:
>
> - Git installed
> - GitHub account created
> - Screen reader configured for GitHub
```
### Screen Reader Behavior
Alert blocks render as `` elements with an SVG icon and a strong heading. Screen readers read:
- NVDA/JAWS: announces `blockquote` role, then reads the type label ("Note", "Warning") then the content
- VoiceOver: reads the type as bold text then the content
- The colored icon is decorative (`aria-hidden`); it does not add information beyond the type label
## 19. Collapsible Sections with Details and Summary
The `` and `` HTML elements create collapsible sections. They are one of the most useful tools for keeping long documents, issue reports, and PRs manageable - hiding optional content until the reader chooses to expand it.
### Basic syntax
```markdown
Click to expand: Full error log
Content that is hidden until the user expands this section.
You can put **any Markdown** in here:
- Lists
- Code blocks
- Links
- Tables
```
### Important formatting rules
1. **Blank line after ``.** Put a blank line between the closing `
` tag and your Markdown content. Without it, Markdown formatting inside may not render
2. **Blank line before `
`.** Same principle at the end
3. The `` text should be descriptive - it is the only thing visible when collapsed
### Real-world uses in this workshop
The following list describes common uses for collapsible sections.
- **Bug reports in issues:** Collapse the full stack trace so the issue body stays readable
- **Long configuration blocks:** Let readers expand the full YAML only if they need it
- **Exercise solutions:** Collapse the answer so learners try the exercise first
- **Screen reader guidance blocks:** Throughout this course, some sections collapse detailed assistive technology instructions so sighted users see a cleaner page while screen reader users can easily expand them
- **Meeting notes:** Collapse detailed minutes while showing the summary
### Nesting details inside details
```markdown
Operating system instructions
Windows
1. Open PowerShell
2. Run `git --version`
macOS
1. Open Terminal
2. Run `git --version`
```
### Details sections that start open
Add the `open` attribute to have the section expanded by default:
```markdown
Currently known issues
- Checkbox toggle requires Focus Mode in NVDA
- Alert blocks do not render in email notifications
```
### Screen Reader Behavior
The `` element renders as a disclosure widget:
- NVDA: announces "button collapsed" for the `` - press `Enter` or `Space` to expand
- JAWS: announces "collapsed" - press `Enter` on the summary to expand
- VoiceOver: announces "collapsed, button" - press `VO+Space` to activate
**After expanding:** The content is immediately readable. Screen readers announce "button expanded" for the summary. No page reload occurs.
## 20. Task List Checkboxes
Task lists in GitHub issues and PRs render as **real interactive checkboxes**. Anyone with write access to the repository can check and uncheck them directly in the rendered view without editing the Markdown.
### Syntax
```markdown
- [x] Color contrast verified (4.5:1 minimum for body text)
- [x] Keyboard navigation tested
- [ ] Screen reader tested with NVDA
- [ ] Screen reader tested with JAWS
- [ ] Screen reader tested with VoiceOver
- [ ] Alt text provided for all images
- [ ] Focus indicators visible
```
### How to write them
1. Start with a list item marker (`-`, `*`, or `+`) and a space
2. Add `[x]` for a checked box or `[ ]` (with a space inside) for an unchecked box
3. Add a space, then the task description
4. The description should be meaningful - "Test NVDA" is better than "Item 3"
### What makes task lists special on GitHub
- **Progress tracking:** In issues, GitHub shows a progress bar: "2 of 7 tasks completed"
- **Click to check:** In the rendered view, users with triage or write permissions can click to toggle checkboxes without editing the comment
- **Linked issues:** You can reference issues in a task: `- [ ] Fix #42` - the task shows the issue title and its open/closed state
- **PR templates:** Task lists in PR templates create checklists that authors fill out before requesting review
### Example - pull request checklist
```markdown
## Pre-review checklist
- [x] Changes are limited to the files listed in the issue
- [x] All new images have descriptive alt text
- [ ] Screen reader tested the changes with NVDA
- [ ] No heading levels are skipped
- [ ] All links use descriptive text (not "click here")
```
### Screen Reader Interaction
In Browse Mode, checkboxes are read as `checkbox, not checked` or `checkbox, checked`.
**To toggle a task list checkbox:**
- NVDA: Press `NVDA+Space` to enter Focus Mode, then `Tab` to find the checkbox, then `Space` to toggle it
- JAWS: `Tab` to the checkbox, then `Space` to toggle
- VoiceOver: `VO+Space` on the checkbox element
## 21. Syntax Highlighting in Fenced Code Blocks
We covered basic code blocks in Section 13. This section covers the GitHub-specific syntax highlighting that makes code blocks more readable for sighted users.
### How it works
Add a language identifier right after the opening triple backticks. GitHub uses Linguist to apply syntax highlighting with appropriate colors for keywords, strings, comments, and other language constructs.
````markdown
```python
def check_accessibility(element):
"""Check if an element has proper ARIA attributes."""
if not element.get("aria-label") and not element.get("aria-labelledby"):
return "Missing accessible name"
return "Accessible"
```
````
### Complete list of commonly used language identifiers
The following table lists the language identifiers you are most likely to use.
| Identifier | Language | Example use in this workshop |
|---|---|---|
| `python` | Python | Scripts, automation, challenge code |
| `bash` or `shell` | Bash/Shell | Terminal commands, Git operations |
| `yaml` or `yml` | YAML | GitHub Actions, issue templates |
| `json` | JSON | Configuration, API responses |
| `javascript` or `js` | JavaScript | Web scripts |
| `typescript` or `ts` | TypeScript | Typed JavaScript |
| `html` | HTML | Web page structure |
| `css` | CSS | Styling |
| `markdown` or `md` | Markdown | Documenting Markdown syntax |
| `diff` | Diff | Code change comparison |
| `text` or `plaintext` | None | No highlighting needed |
| `ruby` | Ruby | Ruby scripts |
| `go` | Go | Go programs |
| `rust` | Rust | Rust programs |
| `java` | Java | Java programs |
| `csharp` or `cs` | C# | .NET programs |
| `sql` | SQL | Database queries |
| `dockerfile` | Dockerfile | Container configuration |
| `xml` | XML | Structured data |
| `toml` | TOML | Configuration (Rust, Python) |
| `ini` | INI | Configuration files |
| `powershell` or `ps1` | PowerShell | Windows automation |
If no language is specified, the code block renders as plain monospaced text with no highlighting.
### Screen Reader Note
Syntax highlighting is visual only - screen readers read the code text without announcing color changes. The code block itself is announced as a `code` region. This means the text content of well-written code is equally accessible whether highlighted or not. Variable names, function names, and comments are the real accessibility of code - not colors.
## 22. Mermaid Diagrams
GitHub renders [Mermaid.js](https://mermaid.js.org/) diagrams inline when you use a `mermaid` fenced code block. They are common in READMEs, PRs, and documentation to illustrate architecture, flows, and relationships.
### Syntax
````markdown
```mermaid
flowchart LR
A[Fork repo] --> B[Clone locally]
B --> C[Create branch]
C --> D[Make changes]
D --> E[Push branch]
E --> F[Open PR]
F --> G{Review passed?}
G -- Yes --> H[Merge]
G -- No --> D
```
````
### Common diagram types
The following table lists the Mermaid diagram types you are most likely to encounter on GitHub.
| Type | Keyword | Use case |
|---|---|---|
| Flowchart | `flowchart LR` or `flowchart TD` | Process flows, decision trees |
| Sequence diagram | `sequenceDiagram` | API calls, user interactions |
| Entity-Relationship | `erDiagram` | Database schemas |
| Class diagram | `classDiagram` | Code architecture |
| Gantt chart | `gantt` | Project schedules |
| Git graph | `gitGraph` | Branch and merge visualization |
| Pie chart | `pie` | Data distribution |
### Accessibility limitation - critical
> **Important:** Mermaid diagrams render as SVG images. GitHub does not auto-generate alt text for them. Screen readers will typically either skip them entirely or announce generic SVG container information that is not useful.
This means **every Mermaid diagram is invisible to screen reader users unless you provide a text alternative.**
### How to make Mermaid diagrams accessible
Always follow this pattern:
1. Write a **text description** before the diagram that conveys all the same information
2. Optionally, duplicate the information as a numbered list or table
3. Consider wrapping the Mermaid source in a `` block if the text description is sufficient
**Example - accessible Mermaid usage:**
````markdown
The PR workflow follows these steps: fork the repository, clone
your fork locally, create a feature branch, make your changes and commit,
push the branch to your fork, open a pull request, address review feedback,
and merge when approved.
1. Fork the repository
2. Clone your fork locally
3. Create a feature branch
4. Make your changes and commit
5. Push the branch to your fork
6. Open a pull request
7. Address review feedback
8. Merge when approved
Diagram source (Mermaid)
```mermaid
flowchart LR
Fork --> Clone --> Branch --> Commit --> Push --> PR --> Review --> Merge
```
````
This way, screen reader users get the full information from the text and numbered list. Sighted users can also expand the Mermaid diagram for a visual representation.
## 23. Math Expressions with LaTeX
GitHub renders LaTeX math expressions using MathJax. This is common in data science, research, and algorithm documentation.
### Inline math
Use single `$` delimiters for math within a sentence:
```markdown
The formula is $e = mc^2$ where $c$ is the speed of light.
```
**Renders as:** The formula is $e = mc^2$ where $c$ is the speed of light.
### Block math
Use `$$` delimiters for display-style (centered, larger) math on their own lines:
```markdown
$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$
```
### Common LaTeX patterns
The following table shows some LaTeX patterns you might encounter.
| What you want | LaTeX | Rendered |
|---|---|---|
| Superscript | `$x^2$` | $x^2$ |
| Subscript | `$x_i$` | $x_i$ |
| Fraction | `$\frac{a}{b}$` | $\frac{a}{b}$ |
| Square root | `$\sqrt{x}$` | $\sqrt{x}$ |
| Greek letter | `$\alpha, \beta, \gamma$` | $\alpha, \beta, \gamma$ |
| Summation | `$\sum_{i=1}^{n}$` | $\sum_{i=1}^{n}$ |
| Not equal | `$\neq$` | $\neq$ |
| Less or equal | `$\leq$` | $\leq$ |
### Screen Reader Note
Math expressions rendered by MathJax include `aria-label` attributes with the spoken form of the equation. Screen readers should announce the math correctly, but accuracy varies:
- NVDA with Firefox or Chrome: reads MathML fairly well
- JAWS: reads the aria-label text
- VoiceOver: reads the aria-label text
**Best practice:** If writing documentation for an accessibility-focused audience, supplement complex equations with a plain English description:
```markdown
The sum of all values from 1 to n equals n times n+1 divided by 2:
$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$
```
## 24. Footnotes
GitHub supports Markdown footnotes, which render as superscript numbers that link to references at the bottom of the document. They are useful for citations, additional context, and references that would interrupt the flow of the main text.
### Syntax
```markdown
This technique improves screen reader navigation significantly.[^1]
You can also use named footnotes for clarity.[^accessibility-note]
[^1]: Based on the WebAIM Screen Reader Survey, 2024.
[^accessibility-note]: See WCAG 2.2 Success Criterion 2.4.3 for focus order requirements.
```
### How they work
1. In your text, add `[^identifier]` where you want the footnote reference to appear
2. Anywhere in the document (typically at the bottom), define the footnote with `[^identifier]: Your footnote text`
3. GitHub renders the reference as a superscript number that links to the definition
4. The definition includes a back-link that returns to the reference location
### Footnote identifiers
- You can use numbers: `[^1]`, `[^2]`, `[^3]`
- You can use descriptive names: `[^webaim-survey]`, `[^wcag-reference]`
- Descriptive names make the raw Markdown more readable but render as sequential numbers
### Multi-line footnotes
Indent continuation lines with two spaces:
```markdown
[^long-note]: This is a longer footnote that spans multiple paragraphs.
The second paragraph of the footnote is indented with two spaces.
You can even include code: `git status`
```
### Screen Reader Behavior
- The footnote reference is a link (`` element) announcing its number
- NVDA: "superscript, 1, link"
- JAWS: "link, 1"
- VoiceOver: "link, footnote 1"
- The back-link at the definition reads "return to footnote reference"
- Activating the footnote link jumps focus to the definition; activating the back-link returns focus to the original location
## 25. Linked Heading Anchors and Tables of Contents
Every heading in a GitHub Markdown file automatically gets an anchor ID. You can link to any heading from anywhere - within the same document, from another file, or from an issue or PR.
### How GitHub generates anchor IDs
GitHub converts the heading text to an anchor ID by:
1. Converting to lowercase
2. Replacing spaces with hyphens
3. Removing most punctuation (except hyphens)
4. Removing leading and trailing whitespace
The following table shows example headings and their generated anchors.
| Heading text | Generated anchor |
|---|---|
| `# Introduction` | `#introduction` |
| `## Getting Started` | `#getting-started` |
| `### VS Code: Setup & Accessibility Basics` | `#vs-code-setup--accessibility-basics` |
| `## 1. First Steps` | `#1-first-steps` |
| `## What Is a PR?` | `#what-is-a-pr` |
### Linking to a heading in the same document
```markdown
See the [Tables](#16-tables) section for details on formatting data.
Return to the [Table of Contents](#table-of-contents).
```
### Linking to a heading in another file
```markdown
See the [Pre-Workshop Setup guide](00-pre-workshop-setup.md#step-1---create-a-github-account).
```
### Building a table of contents
You can build a manual table of contents using heading anchor links:
```markdown
## Table of Contents
1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Usage](#usage)
5. [Contributing](#contributing)
```
### Duplicate headings
If a document has two headings with the same text, GitHub appends `-1`, `-2`, and so on to the duplicate anchors:
| Heading | Anchor |
|---|---|
| First `## Examples` | `#examples` |
| Second `## Examples` | `#examples-1` |
| Third `## Examples` | `#examples-2` |
**Best practice:** Avoid duplicate heading text. Use descriptive, unique headings for each section.
### Finding the anchor for any heading
1. **Mouse users:** On GitHub, hover over any heading - a chain link icon appears to the left. Click it to update the URL with the anchor
2. **Screen reader users:** Navigate to the heading, then `Tab` once. A link button appears. Activate it and the URL in the address bar updates to show the anchor
3. **Keyboard (GitHub shortcut):** There is no direct shortcut, but you can copy the heading text, convert it to the anchor format mentally, and type it in the URL
## 26. Autolinked References - Issues, PRs, Commits, and Users
One of GitHub's most powerful features is automatic linking. When you type certain patterns in any Markdown field on GitHub, they automatically become clickable links. This is how the entire GitHub collaboration workflow connects.
### Issue and pull request references
The following table shows how to reference issues and pull requests.
| What you type | What it links to | Example |
|---|---|---|
| `#42` | Issue or PR number 42 in the current repo | "See #42 for details" |
| `GH-42` | Same as above (alternative syntax) | "Fixed in GH-42" |
| `owner/repo#42` | Issue 42 in a different repo | "Related: community-access/accessibility-agents#15" |
### User and team mentions
The following table shows how to mention users and teams.
| What you type | What it does | Example |
|---|---|---|
| `@username` | Mentions a user, sends them a notification | "Thanks @johndoe for the review" |
| `@org/team-name` | Mentions an entire team | "Cc @community-access/maintainers" |
### Commit references
The following table shows how to reference specific commits.
| What you type | What it links to | Example |
|---|---|---|
| Full SHA: `a1b2c3d4e5f6...` | Links to that commit (first 7+ chars) | "Fixed in a1b2c3d" |
| `owner/repo@SHA` | Commit in another repo | "See community-access/accessibility-agents@a1b2c3d" |
### Closing keywords in pull requests
When you include certain keywords followed by an issue reference in a PR description, merging the PR automatically closes the referenced issue:
```markdown
This PR adds alt text to all images in the documentation.
Closes #42
Fixes #43
Resolves #44
```
All of these keywords work: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`. They are case-insensitive.
### URL autolinking
GitHub automatically converts full URLs into clickable links:
```markdown
Check out https://github.com/community-access/accessibility-agents for the project.
```
> **Accessibility note:** While autolinked URLs work, they create poor link text for screen readers (the entire URL is read character by character). In documentation and issue descriptions, always use descriptive link text instead: `[Accessibility Agents repository](https://github.com/community-access/accessibility-agents)`.
## 27. HTML in Markdown
GitHub allows a subset of HTML in Markdown files. This is useful for semantic elements that do not have Markdown equivalents, advanced layout needs, and accessibility improvements.
### Keyboard key visualization
The `` element renders text in a key-cap style box:
```html
Press Ctrl+C to copy.
Press NVDA+Space to toggle Focus Mode.
```
Press Ctrl+C to copy.
Press NVDA+Space to toggle Focus Mode.
### Subscript and superscript
```html
H2O is water.
E = mc2 is Einstein's equation.
```
H2O is water.
E = mc2 is Einstein's equation.
### Centered content
```html
```
### Line breaks
```html
Line one
Line two on the next line, same paragraph.
```
### Hidden comments
```html
```
Hidden comments are useful for notes to yourself or other contributors that should not be visible to readers.
### Allowed HTML elements on GitHub
GitHub whitelists specific HTML elements for security. The following table lists the most useful allowed elements.
| Element | Purpose | Screen reader behavior |
|---|---|---|
| `` / `` | Collapsible sections | Announced as disclosure widget |
| `` | Keyboard keys | Announced as "code" or the text content |
| `` / `` | Subscript / superscript | Text read normally; some SRs announce position |
| `
` | Line break | Brief pause in reading |
| `` | Generic container | No announcement unless has role/aria |
| `![]()
` | Image with attributes | Alt text read |
| `` | Link with attributes | Link text read |
| ``, ``, ` ` | Complex table | Full table navigation |
| `` | Comment | Not read (invisible) |
### Disallowed HTML on GitHub
GitHub strips these elements for security:
- `
` | Detailed topics within a subsection |
| `##### Fine detail` | `` | Rarely used, very specific topics |
| `###### Finest detail` | `` | Almost never needed |
### Rules for accessible headings
1. **One H1 per document.** The `#` heading is your document title. Every document gets exactly one
2. **Never skip levels.** Go from `##` to `###`, never from `##` to `####`. Skipping levels breaks the document outline for screen reader users who navigate by heading
3. **Make headings descriptive.** A heading of "Section 3" tells a screen reader user nothing. A heading of "Creating Your First Pull Request" tells them exactly what the section covers
4. **Do not use bold as a heading substitute.** Writing `**My Section**` on its own line looks like a heading visually, but it is not a heading in the document structure. Screen reader users navigating by heading (`H` key in Browse Mode) will never find it
> **Screen reader note:** Screen readers let you navigate by heading level. In NVDA and JAWS, pressing `H` moves to the next heading. Pressing `1` through `6` moves to the next heading at that specific level. This is one of the most important navigation methods on any page - and it only works if the document uses real headings in the correct hierarchy.
### Alternative heading syntax (not recommended)
Markdown also supports "setext" headings where you underline text with `=` or `-` characters:
```markdown
Heading Level 1
===============
Heading Level 2
---------------
```
This only works for levels 1 and 2, and it is harder to scan visually in raw Markdown. Stick with the `#` syntax - it is clearer, supports all six levels, and is what you will see in virtually every GitHub project.
## 6. Emphasis - Bold, Italic, and Bold Italic
Emphasis changes how text is read by screen readers - it is not just visual. When text is bold or italic, well-configured screen readers can announce emphasis changes, giving the listener additional context about importance.
### Bold
Wrap text in **two asterisks** or **two underscores** on each side.
**What you type:**
```markdown
This is **bold text** using asterisks.
This is __bold text__ using underscores.
```
**What renders:**
This is **bold text** using asterisks.
This is __bold text__ using underscores.
**Best practice:** Use asterisks (`**`). Underscores can cause problems in the middle of words (like `file__name__here`), while asterisks always work.
### Italic
Wrap text in **one asterisk** or **one underscore** on each side.
**What you type:**
```markdown
This is *italic text* using asterisks.
This is _italic text_ using underscores.
```
**What renders:**
This is *italic text* using asterisks.
This is _italic text_ using underscores.
### Bold and italic combined
Wrap text in **three asterisks** on each side.
**What you type:**
```markdown
This is ***bold and italic*** text.
```
**What renders:**
This is ***bold and italic*** text.
### When to use emphasis
The following table provides guidance on when to use each type of emphasis.
| Type | When to use | Example |
|---|---|---|
| **Bold** | Key terms, important warnings, UI element names | "Click the **Submit** button" |
| *Italic* | Book or document titles, introducing new terms, gentle emphasis | "See the *Contributing Guide* for details" |
| ***Bold italic*** | Extremely rare - critical warnings only | "***Do not force push to the main branch***" |
> **Screen reader note:** NVDA can announce emphasis changes if the user enables "Report font attributes" (under Speech settings). JAWS can announce emphasis with "Say all font changes" enabled. VoiceOver announces emphasis by default on macOS. Even when emphasis is not announced, the HTML semantic structure (`` for bold, `` for italic) is available to screen readers that choose to report it.
### Emphasis inside words
Asterisks work inside words. Underscores do not (in most Markdown processors including GitHub).
```markdown
This**works**fine.
This__does__not.
```
Renders as: This**works**fine. This__does__not.
Use asterisks when you need emphasis inside a word (rare, but it comes up in technical documentation).
## 7. Strikethrough
Strikethrough text shows deleted or outdated content with a line through it. Wrap text in **two tildes** on each side.
**What you type:**
```markdown
The meeting is ~~Tuesday~~ Wednesday at 3 PM.
~~This feature has been removed.~~
```
**What renders:**
The meeting is ~~Tuesday~~ Wednesday at 3 PM.
~~This feature has been removed.~~
> **Screen reader note:** Screen reader behavior with strikethrough varies. NVDA with "Report font attributes" enabled will announce "strikethrough" before the text. JAWS may announce it as "deleted." VoiceOver does not announce strikethrough by default - the text is simply read. Because of this inconsistency, do not rely on strikethrough alone to convey meaning. Add context in the surrounding text: "The meeting was changed from ~~Tuesday~~ to Wednesday."
> **GitHub note:** Strikethrough is part of the GitHub Flavored Markdown specification. It is not in standard Markdown or CommonMark.
## 8. Lists - Ordered and Unordered
Lists are one of the most common elements in GitHub documentation. Issue descriptions, PR checklists, README instructions, step-by-step guides - they all use lists.
### Unordered lists (bullet points)
Start each line with a dash (`-`), asterisk (`*`), or plus sign (`+`) followed by a space.
**What you type:**
```markdown
- First item
- Second item
- Third item
```
**What renders:**
- First item
- Second item
- Third item
**Best practice:** Use dashes (`-`). They are the most common convention on GitHub and visually distinct from the asterisks used for bold and italic.
> **Important:** Be consistent within a single list. Do not mix `-`, `*`, and `+` in the same list - some processors handle it inconsistently, and it makes the raw Markdown harder to read.
### Ordered lists (numbered)
Start each line with a number followed by a period and a space.
**What you type:**
```markdown
1. Clone the repository
2. Create a new branch
3. Make your changes
4. Open a pull request
```
**What renders:**
1. Clone the repository
2. Create a new branch
3. Make your changes
4. Open a pull request
### A helpful trick - Markdown renumbers for you
Here is something that surprises most new users. In Markdown, the actual numbers you type do not matter for the rendered output. Markdown automatically numbers the list sequentially. This means you can use `1.` for every item:
```markdown
1. Clone the repository
1. Create a new branch
1. Make your changes
1. Open a pull request
```
This still renders as 1, 2, 3, 4. The benefit is that when you insert a new step in the middle, you do not need to renumber everything. However, for readability of the raw Markdown, many authors prefer typing the correct numbers.
> **Screen reader note:** Screen readers announce list items with their position: "list, 4 items. 1. Clone the repository. 2. Create a new branch." and so on. The semantic list structure is preserved in the HTML output, so navigation commands like `L` (next list) and `I` (next list item) work correctly in NVDA and JAWS Browse Mode.
### Starting an ordered list at a specific number
If you need a list to start at a number other than 1, use that number for the first item. All subsequent items are numbered sequentially from there:
```markdown
3. This is step three
4. This is step four
5. This is step five
```
## 9. Nested Lists and Mixed Lists
Lists can contain other lists, creating an indented hierarchy. This is essential for complex instructions, outlines, and project structures.
### Nesting unordered lists
Indent the nested items by **two or four spaces** (GitHub accepts either, but four is most reliable).
**What you type:**
```markdown
- Accessibility testing tools
- Screen readers
- NVDA (Windows, free)
- JAWS (Windows, commercial)
- VoiceOver (macOS and iOS, built-in)
- Browser extensions
- axe DevTools
- WAVE
- Documentation tools
- Markdown editors
- Static site generators
```
**What renders:**
- Accessibility testing tools
- Screen readers
- NVDA (Windows, free)
- JAWS (Windows, commercial)
- VoiceOver (macOS and iOS, built-in)
- Browser extensions
- axe DevTools
- WAVE
- Documentation tools
- Markdown editors
- Static site generators
### Nesting ordered lists
The same indentation principle applies to numbered lists:
```markdown
1. Set up your environment
1. Install Git
2. Create a GitHub account
3. Configure your screen reader
2. Learn GitHub navigation
1. Understand the page structure
2. Master keyboard shortcuts
3. Practice with the Learning Room
```
### Mixing ordered and unordered lists
You can nest an unordered list inside an ordered list and vice versa:
```markdown
1. Before the workshop
- Create a GitHub account
- Install VS Code
- Test your screen reader
2. During Day 1
- File your first issue
- Open your first pull request
3. After the workshop
- Continue contributing
- Join community discussions
```
### Adding content inside list items
List items can contain paragraphs, code blocks, and other elements. Indent the content to align with the list item text (typically four spaces):
```markdown
1. Clone the repository
Open your terminal and run the following command:
```bash
git clone https://github.com/community-access/accessibility-agents.git
```
This downloads the entire repository to your computer.
2. Create a new branch
```bash
git checkout -b fix/broken-link
```
```
> **Screen reader note:** Nested lists are announced with their nesting level. NVDA says "list, nesting level 2" when entering an inner list. This helps you understand the hierarchy by ear.
## 10. Links
Links are how you connect documents, reference issues, point to external resources, and cite sources. Getting links right is critical for accessibility - links with bad text are one of the most common accessibility failures in documentation.
### Basic link syntax
Wrap the visible link text in square brackets, followed immediately by the URL in parentheses:
```markdown
[GitHub Documentation](https://docs.github.com)
```
**Renders as:** [GitHub Documentation](https://docs.github.com)
### Links with title text
Add a title in quotes after the URL. The title appears as a tooltip on hover:
```markdown
[GitHub Documentation](https://docs.github.com "Official GitHub docs and guides")
```
> **Screen reader note:** Link titles are not reliably announced by all screen readers. Do not put critical information only in the title text. The link text itself must be descriptive.
### Writing accessible link text
This is one of the most important accessibility skills in Markdown authoring. Screen reader users often navigate by pulling up a list of all links on a page (NVDA: `NVDA+F7` then select Links; JAWS: `Insert+F7`). In this list, only the link text is shown - not the surrounding sentence. Every link must make sense on its own.
The following table contrasts bad and good link text with an explanation.
| Bad (do not do this) | Good (do this instead) | Why |
|---|---|---|
| Click [here](url) for the guide | Read the [Contributing Guide](url) | "here" means nothing out of context |
| [Read more](url) | [Read the full accessibility audit report](url) | "Read more" is ambiguous in a link list |
| [https://docs.github.com](https://docs.github.com) | [GitHub Documentation](https://docs.github.com) | Screen readers read the entire URL character by character |
| [Link](url) | [Pre-Workshop Setup instructions](url) | "Link" tells you nothing about the destination |
### Reference-style links
For documents with many links, reference-style links keep the text readable by separating the URL from the prose. You define the link target once at the bottom of the document:
```markdown
Check the [Contributing Guide][contributing] before submitting a PR.
See also the [Code of Conduct][coc] for community standards.
[contributing]: https://github.com/community-access/accessibility-agents/blob/main/CONTRIBUTING.md
[coc]: https://github.com/community-access/accessibility-agents/blob/main/CODE_OF_CONDUCT.md
```
The reference labels (`[contributing]`, `[coc]`) do not appear in the rendered output. Readers just see clean, clickable links.
### Relative links within a repository
When linking to other files in the same repository, use relative paths instead of full URLs. This way, links work on any fork or branch:
```markdown
See the [Pre-Workshop Setup](00-pre-workshop-setup.md) guide.
Jump to the [Glossary](appendix-a-glossary.md#fork) entry for "fork."
Return to the [course guide](course-guide.md).
```
### Email links
```markdown
Contact us at
```
The angle brackets tell Markdown to create a `mailto:` link:
### Autolinked URLs
GitHub automatically converts full URLs in your text into clickable links, but always prefer explicit descriptive links in prose. Bare URLs should only appear in reference sections or code examples.
## 11. Images
Images in Markdown use a syntax similar to links, with an exclamation mark (`!`) at the beginning.
### Syntax
```markdown
```
The text inside the square brackets is the **alt text** - the description that screen readers read aloud instead of displaying the image. This is the single most important accessibility attribute for images.
### Writing good alt text
The following table provides guidance on alt text for different types of images.
| Image type | Good alt text | Bad alt text |
|---|---|---|
| Screenshot of a form | "GitHub new issue form with title field, body text area, and submit button" | "screenshot" |
| Logo | "Community Access logo" | "logo.png" |
| Decorative divider | Leave alt text empty: `` | "divider" |
| Chart or graph | "Bar chart showing screen reader usage: JAWS 40%, NVDA 35%, VoiceOver 15%, Other 10%" | "chart" |
| Photo of a person | "Jamie presenting at the accessibility workshop podium" | "photo" |
### Image with a link
To make an image clickable, wrap the image syntax inside a link:
```markdown
[](https://community-access.org)
```
### Image with a title
```markdown
```
### When to use details blocks for complex images
If an image contains complex information (like an architecture diagram or a data visualization), provide a full text description in a collapsible `` block:
```markdown
Full description of the architecture diagram
The architecture has three tiers:
1. The GitHub Hub agent receives all user requests
2. The Hub routes to specialist agents (issue-tracker, pr-review, analytics)
3. Each specialist agent returns structured markdown reports
```
> **Screen reader note:** Screen readers announce images as "graphic" followed by the alt text. If alt text is empty, the image is treated as decorative and skipped. If alt text is missing entirely (no square brackets), some screen readers will announce the filename, which is not helpful. Always include the square brackets, even if empty for decorative images.
## 12. Blockquotes
Blockquotes are used for callouts, important notes, cited text, and instructor guidance throughout this course. Start each line with a `>` character followed by a space.
### Basic blockquote
**What you type:**
```markdown
> This is a blockquote. It is used to highlight important information
> or to quote someone else's text.
```
**What renders:**
> This is a blockquote. It is used to highlight important information or to quote someone else's text.
### Multi-paragraph blockquotes
Add a `>` on the blank lines between paragraphs to keep them inside the blockquote:
```markdown
> This is the first paragraph of the blockquote.
>
> This is the second paragraph. The blank line with just ">" keeps
> both paragraphs inside the same blockquote.
```
### Nested blockquotes
```markdown
> This is the outer blockquote.
>
> > This is a nested blockquote inside the first one.
>
> Back to the outer level.
```
### Blockquotes with other elements
Blockquotes can contain any Markdown element - headings, lists, code, bold, links:
```markdown
> **Important:** Before starting the exercise:
>
> 1. Make sure you are on the `main` branch
> 2. Pull the latest changes: `git pull origin main`
> 3. Read the [challenge description](challenges.md) first
>
> If you get stuck, ask in the issue thread.
```
> **Screen reader note:** Screen readers announce the beginning and end of a blockquote. NVDA says "block quote" when entering and "out of block quote" when leaving. Content inside is read normally. This means blockquotes are an excellent way to highlight important information for all users.
### How we use blockquotes in this course
Throughout this workshop, blockquotes serve specific purposes:
- **Screen reader notes:** Tips specific to assistive technology users
- **Learning Room connections:** How the current topic connects to the practice repo
- **Important warnings:** Critical information that could prevent errors
- **Instructor guidance:** Notes from the facilitator about pacing or approach
## 13. Inline Code and Code Blocks
Code formatting is essential on GitHub. You will use it for command-line instructions, file names, configuration values, keyboard shortcuts, and actual source code.
### Inline code
Wrap text in single backticks (`` ` ``) to format it as code within a sentence.
**What you type:**
```markdown
Run `git status` to see which files have changed.
The configuration file is `package.json`.
Press `Ctrl+Shift+P` to open the Command Palette.
```
**What renders:**
Run `git status` to see which files have changed.
The configuration file is `package.json`.
Press `Ctrl+Shift+P` to open the Command Palette.
**When to use inline code:**
- Command names: `git clone`, `npm install`
- File names: `README.md`, `CONTRIBUTING.md`
- Keyboard shortcuts: `Ctrl+C`, `Alt+Tab`
- Variable or function names: `userName`, `getElementById()`
- Configuration values: `true`, `false`, `null`
- Branch names: `main`, `feature/add-alt-text`
### Code blocks (fenced)
For multi-line code, wrap it in triple backticks (` ``` `) on their own lines:
**What you type:**
````markdown
```
This is a code block.
All formatting is preserved exactly.
Indentation stays.
**Bold does not render** - it stays as plain text.
```
````
### Code blocks with syntax highlighting
Add a language identifier right after the opening triple backticks to enable syntax highlighting:
````markdown
```python
def greet(name: str) -> str:
"""Return a greeting for the given name."""
return f"Hello, {name}! Welcome to the workshop."
```
````
```python
def greet(name: str) -> str:
"""Return a greeting for the given name."""
return f"Hello, {name}! Welcome to the workshop."
```
The following table lists language identifiers you will encounter most often in this workshop.
| Language | Identifier | Used for |
|---|---|---|
| Python | `python` | Scripts, automation, Copilot examples |
| Bash / Shell | `bash` or `shell` | Terminal commands, Git operations |
| YAML | `yaml` | GitHub Actions workflows, issue templates |
| JSON | `json` | Configuration files, API responses |
| JavaScript | `javascript` or `js` | Web scripts, Node.js |
| HTML | `html` | Web page structure |
| CSS | `css` | Styling |
| Markdown | `markdown` | Markdown examples (yes, you can format Markdown inside Markdown) |
| Plain text | `text` or `plaintext` | When no highlighting is needed |
| Diff | `diff` | Showing code changes (additions in green, removals in red) |
### Showing diffs in code blocks
The `diff` language identifier highlights additions and removals:
````markdown
```diff
- old line that was removed
+ new line that was added
unchanged context line
```
````
```diff
- old line that was removed
+ new line that was added
unchanged context line
```
### Code blocks inside list items
Indent the code block to align with the list item text:
```markdown
1. Create a new branch:
```bash
git checkout -b feature/my-change
```
2. Make your changes and stage them:
```bash
git add .
```
```
### How to show literal backticks
If your code contains backticks, use more backticks for the fence:
`````markdown
````markdown
```python
print("Hello")
```
````
`````
Use four backticks to wrap content that contains triple backticks. Use five to wrap content that contains four. You get the idea.
> **Screen reader note:** Code blocks are announced as "code" regions. Screen readers read the content character by character when navigating with arrow keys, and as whole lines when navigating with `Down Arrow`. Syntax highlighting is visual only - it does not affect what screen readers announce. The code text is equally accessible whether highlighted or not.
## 14. Horizontal Rules
A horizontal rule creates a thematic break between sections - a visual line across the page. Use three or more dashes, asterisks, or underscores on a line by themselves.
**What you type (any of these work):**
```markdown
***
___
```
**Best practice:** Use `---` (three dashes). It is the most common convention and looks clean in raw Markdown. Always put a blank line before and after the rule.
> **Screen reader note:** Horizontal rules are announced as "separator" in NVDA, "horizontal separator" in JAWS, and "horizontal rule" in VoiceOver. They are useful as navigation landmarks - screen reader users can move between them, but do not overuse them. Headings are a better way to structure a document.
## 15. Escaping Special Characters
Many characters have special meaning in Markdown. If you want to display them as literal characters instead, put a backslash (`\`) before them.
### Characters that can be escaped
The following table lists every character that can be escaped in Markdown.
| Character | Name | Markdown meaning |
|---|---|---|
| `\` | Backslash | Escape character itself |
| `` ` `` | Backtick | Inline code |
| `*` | Asterisk | Bold, italic, or list item |
| `_` | Underscore | Bold or italic |
| `{}` | Curly braces | Used in some extensions |
| `[]` | Square brackets | Link text |
| `()` | Parentheses | Link URL |
| `#` | Hash | Heading |
| `+` | Plus sign | Unordered list |
| `-` | Dash | Unordered list or horizontal rule |
| `.` | Period | Ordered list (after a number) |
| `!` | Exclamation mark | Image |
| `|` | Pipe | Table column separator |
| `~` | Tilde | Strikethrough |
### Examples
**What you type:**
```markdown
This asterisk is literal: \*not bold\*
This hash is literal: \# not a heading
Show a pipe character: \|
```
**What renders:**
This asterisk is literal: \*not bold\*
This hash is literal: \# not a heading
Show a pipe character: \|
## 16. Tables
Tables organize data into rows and columns. They are used extensively on GitHub for comparison charts, reference data, settings documentation, and checklists.
### Basic table syntax
```markdown
| Name | Role | Platform |
|---|---|---|
| NVDA | Screen reader | Windows |
| JAWS | Screen reader | Windows |
| VoiceOver | Screen reader | macOS / iOS |
| TalkBack | Screen reader | Android |
```
**What renders:**
| Name | Role | Platform |
|---|---|---|
| NVDA | Screen reader | Windows |
| JAWS | Screen reader | Windows |
| VoiceOver | Screen reader | macOS / iOS |
| TalkBack | Screen reader | Android |
### How table syntax works
- The **first row** is always the header row
- The **second row** contains dashes (`---`) that separate the header from the data. You need at least three dashes per column
- Each **subsequent row** is a data row
- Columns are separated by pipe characters (`|`)
- Leading and trailing pipes are optional but recommended for readability
### Column alignment
Add colons (`:`) to the separator row to control text alignment:
```markdown
| Left aligned | Center aligned | Right aligned |
|:---|:---:|---:|
| Text | Text | Text |
| Longer text here | Centered text | 42 |
```
| Left aligned | Center aligned | Right aligned |
|:---|:---:|---:|
| Text | Text | Text |
| Longer text here | Centered text | 42 |
- `:---` = left aligned (default)
- `:---:` = center aligned
- `---:` = right aligned
### Formatting inside table cells
You can use inline formatting within table cells:
```markdown
| Feature | Status | Notes |
|---|---|---|
| **Bold text** | `code` | Works [with links](url) too |
| *Italic text* | ~~struck~~ | Use any inline formatting |
```
### Accessibility considerations for tables
1. **Always include a description before the table.** Add a one-sentence summary immediately above the table explaining what it contains. Screen reader users hear the table structure (rows and columns) but benefit from knowing what the table is about before entering it
2. **Keep tables simple.** Tables with more than 5-6 columns become difficult to navigate with a screen reader. Consider splitting wide tables into multiple narrower tables
3. **Use tables for data, not layout.** If you are using a table just to arrange content side by side, use a list instead
4. **Make the header row descriptive.** The header cell is announced before each data cell when navigating by column, so "Platform" is better than "Col 3"
> **Screen reader note:** Screen readers navigate tables with `Ctrl+Alt+Arrow` keys (NVDA and JAWS). `Ctrl+Alt+Right` moves to the next column. `Ctrl+Alt+Down` moves to the next row. The column header is announced each time you move to a new column. Table mode is entered automatically when the screen reader encounters a table.
### When not to use a table
If your "table" has only two columns where the first is a label and the second is a value, consider using a definition-style list or bold labels instead:
```markdown
**Name:** Community Access
**Founded:** 2020
**Mission:** Empowering blind and low vision technology professionals
```
This is often easier to read with a screen reader than a two-column table.
## Part 2 - GitHub Flavored Markdown (GFM)
## 17. What Is GitHub Flavored Markdown?
GitHub Flavored Markdown (GFM) is GitHub's own superset of standard Markdown. It takes everything from the CommonMark specification (the modern standard for Markdown) and adds features specifically designed for software collaboration: tables, task lists, strikethrough, autolinked references, alert blocks, Mermaid diagrams, math expressions, and footnotes.
Everything you learned in Part 1 works everywhere Markdown is supported. Everything in Part 2 is specific to GitHub (and some other platforms that have adopted GFM).
### Where GFM works
The following table shows where GFM is supported.
| Location | GFM supported | Notes |
|---|---|---|
| `.md` files in repos | Yes | Any Markdown file rendered on GitHub |
| Issue descriptions | Yes | Full GFM with autolinks |
| Issue comments | Yes | Full GFM with autolinks |
| Pull request descriptions | Yes | Full GFM with autolinks |
| Pull request comments | Yes | Full GFM with autolinks |
| Discussion posts | Yes | Full GFM with autolinks |
| Wiki pages | Yes | Full GFM |
| Gists | Yes | Full GFM |
| Commit messages | Partial | Basic formatting, autolinks - no Mermaid or math |
| GitHub Pages (Jekyll) | Depends | Jekyll has its own Markdown processor |
| VS Code preview | Mostly | Supports most GFM; Mermaid requires an extension |
## 18. Alert and Callout Blocks
GitHub introduced **alert blocks** in 2023. They render as colored, bordered callout boxes - great for emphasizing warnings, tips, or critical information. You will see these throughout this course to highlight screen reader notes, important warnings, and tips.
### Syntax
```markdown
> [!NOTE]
> Useful information that users should know, even when skimming.
> [!TIP]
> Helpful advice for doing something better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```
### How to write them
1. Start a blockquote with `>`
2. The first line must be exactly `> [!TYPE]` where TYPE is one of: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`
3. All subsequent lines start with `>` and a space, just like a regular blockquote
4. You can include any Markdown inside the alert: lists, code, links, bold
### Choosing the right alert type
The following table describes each alert type and when to use it.
| Type | Color | When to use | Example |
|---|---|---|---|
| `NOTE` | Blue | Supplementary information the reader should know | Additional context about a feature |
| `TIP` | Green | Best practice or shortcut | "Use `Ctrl+Shift+P` for faster access" |
| `IMPORTANT` | Purple | Something the reader absolutely must know | Required configuration step |
| `WARNING` | Yellow | A potential problem or non-obvious risk | "This changes are not reversible after merge" |
| `CAUTION` | Red | An action that could cause irreversible harm | "This deletes all branches and cannot be undone" |
### Multi-line alert with formatting
```markdown
> [!WARNING]
> **Do not skip the pre-workshop setup.**
>
> If you arrive without a configured environment, you will spend the first
> hour catching up while others are working on challenges. Complete
> [Chapter 0](00-pre-workshop-setup.md) before Day 1.
>
> Checklist:
>
> - Git installed
> - GitHub account created
> - Screen reader configured for GitHub
```
### Screen Reader Behavior
Alert blocks render as `` elements with an SVG icon and a strong heading. Screen readers read:
- NVDA/JAWS: announces `blockquote` role, then reads the type label ("Note", "Warning") then the content
- VoiceOver: reads the type as bold text then the content
- The colored icon is decorative (`aria-hidden`); it does not add information beyond the type label
## 19. Collapsible Sections with Details and Summary
The `` and `` HTML elements create collapsible sections. They are one of the most useful tools for keeping long documents, issue reports, and PRs manageable - hiding optional content until the reader chooses to expand it.
### Basic syntax
```markdown
Click to expand: Full error log
Content that is hidden until the user expands this section.
You can put **any Markdown** in here:
- Lists
- Code blocks
- Links
- Tables
```
### Important formatting rules
1. **Blank line after ``.** Put a blank line between the closing `
` tag and your Markdown content. Without it, Markdown formatting inside may not render
2. **Blank line before `
`.** Same principle at the end
3. The `` text should be descriptive - it is the only thing visible when collapsed
### Real-world uses in this workshop
The following list describes common uses for collapsible sections.
- **Bug reports in issues:** Collapse the full stack trace so the issue body stays readable
- **Long configuration blocks:** Let readers expand the full YAML only if they need it
- **Exercise solutions:** Collapse the answer so learners try the exercise first
- **Screen reader guidance blocks:** Throughout this course, some sections collapse detailed assistive technology instructions so sighted users see a cleaner page while screen reader users can easily expand them
- **Meeting notes:** Collapse detailed minutes while showing the summary
### Nesting details inside details
```markdown
Operating system instructions
Windows
1. Open PowerShell
2. Run `git --version`
macOS
1. Open Terminal
2. Run `git --version`
```
### Details sections that start open
Add the `open` attribute to have the section expanded by default:
```markdown
Currently known issues
- Checkbox toggle requires Focus Mode in NVDA
- Alert blocks do not render in email notifications
```
### Screen Reader Behavior
The `` element renders as a disclosure widget:
- NVDA: announces "button collapsed" for the `` - press `Enter` or `Space` to expand
- JAWS: announces "collapsed" - press `Enter` on the summary to expand
- VoiceOver: announces "collapsed, button" - press `VO+Space` to activate
**After expanding:** The content is immediately readable. Screen readers announce "button expanded" for the summary. No page reload occurs.
## 20. Task List Checkboxes
Task lists in GitHub issues and PRs render as **real interactive checkboxes**. Anyone with write access to the repository can check and uncheck them directly in the rendered view without editing the Markdown.
### Syntax
```markdown
- [x] Color contrast verified (4.5:1 minimum for body text)
- [x] Keyboard navigation tested
- [ ] Screen reader tested with NVDA
- [ ] Screen reader tested with JAWS
- [ ] Screen reader tested with VoiceOver
- [ ] Alt text provided for all images
- [ ] Focus indicators visible
```
### How to write them
1. Start with a list item marker (`-`, `*`, or `+`) and a space
2. Add `[x]` for a checked box or `[ ]` (with a space inside) for an unchecked box
3. Add a space, then the task description
4. The description should be meaningful - "Test NVDA" is better than "Item 3"
### What makes task lists special on GitHub
- **Progress tracking:** In issues, GitHub shows a progress bar: "2 of 7 tasks completed"
- **Click to check:** In the rendered view, users with triage or write permissions can click to toggle checkboxes without editing the comment
- **Linked issues:** You can reference issues in a task: `- [ ] Fix #42` - the task shows the issue title and its open/closed state
- **PR templates:** Task lists in PR templates create checklists that authors fill out before requesting review
### Example - pull request checklist
```markdown
## Pre-review checklist
- [x] Changes are limited to the files listed in the issue
- [x] All new images have descriptive alt text
- [ ] Screen reader tested the changes with NVDA
- [ ] No heading levels are skipped
- [ ] All links use descriptive text (not "click here")
```
### Screen Reader Interaction
In Browse Mode, checkboxes are read as `checkbox, not checked` or `checkbox, checked`.
**To toggle a task list checkbox:**
- NVDA: Press `NVDA+Space` to enter Focus Mode, then `Tab` to find the checkbox, then `Space` to toggle it
- JAWS: `Tab` to the checkbox, then `Space` to toggle
- VoiceOver: `VO+Space` on the checkbox element
## 21. Syntax Highlighting in Fenced Code Blocks
We covered basic code blocks in Section 13. This section covers the GitHub-specific syntax highlighting that makes code blocks more readable for sighted users.
### How it works
Add a language identifier right after the opening triple backticks. GitHub uses Linguist to apply syntax highlighting with appropriate colors for keywords, strings, comments, and other language constructs.
````markdown
```python
def check_accessibility(element):
"""Check if an element has proper ARIA attributes."""
if not element.get("aria-label") and not element.get("aria-labelledby"):
return "Missing accessible name"
return "Accessible"
```
````
### Complete list of commonly used language identifiers
The following table lists the language identifiers you are most likely to use.
| Identifier | Language | Example use in this workshop |
|---|---|---|
| `python` | Python | Scripts, automation, challenge code |
| `bash` or `shell` | Bash/Shell | Terminal commands, Git operations |
| `yaml` or `yml` | YAML | GitHub Actions, issue templates |
| `json` | JSON | Configuration, API responses |
| `javascript` or `js` | JavaScript | Web scripts |
| `typescript` or `ts` | TypeScript | Typed JavaScript |
| `html` | HTML | Web page structure |
| `css` | CSS | Styling |
| `markdown` or `md` | Markdown | Documenting Markdown syntax |
| `diff` | Diff | Code change comparison |
| `text` or `plaintext` | None | No highlighting needed |
| `ruby` | Ruby | Ruby scripts |
| `go` | Go | Go programs |
| `rust` | Rust | Rust programs |
| `java` | Java | Java programs |
| `csharp` or `cs` | C# | .NET programs |
| `sql` | SQL | Database queries |
| `dockerfile` | Dockerfile | Container configuration |
| `xml` | XML | Structured data |
| `toml` | TOML | Configuration (Rust, Python) |
| `ini` | INI | Configuration files |
| `powershell` or `ps1` | PowerShell | Windows automation |
If no language is specified, the code block renders as plain monospaced text with no highlighting.
### Screen Reader Note
Syntax highlighting is visual only - screen readers read the code text without announcing color changes. The code block itself is announced as a `code` region. This means the text content of well-written code is equally accessible whether highlighted or not. Variable names, function names, and comments are the real accessibility of code - not colors.
## 22. Mermaid Diagrams
GitHub renders [Mermaid.js](https://mermaid.js.org/) diagrams inline when you use a `mermaid` fenced code block. They are common in READMEs, PRs, and documentation to illustrate architecture, flows, and relationships.
### Syntax
````markdown
```mermaid
flowchart LR
A[Fork repo] --> B[Clone locally]
B --> C[Create branch]
C --> D[Make changes]
D --> E[Push branch]
E --> F[Open PR]
F --> G{Review passed?}
G -- Yes --> H[Merge]
G -- No --> D
```
````
### Common diagram types
The following table lists the Mermaid diagram types you are most likely to encounter on GitHub.
| Type | Keyword | Use case |
|---|---|---|
| Flowchart | `flowchart LR` or `flowchart TD` | Process flows, decision trees |
| Sequence diagram | `sequenceDiagram` | API calls, user interactions |
| Entity-Relationship | `erDiagram` | Database schemas |
| Class diagram | `classDiagram` | Code architecture |
| Gantt chart | `gantt` | Project schedules |
| Git graph | `gitGraph` | Branch and merge visualization |
| Pie chart | `pie` | Data distribution |
### Accessibility limitation - critical
> **Important:** Mermaid diagrams render as SVG images. GitHub does not auto-generate alt text for them. Screen readers will typically either skip them entirely or announce generic SVG container information that is not useful.
This means **every Mermaid diagram is invisible to screen reader users unless you provide a text alternative.**
### How to make Mermaid diagrams accessible
Always follow this pattern:
1. Write a **text description** before the diagram that conveys all the same information
2. Optionally, duplicate the information as a numbered list or table
3. Consider wrapping the Mermaid source in a `` block if the text description is sufficient
**Example - accessible Mermaid usage:**
````markdown
The PR workflow follows these steps: fork the repository, clone
your fork locally, create a feature branch, make your changes and commit,
push the branch to your fork, open a pull request, address review feedback,
and merge when approved.
1. Fork the repository
2. Clone your fork locally
3. Create a feature branch
4. Make your changes and commit
5. Push the branch to your fork
6. Open a pull request
7. Address review feedback
8. Merge when approved
Diagram source (Mermaid)
```mermaid
flowchart LR
Fork --> Clone --> Branch --> Commit --> Push --> PR --> Review --> Merge
```
````
This way, screen reader users get the full information from the text and numbered list. Sighted users can also expand the Mermaid diagram for a visual representation.
## 23. Math Expressions with LaTeX
GitHub renders LaTeX math expressions using MathJax. This is common in data science, research, and algorithm documentation.
### Inline math
Use single `$` delimiters for math within a sentence:
```markdown
The formula is $e = mc^2$ where $c$ is the speed of light.
```
**Renders as:** The formula is $e = mc^2$ where $c$ is the speed of light.
### Block math
Use `$$` delimiters for display-style (centered, larger) math on their own lines:
```markdown
$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$
```
### Common LaTeX patterns
The following table shows some LaTeX patterns you might encounter.
| What you want | LaTeX | Rendered |
|---|---|---|
| Superscript | `$x^2$` | $x^2$ |
| Subscript | `$x_i$` | $x_i$ |
| Fraction | `$\frac{a}{b}$` | $\frac{a}{b}$ |
| Square root | `$\sqrt{x}$` | $\sqrt{x}$ |
| Greek letter | `$\alpha, \beta, \gamma$` | $\alpha, \beta, \gamma$ |
| Summation | `$\sum_{i=1}^{n}$` | $\sum_{i=1}^{n}$ |
| Not equal | `$\neq$` | $\neq$ |
| Less or equal | `$\leq$` | $\leq$ |
### Screen Reader Note
Math expressions rendered by MathJax include `aria-label` attributes with the spoken form of the equation. Screen readers should announce the math correctly, but accuracy varies:
- NVDA with Firefox or Chrome: reads MathML fairly well
- JAWS: reads the aria-label text
- VoiceOver: reads the aria-label text
**Best practice:** If writing documentation for an accessibility-focused audience, supplement complex equations with a plain English description:
```markdown
The sum of all values from 1 to n equals n times n+1 divided by 2:
$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$
```
## 24. Footnotes
GitHub supports Markdown footnotes, which render as superscript numbers that link to references at the bottom of the document. They are useful for citations, additional context, and references that would interrupt the flow of the main text.
### Syntax
```markdown
This technique improves screen reader navigation significantly.[^1]
You can also use named footnotes for clarity.[^accessibility-note]
[^1]: Based on the WebAIM Screen Reader Survey, 2024.
[^accessibility-note]: See WCAG 2.2 Success Criterion 2.4.3 for focus order requirements.
```
### How they work
1. In your text, add `[^identifier]` where you want the footnote reference to appear
2. Anywhere in the document (typically at the bottom), define the footnote with `[^identifier]: Your footnote text`
3. GitHub renders the reference as a superscript number that links to the definition
4. The definition includes a back-link that returns to the reference location
### Footnote identifiers
- You can use numbers: `[^1]`, `[^2]`, `[^3]`
- You can use descriptive names: `[^webaim-survey]`, `[^wcag-reference]`
- Descriptive names make the raw Markdown more readable but render as sequential numbers
### Multi-line footnotes
Indent continuation lines with two spaces:
```markdown
[^long-note]: This is a longer footnote that spans multiple paragraphs.
The second paragraph of the footnote is indented with two spaces.
You can even include code: `git status`
```
### Screen Reader Behavior
- The footnote reference is a link (`` element) announcing its number
- NVDA: "superscript, 1, link"
- JAWS: "link, 1"
- VoiceOver: "link, footnote 1"
- The back-link at the definition reads "return to footnote reference"
- Activating the footnote link jumps focus to the definition; activating the back-link returns focus to the original location
## 25. Linked Heading Anchors and Tables of Contents
Every heading in a GitHub Markdown file automatically gets an anchor ID. You can link to any heading from anywhere - within the same document, from another file, or from an issue or PR.
### How GitHub generates anchor IDs
GitHub converts the heading text to an anchor ID by:
1. Converting to lowercase
2. Replacing spaces with hyphens
3. Removing most punctuation (except hyphens)
4. Removing leading and trailing whitespace
The following table shows example headings and their generated anchors.
| Heading text | Generated anchor |
|---|---|
| `# Introduction` | `#introduction` |
| `## Getting Started` | `#getting-started` |
| `### VS Code: Setup & Accessibility Basics` | `#vs-code-setup--accessibility-basics` |
| `## 1. First Steps` | `#1-first-steps` |
| `## What Is a PR?` | `#what-is-a-pr` |
### Linking to a heading in the same document
```markdown
See the [Tables](#16-tables) section for details on formatting data.
Return to the [Table of Contents](#table-of-contents).
```
### Linking to a heading in another file
```markdown
See the [Pre-Workshop Setup guide](00-pre-workshop-setup.md#step-1---create-a-github-account).
```
### Building a table of contents
You can build a manual table of contents using heading anchor links:
```markdown
## Table of Contents
1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Usage](#usage)
5. [Contributing](#contributing)
```
### Duplicate headings
If a document has two headings with the same text, GitHub appends `-1`, `-2`, and so on to the duplicate anchors:
| Heading | Anchor |
|---|---|
| First `## Examples` | `#examples` |
| Second `## Examples` | `#examples-1` |
| Third `## Examples` | `#examples-2` |
**Best practice:** Avoid duplicate heading text. Use descriptive, unique headings for each section.
### Finding the anchor for any heading
1. **Mouse users:** On GitHub, hover over any heading - a chain link icon appears to the left. Click it to update the URL with the anchor
2. **Screen reader users:** Navigate to the heading, then `Tab` once. A link button appears. Activate it and the URL in the address bar updates to show the anchor
3. **Keyboard (GitHub shortcut):** There is no direct shortcut, but you can copy the heading text, convert it to the anchor format mentally, and type it in the URL
## 26. Autolinked References - Issues, PRs, Commits, and Users
One of GitHub's most powerful features is automatic linking. When you type certain patterns in any Markdown field on GitHub, they automatically become clickable links. This is how the entire GitHub collaboration workflow connects.
### Issue and pull request references
The following table shows how to reference issues and pull requests.
| What you type | What it links to | Example |
|---|---|---|
| `#42` | Issue or PR number 42 in the current repo | "See #42 for details" |
| `GH-42` | Same as above (alternative syntax) | "Fixed in GH-42" |
| `owner/repo#42` | Issue 42 in a different repo | "Related: community-access/accessibility-agents#15" |
### User and team mentions
The following table shows how to mention users and teams.
| What you type | What it does | Example |
|---|---|---|
| `@username` | Mentions a user, sends them a notification | "Thanks @johndoe for the review" |
| `@org/team-name` | Mentions an entire team | "Cc @community-access/maintainers" |
### Commit references
The following table shows how to reference specific commits.
| What you type | What it links to | Example |
|---|---|---|
| Full SHA: `a1b2c3d4e5f6...` | Links to that commit (first 7+ chars) | "Fixed in a1b2c3d" |
| `owner/repo@SHA` | Commit in another repo | "See community-access/accessibility-agents@a1b2c3d" |
### Closing keywords in pull requests
When you include certain keywords followed by an issue reference in a PR description, merging the PR automatically closes the referenced issue:
```markdown
This PR adds alt text to all images in the documentation.
Closes #42
Fixes #43
Resolves #44
```
All of these keywords work: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`. They are case-insensitive.
### URL autolinking
GitHub automatically converts full URLs into clickable links:
```markdown
Check out https://github.com/community-access/accessibility-agents for the project.
```
> **Accessibility note:** While autolinked URLs work, they create poor link text for screen readers (the entire URL is read character by character). In documentation and issue descriptions, always use descriptive link text instead: `[Accessibility Agents repository](https://github.com/community-access/accessibility-agents)`.
## 27. HTML in Markdown
GitHub allows a subset of HTML in Markdown files. This is useful for semantic elements that do not have Markdown equivalents, advanced layout needs, and accessibility improvements.
### Keyboard key visualization
The `` element renders text in a key-cap style box:
```html
Press Ctrl+C to copy.
Press NVDA+Space to toggle Focus Mode.
```
Press Ctrl+C to copy.
Press NVDA+Space to toggle Focus Mode.
### Subscript and superscript
```html
H2O is water.
E = mc2 is Einstein's equation.
```
H2O is water.
E = mc2 is Einstein's equation.
### Centered content
```html
```
### Line breaks
```html
Line one
Line two on the next line, same paragraph.
```
### Hidden comments
```html
```
Hidden comments are useful for notes to yourself or other contributors that should not be visible to readers.
### Allowed HTML elements on GitHub
GitHub whitelists specific HTML elements for security. The following table lists the most useful allowed elements.
| Element | Purpose | Screen reader behavior |
|---|---|---|
| `` / `` | Collapsible sections | Announced as disclosure widget |
| `` | Keyboard keys | Announced as "code" or the text content |
| `` / `` | Subscript / superscript | Text read normally; some SRs announce position |
| `
` | Line break | Brief pause in reading |
| `` | Generic container | No announcement unless has role/aria |
| `![]()
` | Image with attributes | Alt text read |
| `` | Link with attributes | Link text read |
| ``, ``, ` ` | Complex table | Full table navigation |
| `` | Comment | Not read (invisible) |
### Disallowed HTML on GitHub
GitHub strips these elements for security:
- `
` | Almost never needed |
### Rules for accessible headings
1. **One H1 per document.** The `#` heading is your document title. Every document gets exactly one
2. **Never skip levels.** Go from `##` to `###`, never from `##` to `####`. Skipping levels breaks the document outline for screen reader users who navigate by heading
3. **Make headings descriptive.** A heading of "Section 3" tells a screen reader user nothing. A heading of "Creating Your First Pull Request" tells them exactly what the section covers
4. **Do not use bold as a heading substitute.** Writing `**My Section**` on its own line looks like a heading visually, but it is not a heading in the document structure. Screen reader users navigating by heading (`H` key in Browse Mode) will never find it
> **Screen reader note:** Screen readers let you navigate by heading level. In NVDA and JAWS, pressing `H` moves to the next heading. Pressing `1` through `6` moves to the next heading at that specific level. This is one of the most important navigation methods on any page - and it only works if the document uses real headings in the correct hierarchy.
### Alternative heading syntax (not recommended)
Markdown also supports "setext" headings where you underline text with `=` or `-` characters:
```markdown
Heading Level 1
===============
Heading Level 2
---------------
```
This only works for levels 1 and 2, and it is harder to scan visually in raw Markdown. Stick with the `#` syntax - it is clearer, supports all six levels, and is what you will see in virtually every GitHub project.
## 6. Emphasis - Bold, Italic, and Bold Italic
Emphasis changes how text is read by screen readers - it is not just visual. When text is bold or italic, well-configured screen readers can announce emphasis changes, giving the listener additional context about importance.
### Bold
Wrap text in **two asterisks** or **two underscores** on each side.
**What you type:**
```markdown
This is **bold text** using asterisks.
This is __bold text__ using underscores.
```
**What renders:**
This is **bold text** using asterisks.
This is __bold text__ using underscores.
**Best practice:** Use asterisks (`**`). Underscores can cause problems in the middle of words (like `file__name__here`), while asterisks always work.
### Italic
Wrap text in **one asterisk** or **one underscore** on each side.
**What you type:**
```markdown
This is *italic text* using asterisks.
This is _italic text_ using underscores.
```
**What renders:**
This is *italic text* using asterisks.
This is _italic text_ using underscores.
### Bold and italic combined
Wrap text in **three asterisks** on each side.
**What you type:**
```markdown
This is ***bold and italic*** text.
```
**What renders:**
This is ***bold and italic*** text.
### When to use emphasis
The following table provides guidance on when to use each type of emphasis.
| Type | When to use | Example |
|---|---|---|
| **Bold** | Key terms, important warnings, UI element names | "Click the **Submit** button" |
| *Italic* | Book or document titles, introducing new terms, gentle emphasis | "See the *Contributing Guide* for details" |
| ***Bold italic*** | Extremely rare - critical warnings only | "***Do not force push to the main branch***" |
> **Screen reader note:** NVDA can announce emphasis changes if the user enables "Report font attributes" (under Speech settings). JAWS can announce emphasis with "Say all font changes" enabled. VoiceOver announces emphasis by default on macOS. Even when emphasis is not announced, the HTML semantic structure (`` for bold, `` for italic) is available to screen readers that choose to report it.
### Emphasis inside words
Asterisks work inside words. Underscores do not (in most Markdown processors including GitHub).
```markdown
This**works**fine.
This__does__not.
```
Renders as: This**works**fine. This__does__not.
Use asterisks when you need emphasis inside a word (rare, but it comes up in technical documentation).
## 7. Strikethrough
Strikethrough text shows deleted or outdated content with a line through it. Wrap text in **two tildes** on each side.
**What you type:**
```markdown
The meeting is ~~Tuesday~~ Wednesday at 3 PM.
~~This feature has been removed.~~
```
**What renders:**
The meeting is ~~Tuesday~~ Wednesday at 3 PM.
~~This feature has been removed.~~
> **Screen reader note:** Screen reader behavior with strikethrough varies. NVDA with "Report font attributes" enabled will announce "strikethrough" before the text. JAWS may announce it as "deleted." VoiceOver does not announce strikethrough by default - the text is simply read. Because of this inconsistency, do not rely on strikethrough alone to convey meaning. Add context in the surrounding text: "The meeting was changed from ~~Tuesday~~ to Wednesday."
> **GitHub note:** Strikethrough is part of the GitHub Flavored Markdown specification. It is not in standard Markdown or CommonMark.
## 8. Lists - Ordered and Unordered
Lists are one of the most common elements in GitHub documentation. Issue descriptions, PR checklists, README instructions, step-by-step guides - they all use lists.
### Unordered lists (bullet points)
Start each line with a dash (`-`), asterisk (`*`), or plus sign (`+`) followed by a space.
**What you type:**
```markdown
- First item
- Second item
- Third item
```
**What renders:**
- First item
- Second item
- Third item
**Best practice:** Use dashes (`-`). They are the most common convention on GitHub and visually distinct from the asterisks used for bold and italic.
> **Important:** Be consistent within a single list. Do not mix `-`, `*`, and `+` in the same list - some processors handle it inconsistently, and it makes the raw Markdown harder to read.
### Ordered lists (numbered)
Start each line with a number followed by a period and a space.
**What you type:**
```markdown
1. Clone the repository
2. Create a new branch
3. Make your changes
4. Open a pull request
```
**What renders:**
1. Clone the repository
2. Create a new branch
3. Make your changes
4. Open a pull request
### A helpful trick - Markdown renumbers for you
Here is something that surprises most new users. In Markdown, the actual numbers you type do not matter for the rendered output. Markdown automatically numbers the list sequentially. This means you can use `1.` for every item:
```markdown
1. Clone the repository
1. Create a new branch
1. Make your changes
1. Open a pull request
```
This still renders as 1, 2, 3, 4. The benefit is that when you insert a new step in the middle, you do not need to renumber everything. However, for readability of the raw Markdown, many authors prefer typing the correct numbers.
> **Screen reader note:** Screen readers announce list items with their position: "list, 4 items. 1. Clone the repository. 2. Create a new branch." and so on. The semantic list structure is preserved in the HTML output, so navigation commands like `L` (next list) and `I` (next list item) work correctly in NVDA and JAWS Browse Mode.
### Starting an ordered list at a specific number
If you need a list to start at a number other than 1, use that number for the first item. All subsequent items are numbered sequentially from there:
```markdown
3. This is step three
4. This is step four
5. This is step five
```
## 9. Nested Lists and Mixed Lists
Lists can contain other lists, creating an indented hierarchy. This is essential for complex instructions, outlines, and project structures.
### Nesting unordered lists
Indent the nested items by **two or four spaces** (GitHub accepts either, but four is most reliable).
**What you type:**
```markdown
- Accessibility testing tools
- Screen readers
- NVDA (Windows, free)
- JAWS (Windows, commercial)
- VoiceOver (macOS and iOS, built-in)
- Browser extensions
- axe DevTools
- WAVE
- Documentation tools
- Markdown editors
- Static site generators
```
**What renders:**
- Accessibility testing tools
- Screen readers
- NVDA (Windows, free)
- JAWS (Windows, commercial)
- VoiceOver (macOS and iOS, built-in)
- Browser extensions
- axe DevTools
- WAVE
- Documentation tools
- Markdown editors
- Static site generators
### Nesting ordered lists
The same indentation principle applies to numbered lists:
```markdown
1. Set up your environment
1. Install Git
2. Create a GitHub account
3. Configure your screen reader
2. Learn GitHub navigation
1. Understand the page structure
2. Master keyboard shortcuts
3. Practice with the Learning Room
```
### Mixing ordered and unordered lists
You can nest an unordered list inside an ordered list and vice versa:
```markdown
1. Before the workshop
- Create a GitHub account
- Install VS Code
- Test your screen reader
2. During Day 1
- File your first issue
- Open your first pull request
3. After the workshop
- Continue contributing
- Join community discussions
```
### Adding content inside list items
List items can contain paragraphs, code blocks, and other elements. Indent the content to align with the list item text (typically four spaces):
```markdown
1. Clone the repository
Open your terminal and run the following command:
```bash
git clone https://github.com/community-access/accessibility-agents.git
```
This downloads the entire repository to your computer.
2. Create a new branch
```bash
git checkout -b fix/broken-link
```
```
> **Screen reader note:** Nested lists are announced with their nesting level. NVDA says "list, nesting level 2" when entering an inner list. This helps you understand the hierarchy by ear.
## 10. Links
Links are how you connect documents, reference issues, point to external resources, and cite sources. Getting links right is critical for accessibility - links with bad text are one of the most common accessibility failures in documentation.
### Basic link syntax
Wrap the visible link text in square brackets, followed immediately by the URL in parentheses:
```markdown
[GitHub Documentation](https://docs.github.com)
```
**Renders as:** [GitHub Documentation](https://docs.github.com)
### Links with title text
Add a title in quotes after the URL. The title appears as a tooltip on hover:
```markdown
[GitHub Documentation](https://docs.github.com "Official GitHub docs and guides")
```
> **Screen reader note:** Link titles are not reliably announced by all screen readers. Do not put critical information only in the title text. The link text itself must be descriptive.
### Writing accessible link text
This is one of the most important accessibility skills in Markdown authoring. Screen reader users often navigate by pulling up a list of all links on a page (NVDA: `NVDA+F7` then select Links; JAWS: `Insert+F7`). In this list, only the link text is shown - not the surrounding sentence. Every link must make sense on its own.
The following table contrasts bad and good link text with an explanation.
| Bad (do not do this) | Good (do this instead) | Why |
|---|---|---|
| Click [here](url) for the guide | Read the [Contributing Guide](url) | "here" means nothing out of context |
| [Read more](url) | [Read the full accessibility audit report](url) | "Read more" is ambiguous in a link list |
| [https://docs.github.com](https://docs.github.com) | [GitHub Documentation](https://docs.github.com) | Screen readers read the entire URL character by character |
| [Link](url) | [Pre-Workshop Setup instructions](url) | "Link" tells you nothing about the destination |
### Reference-style links
For documents with many links, reference-style links keep the text readable by separating the URL from the prose. You define the link target once at the bottom of the document:
```markdown
Check the [Contributing Guide][contributing] before submitting a PR.
See also the [Code of Conduct][coc] for community standards.
[contributing]: https://github.com/community-access/accessibility-agents/blob/main/CONTRIBUTING.md
[coc]: https://github.com/community-access/accessibility-agents/blob/main/CODE_OF_CONDUCT.md
```
The reference labels (`[contributing]`, `[coc]`) do not appear in the rendered output. Readers just see clean, clickable links.
### Relative links within a repository
When linking to other files in the same repository, use relative paths instead of full URLs. This way, links work on any fork or branch:
```markdown
See the [Pre-Workshop Setup](00-pre-workshop-setup.md) guide.
Jump to the [Glossary](appendix-a-glossary.md#fork) entry for "fork."
Return to the [course guide](course-guide.md).
```
### Email links
```markdown
Contact us at
```
The angle brackets tell Markdown to create a `mailto:` link:
### Autolinked URLs
GitHub automatically converts full URLs in your text into clickable links, but always prefer explicit descriptive links in prose. Bare URLs should only appear in reference sections or code examples.
## 11. Images
Images in Markdown use a syntax similar to links, with an exclamation mark (`!`) at the beginning.
### Syntax
```markdown
```
The text inside the square brackets is the **alt text** - the description that screen readers read aloud instead of displaying the image. This is the single most important accessibility attribute for images.
### Writing good alt text
The following table provides guidance on alt text for different types of images.
| Image type | Good alt text | Bad alt text |
|---|---|---|
| Screenshot of a form | "GitHub new issue form with title field, body text area, and submit button" | "screenshot" |
| Logo | "Community Access logo" | "logo.png" |
| Decorative divider | Leave alt text empty: `` | "divider" |
| Chart or graph | "Bar chart showing screen reader usage: JAWS 40%, NVDA 35%, VoiceOver 15%, Other 10%" | "chart" |
| Photo of a person | "Jamie presenting at the accessibility workshop podium" | "photo" |
### Image with a link
To make an image clickable, wrap the image syntax inside a link:
```markdown
[](https://community-access.org)
```
### Image with a title
```markdown
```
### When to use details blocks for complex images
If an image contains complex information (like an architecture diagram or a data visualization), provide a full text description in a collapsible `` block:
```markdown
Full description of the architecture diagram
The architecture has three tiers:
1. The GitHub Hub agent receives all user requests
2. The Hub routes to specialist agents (issue-tracker, pr-review, analytics)
3. Each specialist agent returns structured markdown reports
```
> **Screen reader note:** Screen readers announce images as "graphic" followed by the alt text. If alt text is empty, the image is treated as decorative and skipped. If alt text is missing entirely (no square brackets), some screen readers will announce the filename, which is not helpful. Always include the square brackets, even if empty for decorative images.
## 12. Blockquotes
Blockquotes are used for callouts, important notes, cited text, and instructor guidance throughout this course. Start each line with a `>` character followed by a space.
### Basic blockquote
**What you type:**
```markdown
> This is a blockquote. It is used to highlight important information
> or to quote someone else's text.
```
**What renders:**
> This is a blockquote. It is used to highlight important information or to quote someone else's text.
### Multi-paragraph blockquotes
Add a `>` on the blank lines between paragraphs to keep them inside the blockquote:
```markdown
> This is the first paragraph of the blockquote.
>
> This is the second paragraph. The blank line with just ">" keeps
> both paragraphs inside the same blockquote.
```
### Nested blockquotes
```markdown
> This is the outer blockquote.
>
> > This is a nested blockquote inside the first one.
>
> Back to the outer level.
```
### Blockquotes with other elements
Blockquotes can contain any Markdown element - headings, lists, code, bold, links:
```markdown
> **Important:** Before starting the exercise:
>
> 1. Make sure you are on the `main` branch
> 2. Pull the latest changes: `git pull origin main`
> 3. Read the [challenge description](challenges.md) first
>
> If you get stuck, ask in the issue thread.
```
> **Screen reader note:** Screen readers announce the beginning and end of a blockquote. NVDA says "block quote" when entering and "out of block quote" when leaving. Content inside is read normally. This means blockquotes are an excellent way to highlight important information for all users.
### How we use blockquotes in this course
Throughout this workshop, blockquotes serve specific purposes:
- **Screen reader notes:** Tips specific to assistive technology users
- **Learning Room connections:** How the current topic connects to the practice repo
- **Important warnings:** Critical information that could prevent errors
- **Instructor guidance:** Notes from the facilitator about pacing or approach
## 13. Inline Code and Code Blocks
Code formatting is essential on GitHub. You will use it for command-line instructions, file names, configuration values, keyboard shortcuts, and actual source code.
### Inline code
Wrap text in single backticks (`` ` ``) to format it as code within a sentence.
**What you type:**
```markdown
Run `git status` to see which files have changed.
The configuration file is `package.json`.
Press `Ctrl+Shift+P` to open the Command Palette.
```
**What renders:**
Run `git status` to see which files have changed.
The configuration file is `package.json`.
Press `Ctrl+Shift+P` to open the Command Palette.
**When to use inline code:**
- Command names: `git clone`, `npm install`
- File names: `README.md`, `CONTRIBUTING.md`
- Keyboard shortcuts: `Ctrl+C`, `Alt+Tab`
- Variable or function names: `userName`, `getElementById()`
- Configuration values: `true`, `false`, `null`
- Branch names: `main`, `feature/add-alt-text`
### Code blocks (fenced)
For multi-line code, wrap it in triple backticks (` ``` `) on their own lines:
**What you type:**
````markdown
```
This is a code block.
All formatting is preserved exactly.
Indentation stays.
**Bold does not render** - it stays as plain text.
```
````
### Code blocks with syntax highlighting
Add a language identifier right after the opening triple backticks to enable syntax highlighting:
````markdown
```python
def greet(name: str) -> str:
"""Return a greeting for the given name."""
return f"Hello, {name}! Welcome to the workshop."
```
````
```python
def greet(name: str) -> str:
"""Return a greeting for the given name."""
return f"Hello, {name}! Welcome to the workshop."
```
The following table lists language identifiers you will encounter most often in this workshop.
| Language | Identifier | Used for |
|---|---|---|
| Python | `python` | Scripts, automation, Copilot examples |
| Bash / Shell | `bash` or `shell` | Terminal commands, Git operations |
| YAML | `yaml` | GitHub Actions workflows, issue templates |
| JSON | `json` | Configuration files, API responses |
| JavaScript | `javascript` or `js` | Web scripts, Node.js |
| HTML | `html` | Web page structure |
| CSS | `css` | Styling |
| Markdown | `markdown` | Markdown examples (yes, you can format Markdown inside Markdown) |
| Plain text | `text` or `plaintext` | When no highlighting is needed |
| Diff | `diff` | Showing code changes (additions in green, removals in red) |
### Showing diffs in code blocks
The `diff` language identifier highlights additions and removals:
````markdown
```diff
- old line that was removed
+ new line that was added
unchanged context line
```
````
```diff
- old line that was removed
+ new line that was added
unchanged context line
```
### Code blocks inside list items
Indent the code block to align with the list item text:
```markdown
1. Create a new branch:
```bash
git checkout -b feature/my-change
```
2. Make your changes and stage them:
```bash
git add .
```
```
### How to show literal backticks
If your code contains backticks, use more backticks for the fence:
`````markdown
````markdown
```python
print("Hello")
```
````
`````
Use four backticks to wrap content that contains triple backticks. Use five to wrap content that contains four. You get the idea.
> **Screen reader note:** Code blocks are announced as "code" regions. Screen readers read the content character by character when navigating with arrow keys, and as whole lines when navigating with `Down Arrow`. Syntax highlighting is visual only - it does not affect what screen readers announce. The code text is equally accessible whether highlighted or not.
## 14. Horizontal Rules
A horizontal rule creates a thematic break between sections - a visual line across the page. Use three or more dashes, asterisks, or underscores on a line by themselves.
**What you type (any of these work):**
```markdown
***
___
```
**Best practice:** Use `---` (three dashes). It is the most common convention and looks clean in raw Markdown. Always put a blank line before and after the rule.
> **Screen reader note:** Horizontal rules are announced as "separator" in NVDA, "horizontal separator" in JAWS, and "horizontal rule" in VoiceOver. They are useful as navigation landmarks - screen reader users can move between them, but do not overuse them. Headings are a better way to structure a document.
## 15. Escaping Special Characters
Many characters have special meaning in Markdown. If you want to display them as literal characters instead, put a backslash (`\`) before them.
### Characters that can be escaped
The following table lists every character that can be escaped in Markdown.
| Character | Name | Markdown meaning |
|---|---|---|
| `\` | Backslash | Escape character itself |
| `` ` `` | Backtick | Inline code |
| `*` | Asterisk | Bold, italic, or list item |
| `_` | Underscore | Bold or italic |
| `{}` | Curly braces | Used in some extensions |
| `[]` | Square brackets | Link text |
| `()` | Parentheses | Link URL |
| `#` | Hash | Heading |
| `+` | Plus sign | Unordered list |
| `-` | Dash | Unordered list or horizontal rule |
| `.` | Period | Ordered list (after a number) |
| `!` | Exclamation mark | Image |
| `|` | Pipe | Table column separator |
| `~` | Tilde | Strikethrough |
### Examples
**What you type:**
```markdown
This asterisk is literal: \*not bold\*
This hash is literal: \# not a heading
Show a pipe character: \|
```
**What renders:**
This asterisk is literal: \*not bold\*
This hash is literal: \# not a heading
Show a pipe character: \|
## 16. Tables
Tables organize data into rows and columns. They are used extensively on GitHub for comparison charts, reference data, settings documentation, and checklists.
### Basic table syntax
```markdown
| Name | Role | Platform |
|---|---|---|
| NVDA | Screen reader | Windows |
| JAWS | Screen reader | Windows |
| VoiceOver | Screen reader | macOS / iOS |
| TalkBack | Screen reader | Android |
```
**What renders:**
| Name | Role | Platform |
|---|---|---|
| NVDA | Screen reader | Windows |
| JAWS | Screen reader | Windows |
| VoiceOver | Screen reader | macOS / iOS |
| TalkBack | Screen reader | Android |
### How table syntax works
- The **first row** is always the header row
- The **second row** contains dashes (`---`) that separate the header from the data. You need at least three dashes per column
- Each **subsequent row** is a data row
- Columns are separated by pipe characters (`|`)
- Leading and trailing pipes are optional but recommended for readability
### Column alignment
Add colons (`:`) to the separator row to control text alignment:
```markdown
| Left aligned | Center aligned | Right aligned |
|:---|:---:|---:|
| Text | Text | Text |
| Longer text here | Centered text | 42 |
```
| Left aligned | Center aligned | Right aligned |
|:---|:---:|---:|
| Text | Text | Text |
| Longer text here | Centered text | 42 |
- `:---` = left aligned (default)
- `:---:` = center aligned
- `---:` = right aligned
### Formatting inside table cells
You can use inline formatting within table cells:
```markdown
| Feature | Status | Notes |
|---|---|---|
| **Bold text** | `code` | Works [with links](url) too |
| *Italic text* | ~~struck~~ | Use any inline formatting |
```
### Accessibility considerations for tables
1. **Always include a description before the table.** Add a one-sentence summary immediately above the table explaining what it contains. Screen reader users hear the table structure (rows and columns) but benefit from knowing what the table is about before entering it
2. **Keep tables simple.** Tables with more than 5-6 columns become difficult to navigate with a screen reader. Consider splitting wide tables into multiple narrower tables
3. **Use tables for data, not layout.** If you are using a table just to arrange content side by side, use a list instead
4. **Make the header row descriptive.** The header cell is announced before each data cell when navigating by column, so "Platform" is better than "Col 3"
> **Screen reader note:** Screen readers navigate tables with `Ctrl+Alt+Arrow` keys (NVDA and JAWS). `Ctrl+Alt+Right` moves to the next column. `Ctrl+Alt+Down` moves to the next row. The column header is announced each time you move to a new column. Table mode is entered automatically when the screen reader encounters a table.
### When not to use a table
If your "table" has only two columns where the first is a label and the second is a value, consider using a definition-style list or bold labels instead:
```markdown
**Name:** Community Access
**Founded:** 2020
**Mission:** Empowering blind and low vision technology professionals
```
This is often easier to read with a screen reader than a two-column table.
## Part 2 - GitHub Flavored Markdown (GFM)
## 17. What Is GitHub Flavored Markdown?
GitHub Flavored Markdown (GFM) is GitHub's own superset of standard Markdown. It takes everything from the CommonMark specification (the modern standard for Markdown) and adds features specifically designed for software collaboration: tables, task lists, strikethrough, autolinked references, alert blocks, Mermaid diagrams, math expressions, and footnotes.
Everything you learned in Part 1 works everywhere Markdown is supported. Everything in Part 2 is specific to GitHub (and some other platforms that have adopted GFM).
### Where GFM works
The following table shows where GFM is supported.
| Location | GFM supported | Notes |
|---|---|---|
| `.md` files in repos | Yes | Any Markdown file rendered on GitHub |
| Issue descriptions | Yes | Full GFM with autolinks |
| Issue comments | Yes | Full GFM with autolinks |
| Pull request descriptions | Yes | Full GFM with autolinks |
| Pull request comments | Yes | Full GFM with autolinks |
| Discussion posts | Yes | Full GFM with autolinks |
| Wiki pages | Yes | Full GFM |
| Gists | Yes | Full GFM |
| Commit messages | Partial | Basic formatting, autolinks - no Mermaid or math |
| GitHub Pages (Jekyll) | Depends | Jekyll has its own Markdown processor |
| VS Code preview | Mostly | Supports most GFM; Mermaid requires an extension |
## 18. Alert and Callout Blocks
GitHub introduced **alert blocks** in 2023. They render as colored, bordered callout boxes - great for emphasizing warnings, tips, or critical information. You will see these throughout this course to highlight screen reader notes, important warnings, and tips.
### Syntax
```markdown
> [!NOTE]
> Useful information that users should know, even when skimming.
> [!TIP]
> Helpful advice for doing something better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```
### How to write them
1. Start a blockquote with `>`
2. The first line must be exactly `> [!TYPE]` where TYPE is one of: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`
3. All subsequent lines start with `>` and a space, just like a regular blockquote
4. You can include any Markdown inside the alert: lists, code, links, bold
### Choosing the right alert type
The following table describes each alert type and when to use it.
| Type | Color | When to use | Example |
|---|---|---|---|
| `NOTE` | Blue | Supplementary information the reader should know | Additional context about a feature |
| `TIP` | Green | Best practice or shortcut | "Use `Ctrl+Shift+P` for faster access" |
| `IMPORTANT` | Purple | Something the reader absolutely must know | Required configuration step |
| `WARNING` | Yellow | A potential problem or non-obvious risk | "This changes are not reversible after merge" |
| `CAUTION` | Red | An action that could cause irreversible harm | "This deletes all branches and cannot be undone" |
### Multi-line alert with formatting
```markdown
> [!WARNING]
> **Do not skip the pre-workshop setup.**
>
> If you arrive without a configured environment, you will spend the first
> hour catching up while others are working on challenges. Complete
> [Chapter 0](00-pre-workshop-setup.md) before Day 1.
>
> Checklist:
>
> - Git installed
> - GitHub account created
> - Screen reader configured for GitHub
```
### Screen Reader Behavior
Alert blocks render as `` elements with an SVG icon and a strong heading. Screen readers read:
- NVDA/JAWS: announces `blockquote` role, then reads the type label ("Note", "Warning") then the content
- VoiceOver: reads the type as bold text then the content
- The colored icon is decorative (`aria-hidden`); it does not add information beyond the type label
## 19. Collapsible Sections with Details and Summary
The `` and `` HTML elements create collapsible sections. They are one of the most useful tools for keeping long documents, issue reports, and PRs manageable - hiding optional content until the reader chooses to expand it.
### Basic syntax
```markdown
Click to expand: Full error log
Content that is hidden until the user expands this section.
You can put **any Markdown** in here:
- Lists
- Code blocks
- Links
- Tables
```
### Important formatting rules
1. **Blank line after ``.** Put a blank line between the closing `
` tag and your Markdown content. Without it, Markdown formatting inside may not render
2. **Blank line before `
`.** Same principle at the end
3. The `` text should be descriptive - it is the only thing visible when collapsed
### Real-world uses in this workshop
The following list describes common uses for collapsible sections.
- **Bug reports in issues:** Collapse the full stack trace so the issue body stays readable
- **Long configuration blocks:** Let readers expand the full YAML only if they need it
- **Exercise solutions:** Collapse the answer so learners try the exercise first
- **Screen reader guidance blocks:** Throughout this course, some sections collapse detailed assistive technology instructions so sighted users see a cleaner page while screen reader users can easily expand them
- **Meeting notes:** Collapse detailed minutes while showing the summary
### Nesting details inside details
```markdown
Operating system instructions
Windows
1. Open PowerShell
2. Run `git --version`
macOS
1. Open Terminal
2. Run `git --version`
```
### Details sections that start open
Add the `open` attribute to have the section expanded by default:
```markdown
Currently known issues
- Checkbox toggle requires Focus Mode in NVDA
- Alert blocks do not render in email notifications
```
### Screen Reader Behavior
The `` element renders as a disclosure widget:
- NVDA: announces "button collapsed" for the `` - press `Enter` or `Space` to expand
- JAWS: announces "collapsed" - press `Enter` on the summary to expand
- VoiceOver: announces "collapsed, button" - press `VO+Space` to activate
**After expanding:** The content is immediately readable. Screen readers announce "button expanded" for the summary. No page reload occurs.
## 20. Task List Checkboxes
Task lists in GitHub issues and PRs render as **real interactive checkboxes**. Anyone with write access to the repository can check and uncheck them directly in the rendered view without editing the Markdown.
### Syntax
```markdown
- [x] Color contrast verified (4.5:1 minimum for body text)
- [x] Keyboard navigation tested
- [ ] Screen reader tested with NVDA
- [ ] Screen reader tested with JAWS
- [ ] Screen reader tested with VoiceOver
- [ ] Alt text provided for all images
- [ ] Focus indicators visible
```
### How to write them
1. Start with a list item marker (`-`, `*`, or `+`) and a space
2. Add `[x]` for a checked box or `[ ]` (with a space inside) for an unchecked box
3. Add a space, then the task description
4. The description should be meaningful - "Test NVDA" is better than "Item 3"
### What makes task lists special on GitHub
- **Progress tracking:** In issues, GitHub shows a progress bar: "2 of 7 tasks completed"
- **Click to check:** In the rendered view, users with triage or write permissions can click to toggle checkboxes without editing the comment
- **Linked issues:** You can reference issues in a task: `- [ ] Fix #42` - the task shows the issue title and its open/closed state
- **PR templates:** Task lists in PR templates create checklists that authors fill out before requesting review
### Example - pull request checklist
```markdown
## Pre-review checklist
- [x] Changes are limited to the files listed in the issue
- [x] All new images have descriptive alt text
- [ ] Screen reader tested the changes with NVDA
- [ ] No heading levels are skipped
- [ ] All links use descriptive text (not "click here")
```
### Screen Reader Interaction
In Browse Mode, checkboxes are read as `checkbox, not checked` or `checkbox, checked`.
**To toggle a task list checkbox:**
- NVDA: Press `NVDA+Space` to enter Focus Mode, then `Tab` to find the checkbox, then `Space` to toggle it
- JAWS: `Tab` to the checkbox, then `Space` to toggle
- VoiceOver: `VO+Space` on the checkbox element
## 21. Syntax Highlighting in Fenced Code Blocks
We covered basic code blocks in Section 13. This section covers the GitHub-specific syntax highlighting that makes code blocks more readable for sighted users.
### How it works
Add a language identifier right after the opening triple backticks. GitHub uses Linguist to apply syntax highlighting with appropriate colors for keywords, strings, comments, and other language constructs.
````markdown
```python
def check_accessibility(element):
"""Check if an element has proper ARIA attributes."""
if not element.get("aria-label") and not element.get("aria-labelledby"):
return "Missing accessible name"
return "Accessible"
```
````
### Complete list of commonly used language identifiers
The following table lists the language identifiers you are most likely to use.
| Identifier | Language | Example use in this workshop |
|---|---|---|
| `python` | Python | Scripts, automation, challenge code |
| `bash` or `shell` | Bash/Shell | Terminal commands, Git operations |
| `yaml` or `yml` | YAML | GitHub Actions, issue templates |
| `json` | JSON | Configuration, API responses |
| `javascript` or `js` | JavaScript | Web scripts |
| `typescript` or `ts` | TypeScript | Typed JavaScript |
| `html` | HTML | Web page structure |
| `css` | CSS | Styling |
| `markdown` or `md` | Markdown | Documenting Markdown syntax |
| `diff` | Diff | Code change comparison |
| `text` or `plaintext` | None | No highlighting needed |
| `ruby` | Ruby | Ruby scripts |
| `go` | Go | Go programs |
| `rust` | Rust | Rust programs |
| `java` | Java | Java programs |
| `csharp` or `cs` | C# | .NET programs |
| `sql` | SQL | Database queries |
| `dockerfile` | Dockerfile | Container configuration |
| `xml` | XML | Structured data |
| `toml` | TOML | Configuration (Rust, Python) |
| `ini` | INI | Configuration files |
| `powershell` or `ps1` | PowerShell | Windows automation |
If no language is specified, the code block renders as plain monospaced text with no highlighting.
### Screen Reader Note
Syntax highlighting is visual only - screen readers read the code text without announcing color changes. The code block itself is announced as a `code` region. This means the text content of well-written code is equally accessible whether highlighted or not. Variable names, function names, and comments are the real accessibility of code - not colors.
## 22. Mermaid Diagrams
GitHub renders [Mermaid.js](https://mermaid.js.org/) diagrams inline when you use a `mermaid` fenced code block. They are common in READMEs, PRs, and documentation to illustrate architecture, flows, and relationships.
### Syntax
````markdown
```mermaid
flowchart LR
A[Fork repo] --> B[Clone locally]
B --> C[Create branch]
C --> D[Make changes]
D --> E[Push branch]
E --> F[Open PR]
F --> G{Review passed?}
G -- Yes --> H[Merge]
G -- No --> D
```
````
### Common diagram types
The following table lists the Mermaid diagram types you are most likely to encounter on GitHub.
| Type | Keyword | Use case |
|---|---|---|
| Flowchart | `flowchart LR` or `flowchart TD` | Process flows, decision trees |
| Sequence diagram | `sequenceDiagram` | API calls, user interactions |
| Entity-Relationship | `erDiagram` | Database schemas |
| Class diagram | `classDiagram` | Code architecture |
| Gantt chart | `gantt` | Project schedules |
| Git graph | `gitGraph` | Branch and merge visualization |
| Pie chart | `pie` | Data distribution |
### Accessibility limitation - critical
> **Important:** Mermaid diagrams render as SVG images. GitHub does not auto-generate alt text for them. Screen readers will typically either skip them entirely or announce generic SVG container information that is not useful.
This means **every Mermaid diagram is invisible to screen reader users unless you provide a text alternative.**
### How to make Mermaid diagrams accessible
Always follow this pattern:
1. Write a **text description** before the diagram that conveys all the same information
2. Optionally, duplicate the information as a numbered list or table
3. Consider wrapping the Mermaid source in a `` block if the text description is sufficient
**Example - accessible Mermaid usage:**
````markdown
The PR workflow follows these steps: fork the repository, clone
your fork locally, create a feature branch, make your changes and commit,
push the branch to your fork, open a pull request, address review feedback,
and merge when approved.
1. Fork the repository
2. Clone your fork locally
3. Create a feature branch
4. Make your changes and commit
5. Push the branch to your fork
6. Open a pull request
7. Address review feedback
8. Merge when approved
Diagram source (Mermaid)
```mermaid
flowchart LR
Fork --> Clone --> Branch --> Commit --> Push --> PR --> Review --> Merge
```
````
This way, screen reader users get the full information from the text and numbered list. Sighted users can also expand the Mermaid diagram for a visual representation.
## 23. Math Expressions with LaTeX
GitHub renders LaTeX math expressions using MathJax. This is common in data science, research, and algorithm documentation.
### Inline math
Use single `$` delimiters for math within a sentence:
```markdown
The formula is $e = mc^2$ where $c$ is the speed of light.
```
**Renders as:** The formula is $e = mc^2$ where $c$ is the speed of light.
### Block math
Use `$$` delimiters for display-style (centered, larger) math on their own lines:
```markdown
$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$
```
### Common LaTeX patterns
The following table shows some LaTeX patterns you might encounter.
| What you want | LaTeX | Rendered |
|---|---|---|
| Superscript | `$x^2$` | $x^2$ |
| Subscript | `$x_i$` | $x_i$ |
| Fraction | `$\frac{a}{b}$` | $\frac{a}{b}$ |
| Square root | `$\sqrt{x}$` | $\sqrt{x}$ |
| Greek letter | `$\alpha, \beta, \gamma$` | $\alpha, \beta, \gamma$ |
| Summation | `$\sum_{i=1}^{n}$` | $\sum_{i=1}^{n}$ |
| Not equal | `$\neq$` | $\neq$ |
| Less or equal | `$\leq$` | $\leq$ |
### Screen Reader Note
Math expressions rendered by MathJax include `aria-label` attributes with the spoken form of the equation. Screen readers should announce the math correctly, but accuracy varies:
- NVDA with Firefox or Chrome: reads MathML fairly well
- JAWS: reads the aria-label text
- VoiceOver: reads the aria-label text
**Best practice:** If writing documentation for an accessibility-focused audience, supplement complex equations with a plain English description:
```markdown
The sum of all values from 1 to n equals n times n+1 divided by 2:
$$
\sum_{i=1}^{n} x_i = \frac{n(n+1)}{2}
$$
```
## 24. Footnotes
GitHub supports Markdown footnotes, which render as superscript numbers that link to references at the bottom of the document. They are useful for citations, additional context, and references that would interrupt the flow of the main text.
### Syntax
```markdown
This technique improves screen reader navigation significantly.[^1]
You can also use named footnotes for clarity.[^accessibility-note]
[^1]: Based on the WebAIM Screen Reader Survey, 2024.
[^accessibility-note]: See WCAG 2.2 Success Criterion 2.4.3 for focus order requirements.
```
### How they work
1. In your text, add `[^identifier]` where you want the footnote reference to appear
2. Anywhere in the document (typically at the bottom), define the footnote with `[^identifier]: Your footnote text`
3. GitHub renders the reference as a superscript number that links to the definition
4. The definition includes a back-link that returns to the reference location
### Footnote identifiers
- You can use numbers: `[^1]`, `[^2]`, `[^3]`
- You can use descriptive names: `[^webaim-survey]`, `[^wcag-reference]`
- Descriptive names make the raw Markdown more readable but render as sequential numbers
### Multi-line footnotes
Indent continuation lines with two spaces:
```markdown
[^long-note]: This is a longer footnote that spans multiple paragraphs.
The second paragraph of the footnote is indented with two spaces.
You can even include code: `git status`
```
### Screen Reader Behavior
- The footnote reference is a link (`` element) announcing its number
- NVDA: "superscript, 1, link"
- JAWS: "link, 1"
- VoiceOver: "link, footnote 1"
- The back-link at the definition reads "return to footnote reference"
- Activating the footnote link jumps focus to the definition; activating the back-link returns focus to the original location
## 25. Linked Heading Anchors and Tables of Contents
Every heading in a GitHub Markdown file automatically gets an anchor ID. You can link to any heading from anywhere - within the same document, from another file, or from an issue or PR.
### How GitHub generates anchor IDs
GitHub converts the heading text to an anchor ID by:
1. Converting to lowercase
2. Replacing spaces with hyphens
3. Removing most punctuation (except hyphens)
4. Removing leading and trailing whitespace
The following table shows example headings and their generated anchors.
| Heading text | Generated anchor |
|---|---|
| `# Introduction` | `#introduction` |
| `## Getting Started` | `#getting-started` |
| `### VS Code: Setup & Accessibility Basics` | `#vs-code-setup--accessibility-basics` |
| `## 1. First Steps` | `#1-first-steps` |
| `## What Is a PR?` | `#what-is-a-pr` |
### Linking to a heading in the same document
```markdown
See the [Tables](#16-tables) section for details on formatting data.
Return to the [Table of Contents](#table-of-contents).
```
### Linking to a heading in another file
```markdown
See the [Pre-Workshop Setup guide](00-pre-workshop-setup.md#step-1---create-a-github-account).
```
### Building a table of contents
You can build a manual table of contents using heading anchor links:
```markdown
## Table of Contents
1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Usage](#usage)
5. [Contributing](#contributing)
```
### Duplicate headings
If a document has two headings with the same text, GitHub appends `-1`, `-2`, and so on to the duplicate anchors:
| Heading | Anchor |
|---|---|
| First `## Examples` | `#examples` |
| Second `## Examples` | `#examples-1` |
| Third `## Examples` | `#examples-2` |
**Best practice:** Avoid duplicate heading text. Use descriptive, unique headings for each section.
### Finding the anchor for any heading
1. **Mouse users:** On GitHub, hover over any heading - a chain link icon appears to the left. Click it to update the URL with the anchor
2. **Screen reader users:** Navigate to the heading, then `Tab` once. A link button appears. Activate it and the URL in the address bar updates to show the anchor
3. **Keyboard (GitHub shortcut):** There is no direct shortcut, but you can copy the heading text, convert it to the anchor format mentally, and type it in the URL
## 26. Autolinked References - Issues, PRs, Commits, and Users
One of GitHub's most powerful features is automatic linking. When you type certain patterns in any Markdown field on GitHub, they automatically become clickable links. This is how the entire GitHub collaboration workflow connects.
### Issue and pull request references
The following table shows how to reference issues and pull requests.
| What you type | What it links to | Example |
|---|---|---|
| `#42` | Issue or PR number 42 in the current repo | "See #42 for details" |
| `GH-42` | Same as above (alternative syntax) | "Fixed in GH-42" |
| `owner/repo#42` | Issue 42 in a different repo | "Related: community-access/accessibility-agents#15" |
### User and team mentions
The following table shows how to mention users and teams.
| What you type | What it does | Example |
|---|---|---|
| `@username` | Mentions a user, sends them a notification | "Thanks @johndoe for the review" |
| `@org/team-name` | Mentions an entire team | "Cc @community-access/maintainers" |
### Commit references
The following table shows how to reference specific commits.
| What you type | What it links to | Example |
|---|---|---|
| Full SHA: `a1b2c3d4e5f6...` | Links to that commit (first 7+ chars) | "Fixed in a1b2c3d" |
| `owner/repo@SHA` | Commit in another repo | "See community-access/accessibility-agents@a1b2c3d" |
### Closing keywords in pull requests
When you include certain keywords followed by an issue reference in a PR description, merging the PR automatically closes the referenced issue:
```markdown
This PR adds alt text to all images in the documentation.
Closes #42
Fixes #43
Resolves #44
```
All of these keywords work: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`. They are case-insensitive.
### URL autolinking
GitHub automatically converts full URLs into clickable links:
```markdown
Check out https://github.com/community-access/accessibility-agents for the project.
```
> **Accessibility note:** While autolinked URLs work, they create poor link text for screen readers (the entire URL is read character by character). In documentation and issue descriptions, always use descriptive link text instead: `[Accessibility Agents repository](https://github.com/community-access/accessibility-agents)`.
## 27. HTML in Markdown
GitHub allows a subset of HTML in Markdown files. This is useful for semantic elements that do not have Markdown equivalents, advanced layout needs, and accessibility improvements.
### Keyboard key visualization
The `` element renders text in a key-cap style box:
```html
Press Ctrl+C to copy.
Press NVDA+Space to toggle Focus Mode.
```
Press Ctrl+C to copy.
Press NVDA+Space to toggle Focus Mode.
### Subscript and superscript
```html
H2O is water.
E = mc2 is Einstein's equation.
```
H2O is water.
E = mc2 is Einstein's equation.
### Centered content
```html
```
### Line breaks
```html
Line one
Line two on the next line, same paragraph.
```
### Hidden comments
```html
```
Hidden comments are useful for notes to yourself or other contributors that should not be visible to readers.
### Allowed HTML elements on GitHub
GitHub whitelists specific HTML elements for security. The following table lists the most useful allowed elements.
| Element | Purpose | Screen reader behavior |
|---|---|---|
| `` / `` | Collapsible sections | Announced as disclosure widget |
| `` | Keyboard keys | Announced as "code" or the text content |
| `` / `` | Subscript / superscript | Text read normally; some SRs announce position |
| `
` | Line break | Brief pause in reading |
| `` | Generic container | No announcement unless has role/aria |
| `![]()
` | Image with attributes | Alt text read |
| `` | Link with attributes | Link text read |
| ``, ``, ` ` | Complex table | Full table navigation |
| `` | Comment | Not read (invisible) |
### Disallowed HTML on GitHub
GitHub strips these elements for security:
- `
` block:
```markdown
```
> **Screen reader note:** Screen readers announce images as "graphic" followed by the alt text. If alt text is empty, the image is treated as decorative and skipped. If alt text is missing entirely (no square brackets), some screen readers will announce the filename, which is not helpful. Always include the square brackets, even if empty for decorative images.
## 12. Blockquotes
Blockquotes are used for callouts, important notes, cited text, and instructor guidance throughout this course. Start each line with a `>` character followed by a space.
### Basic blockquote
**What you type:**
```markdown
> This is a blockquote. It is used to highlight important information
> or to quote someone else's text.
```
**What renders:**
> This is a blockquote. It is used to highlight important information or to quote someone else's text.
### Multi-paragraph blockquotes
Add a `>` on the blank lines between paragraphs to keep them inside the blockquote:
```markdown
> This is the first paragraph of the blockquote.
>
> This is the second paragraph. The blank line with just ">" keeps
> both paragraphs inside the same blockquote.
```
### Nested blockquotes
```markdown
> This is the outer blockquote.
>
> > This is a nested blockquote inside the first one.
>
> Back to the outer level.
```
### Blockquotes with other elements
Blockquotes can contain any Markdown element - headings, lists, code, bold, links:
```markdown
> **Important:** Before starting the exercise:
>
> 1. Make sure you are on the `main` branch
> 2. Pull the latest changes: `git pull origin main`
> 3. Read the [challenge description](challenges.md) first
>
> If you get stuck, ask in the issue thread.
```
> **Screen reader note:** Screen readers announce the beginning and end of a blockquote. NVDA says "block quote" when entering and "out of block quote" when leaving. Content inside is read normally. This means blockquotes are an excellent way to highlight important information for all users.
### How we use blockquotes in this course
Throughout this workshop, blockquotes serve specific purposes:
- **Screen reader notes:** Tips specific to assistive technology users
- **Learning Room connections:** How the current topic connects to the practice repo
- **Important warnings:** Critical information that could prevent errors
- **Instructor guidance:** Notes from the facilitator about pacing or approach
## 13. Inline Code and Code Blocks
Code formatting is essential on GitHub. You will use it for command-line instructions, file names, configuration values, keyboard shortcuts, and actual source code.
### Inline code
Wrap text in single backticks (`` ` ``) to format it as code within a sentence.
**What you type:**
```markdown
Run `git status` to see which files have changed.
The configuration file is `package.json`.
Press `Ctrl+Shift+P` to open the Command Palette.
```
**What renders:**
Run `git status` to see which files have changed.
The configuration file is `package.json`.
Press `Ctrl+Shift+P` to open the Command Palette.
**When to use inline code:**
- Command names: `git clone`, `npm install`
- File names: `README.md`, `CONTRIBUTING.md`
- Keyboard shortcuts: `Ctrl+C`, `Alt+Tab`
- Variable or function names: `userName`, `getElementById()`
- Configuration values: `true`, `false`, `null`
- Branch names: `main`, `feature/add-alt-text`
### Code blocks (fenced)
For multi-line code, wrap it in triple backticks (` ``` `) on their own lines:
**What you type:**
````markdown
```
This is a code block.
All formatting is preserved exactly.
Indentation stays.
**Bold does not render** - it stays as plain text.
```
````
### Code blocks with syntax highlighting
Add a language identifier right after the opening triple backticks to enable syntax highlighting:
````markdown
```python
def greet(name: str) -> str:
"""Return a greeting for the given name."""
return f"Hello, {name}! Welcome to the workshop."
```
````
```python
def greet(name: str) -> str:
"""Return a greeting for the given name."""
return f"Hello, {name}! Welcome to the workshop."
```
The following table lists language identifiers you will encounter most often in this workshop.
| Language | Identifier | Used for |
|---|---|---|
| Python | `python` | Scripts, automation, Copilot examples |
| Bash / Shell | `bash` or `shell` | Terminal commands, Git operations |
| YAML | `yaml` | GitHub Actions workflows, issue templates |
| JSON | `json` | Configuration files, API responses |
| JavaScript | `javascript` or `js` | Web scripts, Node.js |
| HTML | `html` | Web page structure |
| CSS | `css` | Styling |
| Markdown | `markdown` | Markdown examples (yes, you can format Markdown inside Markdown) |
| Plain text | `text` or `plaintext` | When no highlighting is needed |
| Diff | `diff` | Showing code changes (additions in green, removals in red) |
### Showing diffs in code blocks
The `diff` language identifier highlights additions and removals:
````markdown
```diff
- old line that was removed
+ new line that was added
unchanged context line
```
````
```diff
- old line that was removed
+ new line that was added
unchanged context line
```
### Code blocks inside list items
Indent the code block to align with the list item text:
```markdown
1. Create a new branch:
```bash
git checkout -b feature/my-change
```
2. Make your changes and stage them:
```bash
git add .
```
```
### How to show literal backticks
If your code contains backticks, use more backticks for the fence:
`````markdown
````markdown
```python
print("Hello")
```
````
`````
Use four backticks to wrap content that contains triple backticks. Use five to wrap content that contains four. You get the idea.
> **Screen reader note:** Code blocks are announced as "code" regions. Screen readers read the content character by character when navigating with arrow keys, and as whole lines when navigating with `Down Arrow`. Syntax highlighting is visual only - it does not affect what screen readers announce. The code text is equally accessible whether highlighted or not.
## 14. Horizontal Rules
A horizontal rule creates a thematic break between sections - a visual line across the page. Use three or more dashes, asterisks, or underscores on a line by themselves.
**What you type (any of these work):**
```markdown
***
___
```
**Best practice:** Use `---` (three dashes). It is the most common convention and looks clean in raw Markdown. Always put a blank line before and after the rule.
> **Screen reader note:** Horizontal rules are announced as "separator" in NVDA, "horizontal separator" in JAWS, and "horizontal rule" in VoiceOver. They are useful as navigation landmarks - screen reader users can move between them, but do not overuse them. Headings are a better way to structure a document.
## 15. Escaping Special Characters
Many characters have special meaning in Markdown. If you want to display them as literal characters instead, put a backslash (`\`) before them.
### Characters that can be escaped
The following table lists every character that can be escaped in Markdown.
| Character | Name | Markdown meaning |
|---|---|---|
| `\` | Backslash | Escape character itself |
| `` ` `` | Backtick | Inline code |
| `*` | Asterisk | Bold, italic, or list item |
| `_` | Underscore | Bold or italic |
| `{}` | Curly braces | Used in some extensions |
| `[]` | Square brackets | Link text |
| `()` | Parentheses | Link URL |
| `#` | Hash | Heading |
| `+` | Plus sign | Unordered list |
| `-` | Dash | Unordered list or horizontal rule |
| `.` | Period | Ordered list (after a number) |
| `!` | Exclamation mark | Image |
| `|` | Pipe | Table column separator |
| `~` | Tilde | Strikethrough |
### Examples
**What you type:**
```markdown
This asterisk is literal: \*not bold\*
This hash is literal: \# not a heading
Show a pipe character: \|
```
**What renders:**
This asterisk is literal: \*not bold\*
This hash is literal: \# not a heading
Show a pipe character: \|
## 16. Tables
Tables organize data into rows and columns. They are used extensively on GitHub for comparison charts, reference data, settings documentation, and checklists.
### Basic table syntax
```markdown
| Name | Role | Platform |
|---|---|---|
| NVDA | Screen reader | Windows |
| JAWS | Screen reader | Windows |
| VoiceOver | Screen reader | macOS / iOS |
| TalkBack | Screen reader | Android |
```
**What renders:**
| Name | Role | Platform |
|---|---|---|
| NVDA | Screen reader | Windows |
| JAWS | Screen reader | Windows |
| VoiceOver | Screen reader | macOS / iOS |
| TalkBack | Screen reader | Android |
### How table syntax works
- The **first row** is always the header row
- The **second row** contains dashes (`---`) that separate the header from the data. You need at least three dashes per column
- Each **subsequent row** is a data row
- Columns are separated by pipe characters (`|`)
- Leading and trailing pipes are optional but recommended for readability
### Column alignment
Add colons (`:`) to the separator row to control text alignment:
```markdown
| Left aligned | Center aligned | Right aligned |
|:---|:---:|---:|
| Text | Text | Text |
| Longer text here | Centered text | 42 |
```
| Left aligned | Center aligned | Right aligned |
|:---|:---:|---:|
| Text | Text | Text |
| Longer text here | Centered text | 42 |
- `:---` = left aligned (default)
- `:---:` = center aligned
- `---:` = right aligned
### Formatting inside table cells
You can use inline formatting within table cells:
```markdown
| Feature | Status | Notes |
|---|---|---|
| **Bold text** | `code` | Works [with links](url) too |
| *Italic text* | ~~struck~~ | Use any inline formatting |
```
### Accessibility considerations for tables
1. **Always include a description before the table.** Add a one-sentence summary immediately above the table explaining what it contains. Screen reader users hear the table structure (rows and columns) but benefit from knowing what the table is about before entering it
2. **Keep tables simple.** Tables with more than 5-6 columns become difficult to navigate with a screen reader. Consider splitting wide tables into multiple narrower tables
3. **Use tables for data, not layout.** If you are using a table just to arrange content side by side, use a list instead
4. **Make the header row descriptive.** The header cell is announced before each data cell when navigating by column, so "Platform" is better than "Col 3"
> **Screen reader note:** Screen readers navigate tables with `Ctrl+Alt+Arrow` keys (NVDA and JAWS). `Ctrl+Alt+Right` moves to the next column. `Ctrl+Alt+Down` moves to the next row. The column header is announced each time you move to a new column. Table mode is entered automatically when the screen reader encounters a table.
### When not to use a table
If your "table" has only two columns where the first is a label and the second is a value, consider using a definition-style list or bold labels instead:
```markdown
**Name:** Community Access
**Founded:** 2020
**Mission:** Empowering blind and low vision technology professionals
```
This is often easier to read with a screen reader than a two-column table.
## Part 2 - GitHub Flavored Markdown (GFM)
## 17. What Is GitHub Flavored Markdown?
GitHub Flavored Markdown (GFM) is GitHub's own superset of standard Markdown. It takes everything from the CommonMark specification (the modern standard for Markdown) and adds features specifically designed for software collaboration: tables, task lists, strikethrough, autolinked references, alert blocks, Mermaid diagrams, math expressions, and footnotes.
Everything you learned in Part 1 works everywhere Markdown is supported. Everything in Part 2 is specific to GitHub (and some other platforms that have adopted GFM).
### Where GFM works
The following table shows where GFM is supported.
| Location | GFM supported | Notes |
|---|---|---|
| `.md` files in repos | Yes | Any Markdown file rendered on GitHub |
| Issue descriptions | Yes | Full GFM with autolinks |
| Issue comments | Yes | Full GFM with autolinks |
| Pull request descriptions | Yes | Full GFM with autolinks |
| Pull request comments | Yes | Full GFM with autolinks |
| Discussion posts | Yes | Full GFM with autolinks |
| Wiki pages | Yes | Full GFM |
| Gists | Yes | Full GFM |
| Commit messages | Partial | Basic formatting, autolinks - no Mermaid or math |
| GitHub Pages (Jekyll) | Depends | Jekyll has its own Markdown processor |
| VS Code preview | Mostly | Supports most GFM; Mermaid requires an extension |
## 18. Alert and Callout Blocks
GitHub introduced **alert blocks** in 2023. They render as colored, bordered callout boxes - great for emphasizing warnings, tips, or critical information. You will see these throughout this course to highlight screen reader notes, important warnings, and tips.
### Syntax
```markdown
> [!NOTE]
> Useful information that users should know, even when skimming.
> [!TIP]
> Helpful advice for doing something better or more easily.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
> [!WARNING]
> Urgent info that needs immediate attention to avoid problems.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
```
### How to write them
1. Start a blockquote with `>`
2. The first line must be exactly `> [!TYPE]` where TYPE is one of: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`
3. All subsequent lines start with `>` and a space, just like a regular blockquote
4. You can include any Markdown inside the alert: lists, code, links, bold
### Choosing the right alert type
The following table describes each alert type and when to use it.
| Type | Color | When to use | Example |
|---|---|---|---|
| `NOTE` | Blue | Supplementary information the reader should know | Additional context about a feature |
| `TIP` | Green | Best practice or shortcut | "Use `Ctrl+Shift+P` for faster access" |
| `IMPORTANT` | Purple | Something the reader absolutely must know | Required configuration step |
| `WARNING` | Yellow | A potential problem or non-obvious risk | "This changes are not reversible after merge" |
| `CAUTION` | Red | An action that could cause irreversible harm | "This deletes all branches and cannot be undone" |
### Multi-line alert with formatting
```markdown
> [!WARNING]
> **Do not skip the pre-workshop setup.**
>
> If you arrive without a configured environment, you will spend the first
> hour catching up while others are working on challenges. Complete
> [Chapter 0](00-pre-workshop-setup.md) before Day 1.
>
> Checklist:
>
> - Git installed
> - GitHub account created
> - Screen reader configured for GitHub
```
### Screen Reader Behavior
Alert blocks render as `
Full description of the architecture diagram
The architecture has three tiers: 1. The GitHub Hub agent receives all user requests 2. The Hub routes to specialist agents (issue-tracker, pr-review, analytics) 3. Each specialist agent returns structured markdown reports` elements with an SVG icon and a strong heading. Screen readers read: - NVDA/JAWS: announces `blockquote` role, then reads the type label ("Note", "Warning") then the content - VoiceOver: reads the type as bold text then the content - The colored icon is decorative (`aria-hidden`); it does not add information beyond the type label ## 19. Collapsible Sections with Details and Summary The `` and ``.** Same principle at the end 3. The `` HTML elements create collapsible sections. They are one of the most useful tools for keeping long documents, issue reports, and PRs manageable - hiding optional content until the reader chooses to expand it. ### Basic syntax ```markdown
``` ### Important formatting rules 1. **Blank line after `Click to expand: Full error log
Content that is hidden until the user expands this section. You can put **any Markdown** in here: - Lists - Code blocks - Links - Tables`.** Put a blank line between the closing `
` tag and your Markdown content. Without it, Markdown formatting inside may not render 2. **Blank line before `` text should be descriptive - it is the only thing visible when collapsed ### Real-world uses in this workshop The following list describes common uses for collapsible sections. - **Bug reports in issues:** Collapse the full stack trace so the issue body stays readable - **Long configuration blocks:** Let readers expand the full YAML only if they need it - **Exercise solutions:** Collapse the answer so learners try the exercise first - **Screen reader guidance blocks:** Throughout this course, some sections collapse detailed assistive technology instructions so sighted users see a cleaner page while screen reader users can easily expand them - **Meeting notes:** Collapse detailed minutes while showing the summary ### Nesting details inside details ```markdown
``` ### Details sections that start open Add the `open` attribute to have the section expanded by default: ```markdownOperating system instructions
Windows
1. Open PowerShell 2. Run `git --version`macOS
1. Open Terminal 2. Run `git --version```` ### Screen Reader Behavior The `Currently known issues
- Checkbox toggle requires Focus Mode in NVDA - Alert blocks do not render in email notifications` element renders as a disclosure widget: - NVDA: announces "button collapsed" for the `` - press `Enter` or `Space` to expand - JAWS: announces "collapsed" - press `Enter` on the summary to expand - VoiceOver: announces "collapsed, button" - press `VO+Space` to activate **After expanding:** The content is immediately readable. Screen readers announce "button expanded" for the summary. No page reload occurs. ## 20. Task List Checkboxes Task lists in GitHub issues and PRs render as **real interactive checkboxes**. Anyone with write access to the repository can check and uncheck them directly in the rendered view without editing the Markdown. ### Syntax ```markdown - [x] Color contrast verified (4.5:1 minimum for body text) - [x] Keyboard navigation tested - [ ] Screen reader tested with NVDA - [ ] Screen reader tested with JAWS - [ ] Screen reader tested with VoiceOver - [ ] Alt text provided for all images - [ ] Focus indicators visible ``` ### How to write them 1. Start with a list item marker (`-`, `*`, or `+`) and a space 2. Add `[x]` for a checked box or `[ ]` (with a space inside) for an unchecked box 3. Add a space, then the task description 4. The description should be meaningful - "Test NVDA" is better than "Item 3" ### What makes task lists special on GitHub - **Progress tracking:** In issues, GitHub shows a progress bar: "2 of 7 tasks completed" - **Click to check:** In the rendered view, users with triage or write permissions can click to toggle checkboxes without editing the comment - **Linked issues:** You can reference issues in a task: `- [ ] Fix #42` - the task shows the issue title and its open/closed state - **PR templates:** Task lists in PR templates create checklists that authors fill out before requesting review ### Example - pull request checklist ```markdown ## Pre-review checklist - [x] Changes are limited to the files listed in the issue - [x] All new images have descriptive alt text - [ ] Screen reader tested the changes with NVDA - [ ] No heading levels are skipped - [ ] All links use descriptive text (not "click here") ``` ### Screen Reader Interaction In Browse Mode, checkboxes are read as `checkbox, not checked` or `checkbox, checked`. **To toggle a task list checkbox:** - NVDA: Press `NVDA+Space` to enter Focus Mode, then `Tab` to find the checkbox, then `Space` to toggle it - JAWS: `Tab` to the checkbox, then `Space` to toggle - VoiceOver: `VO+Space` on the checkbox element ## 21. Syntax Highlighting in Fenced Code Blocks We covered basic code blocks in Section 13. This section covers the GitHub-specific syntax highlighting that makes code blocks more readable for sighted users. ### How it works Add a language identifier right after the opening triple backticks. GitHub uses Linguist to apply syntax highlighting with appropriate colors for keywords, strings, comments, and other language constructs. ````markdown ```python def check_accessibility(element): """Check if an element has proper ARIA attributes.""" if not element.get("aria-label") and not element.get("aria-labelledby"): return "Missing accessible name" return "Accessible" ``` ```` ### Complete list of commonly used language identifiers The following table lists the language identifiers you are most likely to use. | Identifier | Language | Example use in this workshop | |---|---|---| | `python` | Python | Scripts, automation, challenge code | | `bash` or `shell` | Bash/Shell | Terminal commands, Git operations | | `yaml` or `yml` | YAML | GitHub Actions, issue templates | | `json` | JSON | Configuration, API responses | | `javascript` or `js` | JavaScript | Web scripts | | `typescript` or `ts` | TypeScript | Typed JavaScript | | `html` | HTML | Web page structure | | `css` | CSS | Styling | | `markdown` or `md` | Markdown | Documenting Markdown syntax | | `diff` | Diff | Code change comparison | | `text` or `plaintext` | None | No highlighting needed | | `ruby` | Ruby | Ruby scripts | | `go` | Go | Go programs | | `rust` | Rust | Rust programs | | `java` | Java | Java programs | | `csharp` or `cs` | C# | .NET programs | | `sql` | SQL | Database queries | | `dockerfile` | Dockerfile | Container configuration | | `xml` | XML | Structured data | | `toml` | TOML | Configuration (Rust, Python) | | `ini` | INI | Configuration files | | `powershell` or `ps1` | PowerShell | Windows automation | If no language is specified, the code block renders as plain monospaced text with no highlighting. ### Screen Reader Note Syntax highlighting is visual only - screen readers read the code text without announcing color changes. The code block itself is announced as a `code` region. This means the text content of well-written code is equally accessible whether highlighted or not. Variable names, function names, and comments are the real accessibility of code - not colors. ## 22. Mermaid Diagrams GitHub renders [Mermaid.js](https://mermaid.js.org/) diagrams inline when you use a `mermaid` fenced code block. They are common in READMEs, PRs, and documentation to illustrate architecture, flows, and relationships. ### Syntax ````markdown ```mermaid flowchart LR A[Fork repo] --> B[Clone locally] B --> C[Create branch] C --> D[Make changes] D --> E[Push branch] E --> F[Open PR] F --> G{Review passed?} G -- Yes --> H[Merge] G -- No --> D ``` ```` ### Common diagram types The following table lists the Mermaid diagram types you are most likely to encounter on GitHub. | Type | Keyword | Use case | |---|---|---| | Flowchart | `flowchart LR` or `flowchart TD` | Process flows, decision trees | | Sequence diagram | `sequenceDiagram` | API calls, user interactions | | Entity-Relationship | `erDiagram` | Database schemas | | Class diagram | `classDiagram` | Code architecture | | Gantt chart | `gantt` | Project schedules | | Git graph | `gitGraph` | Branch and merge visualization | | Pie chart | `pie` | Data distribution | ### Accessibility limitation - critical > **Important:** Mermaid diagrams render as SVG images. GitHub does not auto-generate alt text for them. Screen readers will typically either skip them entirely or announce generic SVG container information that is not useful. This means **every Mermaid diagram is invisible to screen reader users unless you provide a text alternative.** ### How to make Mermaid diagrams accessible Always follow this pattern: 1. Write a **text description** before the diagram that conveys all the same information 2. Optionally, duplicate the information as a numbered list or table 3. Consider wrapping the Mermaid source in a `
` block if the text description is sufficient **Example - accessible Mermaid usage:** ````markdown The PR workflow follows these steps: fork the repository, clone your fork locally, create a feature branch, make your changes and commit, push the branch to your fork, open a pull request, address review feedback, and merge when approved. 1. Fork the repository 2. Clone your fork locally 3. Create a feature branch 4. Make your changes and commit 5. Push the branch to your fork 6. Open a pull request 7. Address review feedback 8. Merge when approved```` This way, screen reader users get the full information from the text and numbered list. Sighted users can also expand the Mermaid diagram for a visual representation. ## 23. Math Expressions with LaTeX GitHub renders LaTeX math expressions using MathJax. This is common in data science, research, and algorithm documentation. ### Inline math Use single `$` delimiters for math within a sentence: ```markdown The formula is $e = mc^2$ where $c$ is the speed of light. ``` **Renders as:** The formula is $e = mc^2$ where $c$ is the speed of light. ### Block math Use `$$` delimiters for display-style (centered, larger) math on their own lines: ```markdown $$ \sum_{i=1}^{n} x_i = \frac{n(n+1)}{2} $$ ``` ### Common LaTeX patterns The following table shows some LaTeX patterns you might encounter. | What you want | LaTeX | Rendered | |---|---|---| | Superscript | `$x^2$` | $x^2$ | | Subscript | `$x_i$` | $x_i$ | | Fraction | `$\frac{a}{b}$` | $\frac{a}{b}$ | | Square root | `$\sqrt{x}$` | $\sqrt{x}$ | | Greek letter | `$\alpha, \beta, \gamma$` | $\alpha, \beta, \gamma$ | | Summation | `$\sum_{i=1}^{n}$` | $\sum_{i=1}^{n}$ | | Not equal | `$\neq$` | $\neq$ | | Less or equal | `$\leq$` | $\leq$ | ### Screen Reader Note Math expressions rendered by MathJax include `aria-label` attributes with the spoken form of the equation. Screen readers should announce the math correctly, but accuracy varies: - NVDA with Firefox or Chrome: reads MathML fairly well - JAWS: reads the aria-label text - VoiceOver: reads the aria-label text **Best practice:** If writing documentation for an accessibility-focused audience, supplement complex equations with a plain English description: ```markdown The sum of all values from 1 to n equals n times n+1 divided by 2: $$ \sum_{i=1}^{n} x_i = \frac{n(n+1)}{2} $$ ``` ## 24. Footnotes GitHub supports Markdown footnotes, which render as superscript numbers that link to references at the bottom of the document. They are useful for citations, additional context, and references that would interrupt the flow of the main text. ### Syntax ```markdown This technique improves screen reader navigation significantly.[^1] You can also use named footnotes for clarity.[^accessibility-note] [^1]: Based on the WebAIM Screen Reader Survey, 2024. [^accessibility-note]: See WCAG 2.2 Success Criterion 2.4.3 for focus order requirements. ``` ### How they work 1. In your text, add `[^identifier]` where you want the footnote reference to appear 2. Anywhere in the document (typically at the bottom), define the footnote with `[^identifier]: Your footnote text` 3. GitHub renders the reference as a superscript number that links to the definition 4. The definition includes a back-link that returns to the reference location ### Footnote identifiers - You can use numbers: `[^1]`, `[^2]`, `[^3]` - You can use descriptive names: `[^webaim-survey]`, `[^wcag-reference]` - Descriptive names make the raw Markdown more readable but render as sequential numbers ### Multi-line footnotes Indent continuation lines with two spaces: ```markdown [^long-note]: This is a longer footnote that spans multiple paragraphs. The second paragraph of the footnote is indented with two spaces. You can even include code: `git status` ``` ### Screen Reader Behavior - The footnote reference is a link (`` element) announcing its number - NVDA: "superscript, 1, link" - JAWS: "link, 1" - VoiceOver: "link, footnote 1" - The back-link at the definition reads "return to footnote reference" - Activating the footnote link jumps focus to the definition; activating the back-link returns focus to the original location ## 25. Linked Heading Anchors and Tables of Contents Every heading in a GitHub Markdown file automatically gets an anchor ID. You can link to any heading from anywhere - within the same document, from another file, or from an issue or PR. ### How GitHub generates anchor IDs GitHub converts the heading text to an anchor ID by: 1. Converting to lowercase 2. Replacing spaces with hyphens 3. Removing most punctuation (except hyphens) 4. Removing leading and trailing whitespace The following table shows example headings and their generated anchors. | Heading text | Generated anchor | |---|---| | `# Introduction` | `#introduction` | | `## Getting Started` | `#getting-started` | | `### VS Code: Setup & Accessibility Basics` | `#vs-code-setup--accessibility-basics` | | `## 1. First Steps` | `#1-first-steps` | | `## What Is a PR?` | `#what-is-a-pr` | ### Linking to a heading in the same document ```markdown See the [Tables](#16-tables) section for details on formatting data. Return to the [Table of Contents](#table-of-contents). ``` ### Linking to a heading in another file ```markdown See the [Pre-Workshop Setup guide](00-pre-workshop-setup.md#step-1---create-a-github-account). ``` ### Building a table of contents You can build a manual table of contents using heading anchor links: ```markdown ## Table of Contents 1. [Introduction](#introduction) 2. [Installation](#installation) 3. [Configuration](#configuration) 4. [Usage](#usage) 5. [Contributing](#contributing) ``` ### Duplicate headings If a document has two headings with the same text, GitHub appends `-1`, `-2`, and so on to the duplicate anchors: | Heading | Anchor | |---|---| | First `## Examples` | `#examples` | | Second `## Examples` | `#examples-1` | | Third `## Examples` | `#examples-2` | **Best practice:** Avoid duplicate heading text. Use descriptive, unique headings for each section. ### Finding the anchor for any heading 1. **Mouse users:** On GitHub, hover over any heading - a chain link icon appears to the left. Click it to update the URL with the anchor 2. **Screen reader users:** Navigate to the heading, then `Tab` once. A link button appears. Activate it and the URL in the address bar updates to show the anchor 3. **Keyboard (GitHub shortcut):** There is no direct shortcut, but you can copy the heading text, convert it to the anchor format mentally, and type it in the URL ## 26. Autolinked References - Issues, PRs, Commits, and Users One of GitHub's most powerful features is automatic linking. When you type certain patterns in any Markdown field on GitHub, they automatically become clickable links. This is how the entire GitHub collaboration workflow connects. ### Issue and pull request references The following table shows how to reference issues and pull requests. | What you type | What it links to | Example | |---|---|---| | `#42` | Issue or PR number 42 in the current repo | "See #42 for details" | | `GH-42` | Same as above (alternative syntax) | "Fixed in GH-42" | | `owner/repo#42` | Issue 42 in a different repo | "Related: community-access/accessibility-agents#15" | ### User and team mentions The following table shows how to mention users and teams. | What you type | What it does | Example | |---|---|---| | `@username` | Mentions a user, sends them a notification | "Thanks @johndoe for the review" | | `@org/team-name` | Mentions an entire team | "Cc @community-access/maintainers" | ### Commit references The following table shows how to reference specific commits. | What you type | What it links to | Example | |---|---|---| | Full SHA: `a1b2c3d4e5f6...` | Links to that commit (first 7+ chars) | "Fixed in a1b2c3d" | | `owner/repo@SHA` | Commit in another repo | "See community-access/accessibility-agents@a1b2c3d" | ### Closing keywords in pull requests When you include certain keywords followed by an issue reference in a PR description, merging the PR automatically closes the referenced issue: ```markdown This PR adds alt text to all images in the documentation. Closes #42 Fixes #43 Resolves #44 ``` All of these keywords work: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`. They are case-insensitive. ### URL autolinking GitHub automatically converts full URLs into clickable links: ```markdown Check out https://github.com/community-access/accessibility-agents for the project. ``` > **Accessibility note:** While autolinked URLs work, they create poor link text for screen readers (the entire URL is read character by character). In documentation and issue descriptions, always use descriptive link text instead: `[Accessibility Agents repository](https://github.com/community-access/accessibility-agents)`. ## 27. HTML in Markdown GitHub allows a subset of HTML in Markdown files. This is useful for semantic elements that do not have Markdown equivalents, advanced layout needs, and accessibility improvements. ### Keyboard key visualization The `` element renders text in a key-cap style box: ```html Press Ctrl+C to copy. Press NVDA+Space to toggle Focus Mode. ``` Press Ctrl+C to copy. Press NVDA+Space to toggle Focus Mode. ### Subscript and superscript ```html H2O is water. E = mc2 is Einstein's equation. ``` H2O is water. E = mc2 is Einstein's equation. ### Centered content ```htmlDiagram source (Mermaid)
```mermaid flowchart LR Fork --> Clone --> Branch --> Commit --> Push --> PR --> Review --> Merge `````` ### Line breaks ```html Line one
Line two on the next line, same paragraph. ``` ### Hidden comments ```html ``` Hidden comments are useful for notes to yourself or other contributors that should not be visible to readers. ### Allowed HTML elements on GitHub GitHub whitelists specific HTML elements for security. The following table lists the most useful allowed elements. | Element | Purpose | Screen reader behavior | |---|---|---| | `` / `` | Collapsible sections | Announced as disclosure widget | | `` | Keyboard keys | Announced as "code" or the text content | | `` / `` | Subscript / superscript | Text read normally; some SRs announce position | | `
` | Line break | Brief pause in reading | | `` | Generic container | No announcement unless has role/aria | | `` | Image with attributes | Alt text read | | `` | Link with attributes | Link text read | | `
`, `
`, ` ` | Complex table | Full table navigation | | `` | Comment | Not read (invisible) | ### Disallowed HTML on GitHub GitHub strips these elements for security: - `