| name | markdown-a11y |
| description | Markdown accessibility review guidelines based on GitHub's 5 best practices for inclusive documentation. Use when the task involves `review markdown accessibility`, `make docs accessible`, `a11y review`, `markdown a11y`, or `accessible documentation`. |
| license | MIT |
| metadata | {"version":"1.0.0"} |
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:
- Missing or empty alt text on images
- Skipped heading levels or heading hierarchy issues
- Non-descriptive link text
- Emoji used as bullet points or list markers
- 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).
Why it matters: Screen readers can present all links as an isolated list. "here", "here", "here"
tells the user nothing. Each link must stand on its own.
2. Image Alt Text
<!-- BAD: empty alt text (unless intentionally decorative) -->
<!-- BAD: filename as alt text -->
<!-- BAD: generic placeholder -->
<!-- GOOD: succinct, descriptive alt text -->
<!-- GOOD: decorative image (explicitly empty alt) -->
<!-- Only valid when the image adds no informational value -->
For complex images (charts, infographics), summarize the key data in alt text and provide a
longer description:
<details>
<summary>Detailed sales breakdown</summary>
| Region | Sales | % of Total |
|--------|---------|------------|
| North | $4.5M | 45% |
| South | $3.0M | 30% |
| East | $1.5M | 15% |
| West | $1.0M | 10% |
</details>
Important: When suggesting alt text improvements, present them as recommendations. Only the
author can properly assess visual content and context.
3. Heading Hierarchy
<!-- BAD: skipped heading level (## to ####) -->
## Installation
#### Prerequisites <!-- skips H3! -->
<!-- GOOD: proper hierarchy -->
## Installation
### Prerequisites
<!-- BAD: bold text used as a fake heading -->
**Installation Steps**
First, clone the repo...
<!-- GOOD: proper heading -->
### Installation Steps
First, clone the repo...
<!-- BAD: multiple H1s -->
# My Project
...
# Getting Started <!-- second H1! -->
<!-- GOOD: single H1, sections use H2 -->
# My Project
...
## Getting Started
Note: In projects where H1 is auto-generated from front matter (e.g., Jekyll, Hugo, Docusaurus),
start content at H2.
Why it matters: Screen reader users navigate by heading level. Skipped levels break that mental
model — it's like a book jumping from Chapter 2 to Chapter 4.
4. Plain Language
<!-- BAD: unnecessarily complex -->
The aforementioned methodology facilitates the implementation
of a comprehensive authentication paradigm.
<!-- GOOD: clear, direct -->
This method sets up authentication for your project.
<!-- BAD: dense wall of text -->
The system processes incoming requests by first validating the
authentication token against the identity provider, then checking
the role-based access control permissions matrix to determine
whether the requesting entity has sufficient privileges to access
the specified resource endpoint, and finally logging the access
attempt for audit compliance purposes.
<!-- GOOD: broken into digestible pieces -->
The system handles each request in three steps:
1. **Validates the token** against the identity provider.
2. **Checks permissions** to confirm the user can access the resource.
3. **Logs the attempt** for audit compliance.
Important: When suggesting plain language improvements, present them as recommendations.
Language decisions depend on audience, context, and tone that only the author fully understands.
5. Lists and Emoji
Lists
<!-- BAD: emoji as bullet points -->
🔹 Install dependencies
🔹 Configure the database
🔹 Run migrations
<!-- GOOD: proper markdown list -->
- Install dependencies
- Configure the database
- Run migrations
<!-- BAD: sequential items in plain text -->
First install Node.js. Then install dependencies. Finally run the app.
<!-- GOOD: structured as a list -->
1. Install Node.js
2. Install dependencies
3. Run the app
Why it matters: Proper list syntax lets screen readers announce "list, 3 items" and navigate
item-by-item. Emoji bullets are read aloud in full (e.g., "small blue diamond, Install
dependencies").
Emoji
<!-- BAD: multiple consecutive emoji -->
Great job! 🚀✨🔥💯🎉
<!-- GOOD: single emoji, sparingly -->
Great job! 🎉
<!-- BAD: emoji as sole conveyor of meaning -->
Status: ✅
<!-- GOOD: meaning in text, emoji as supplement -->
Status: Passing ✅
Why it matters: Each emoji name is read aloud in full. "rocket, sparkles, fire, hundred points,
party popper" is disruptive. A single well-placed emoji enhances; a cluster of them creates noise.
Review Tone
- Explain impact: Specify who is affected — screen reader users, people with cognitive
disabilities, non-native speakers.
- Preserve voice: Accessibility and personality are not mutually exclusive. Don't flatten
engaging writing.
- Be actionable: Give specific fixes, not vague advice.
Commands
npx markdownlint-cli2 "**/*.md"
npx markdownlint-cli2 --config '{"MD001": true, "MD003": true}' "**/*.md"
npx markdownlint-cli2 --config '{"MD034": true}' "**/*.md"
Resources
