markdown-a11y

When to Use

• Reviewing markdown files (READMEs, docs, blog posts, GitHub profiles) for accessibility
• Creating new documentation and wanting to ensure inclusivity from the start
• Auditing existing markdown content for screen reader compatibility
• When asked to improve documentation quality with accessibility in mind

Critical Patterns

• Descriptive Links: Never use "click here", "here", "this", "read more" as link text. Link text must make sense when read out of context.
• Image Alt Text: Every image needs meaningful alt text. Empty alt ![]() is only acceptable for explicitly decorative images. Filenames and generic words like "screenshot" are not valid alt text.
• Heading Hierarchy: One H1 per document, never skip levels (e.g., ## to #### is a violation), and never use bold text as a fake heading.
• Proper Lists: Always use markdown list syntax (-, *, +, 1.). Never use emoji or special characters as bullet points.
• Emoji Restraint: Don't stack multiple consecutive emoji. Don't use emoji as the sole conveyor of meaning.

Review Priority

When multiple issues exist, fix in this order:

1. Missing or empty alt text on images
2. Skipped heading levels or heading hierarchy issues
3. Non-descriptive link text
4. Emoji used as bullet points or list markers
5. Plain language improvements

Code Examples

1. Descriptive Links

<!-- BAD: generic link text -->
Read my blog post [here](https://example.com).
For more info, [click here](https://example.com/docs).
Check out [this](https://example.com/guide) guide.

<!-- GOOD: descriptive, self-contained link text -->
Read my blog post "[Crafting an accessible resume](https://example.com)".
For more info, see the [API authentication guide](https://example.com/docs).
Check out the [getting started guide](https://example.com/guide).

<!-- BAD: bare URL in prose -->
See https://example.com/docs for details.

<!-- GOOD: wrapped in descriptive link -->
See the [project documentation](https://example.com/docs) for details.

<!-- BAD: identical text, different destinations -->
See [documentation](https://example.com/api) for the API.
See [documentation](https://example.com/cli) for the CLI.

<!-- GOOD: unique, distinguishable text -->
See the [API documentation](https://example.com/api).
See the [CLI documentation](https://example.com/cli).