1
---
2
name: markdown-accessibility-checker
3
description: Reviews Markdown documentation (READMEs, docs sites, wikis, blog posts, changelogs) for accessibility - missing or poor image alt text, heading structure, vague or duplicate link text, bare URLs, empty table headers, color-only instructions, ALL CAPS, and emoji bullets - then writes good alt text for each image from context and returns a fix list or a corrected file. Use when a user asks to "check my README for accessibility", "write alt text for these images", "make our docs screen reader friendly", or wants an accessibility check for Markdown in CI.
4
---
5
6
# Markdown Accessibility Checker
7
8
You make Markdown documents work for everyone, including people who use screen readers, keyboard navigation, magnification, or reading aids. You find the problems a script can detect, then do the part a script cannot: write meaningful alt text and link text that fit the document's purpose.
9
10
## Files in this skill
11
12
- `scripts/check_md_a11y.py` - scans Markdown files or folders and reports problems with line numbers and severities (Python 3 standard library only)
13
- `references/alt-text-guide.md` - how to write alt text by image type (screenshots, diagrams, charts, photos, logos, badges, decorative images)
14
- `references/structure-and-links.md` - headings, link text, tables, lists, emphasis, and what each rule in the script means
15
- `templates/a11y-review.md` - the review report and the alt text worksheet
16
- `examples/example-readme-review.md` - a worked review of a project README
17
18
## Workflow
19
20
### 1. Scope the review
21
Ask which files or folders to check, who reads them (developers, end users, students), and whether the user wants a report, a corrected file, or both. If the documents are rendered by a site generator, ask whether it adds its own page title (then the Markdown may not need an H1).
22
23
### 2. Run the checker
24
```bash
25
python3 scripts/check_md_a11y.py README.md docs/
26
python3 scripts/check_md_a11y.py docs/ --json
27
python3 scripts/check_md_a11y.py docs/ --fail-on warn # for CI
28
```
29
It ignores fenced code blocks and inline code. HIGH means content is lost for some readers (missing alt, empty link, empty heading), WARN should be fixed, INFO needs a human look. If you cannot run the script, check the same rules by reading the file and say so.
30
31
### 3. Write alt text
32
For every image flagged, and for every image with existing alt text, decide its purpose using `references/alt-text-guide.md`:
33
- Read the text around it: what is the image for at this point in the document?
34
- If you can see the image, describe what matters for that purpose. If you cannot, ask the user, or write a clearly marked draft from the file name and context (for example "DRAFT: check against the image").
35
- Decorative images get empty alt text; in Markdown prefer removing them, or use HTML `<img alt="">`.
36
Fill in the alt text worksheet in `templates/a11y-review.md`.
37
38
### 4. Fix structure and links
39
Apply `references/structure-and-links.md`: one H1, no skipped levels, real headings instead of bold lines, descriptive unique link text, tables with headers, instructions that do not rely on color alone.
40
41
### 5. Deliver
42
- Report: fill in `templates/a11y-review.md`, as in `examples/example-readme-review.md`, with the most important fixes first.
43
- Corrected file: return the full Markdown with fixes applied and a short change list. Do not change meaning, code samples, or links' destinations.
44
- Rerun the checker on the corrected file and include the before and after counts.
45
46
## Rules
47
- Never invent what an image shows. If you have not seen it, mark the alt text as a draft.
48
- Keep alt text short (usually under 150 characters); put long explanations (charts, diagrams) in the text or a caption and say so in the alt.
49
- Do not start alt text with "image of" or "picture of".
50
- Remember that automated checks find only part of the problems; always mention what still needs a manual check (color contrast in images, reading order, video captions).
51
- Respect the author's voice; fix accessibility, not style.
52