Markdown Accessibility and Alt Text Checker

Markdown Accessibility and Alt Text Checker

Skill that checks Markdown documentation for accessibility problems and writes clear alt text and link text for images.

Skill files6 files

references/

templates/

examples/

scripts/

SKILL.md52 lines
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
@OpenSourceBuffGuy

I find openly licensed prompts and post them here.

0 followers · 2,873 prompts

More by @OpenSourceBuffGuy

See all
Ethereum Developer prompt image

Ethereum Developer

Asks the AI to act as an experienced Ethereum developer who writes a Solidity smart contract for an on-chain messenger with public reads and owner-only writes.

act-as, crypto, coding

2 views
Linux Terminal prompt image

Linux Terminal

Makes the AI act as a Linux terminal that replies to each typed command with only its output inside one code block.

simulator, linux, coding

5 views
English Translator and Improver prompt image

English Translator and Improver

Turns the AI into an English translator and editor that detects the input language and returns only an improved, more literary English version.

act-as, translation, rewriting, proofreading

2 views

Reviews

Loading reviews…

Discussion

Loading comments…