Repository navigation
Known findings from the documentation accessibility check #267
Description
This issue tracks the findings the documentation accessibility check recorded when it was added. The check is scripts/check-docs-accessibility.js; it runs on every pull request that changes Markdown (.github/workflows/docs-accessibility.yml) and fails only when a pull request adds a finding. The findings it started with are counted per file and rule in scripts/docs-accessibility-baseline.json, and those counts may only go down.
Baseline on 2026-10-28: 264 findings in 37 of the 152 Markdown files it checks (root, docs/, admin/, classroom/; learning-room/ is excluded because it has deliberate defects for learners to fix).
| Rule | Findings | What a reader meets | Where |
|---|---|---|---|
emoji |
172 | Emoji names read aloud, often at the start of headings | admin/CURRICULUM_2.0_ORGANIZATION.md (123), admin/FACILITATOR_GUIDE.md (26), admin/FACILITATOR_RESOURCES.md (20), admin/FACILITATOR_OPERATIONS.md (3) |
code-fence-language |
88 | Code blocks that do not say what they contain | 34 files; the most in docs/appendix-ac-document-developer-tools.md (16) and docs/appendix-ab-advanced-agent-patterns.md (7) |
link-text |
3 | Not a barrier: the "bad example" column of the link text table in docs/appendix-c-markdown-reference.md, kept on purpose |
|
heading-single-h1 |
1 | admin/classroom admin access.md is a single URL with no title |
Fixed in the same pull request that added the check: a skipped heading level in Appendix Z, a second H1 in Appendix L, empty table headers on both registration pages, and a stray line above the title of CONTRIBUTING.md.
Pieces to pick up
- Remove emoji from the facilitator guide headings and fix the links to them #264 - emoji in the facilitator guide and resources (good first issue)
- Add language identifiers to the code blocks in three reference solutions #268 - code block languages in three reference solutions (good first issue)
- Emoji in
admin/CURRICULUM_2.0_ORGANIZATION.mdandadmin/FACILITATOR_OPERATIONS.md - Code block languages in the remaining files, a few files per pull request
- Give
admin/classroom admin access.mda title, or remove it if it is no longer needed
To see every finding with its line number: node scripts/check-docs-accessibility.js --report. When you fix some, lower the matching counts in the baseline in the same pull request.
Related, in the site template rather than the Markdown: #265 and #266.
Generated by Claude Code
Activity