// Markdown accessibility rule library covering ambiguous links, anchor validation, emoji handling (remove or translate to English), Mermaid and ASCII diagram replacement templates, heading structure, table descriptions, and severity scoring. Use when auditing or fixing markdown documentation for accessibility.
| name | markdown-accessibility |
| description | Markdown accessibility rule library covering ambiguous links, anchor validation, emoji handling (remove or translate to English), Mermaid and ASCII diagram replacement templates, heading structure, table descriptions, and severity scoring. Use when auditing or fixing markdown documentation for accessibility. |
Reusable knowledge module for the markdown-a11y-assistant, markdown-scanner, and markdown-fixer agents and the markdown-accessibility always-on instructions. Provides pattern libraries, severity scoring, fix templates, emoji translation maps, diagram description templates, and GitHub anchor generation rules for comprehensive markdown accessibility auditing across 9 domains.
- or leave unchanged#anchor links against actual headings| Issue | Severity | WCAG | Auto-fix? |
|---|---|---|---|
| Image missing alt text | Critical | 1.1.1 (A) | No - needs visual judgment |
| Mermaid diagram with no text alternative | Critical | 1.1.1 (A) | Partial - simple diagrams auto-described; complex need human |
| ASCII diagram with no text description | Critical | 1.1.1 (A) | Partial - flag and wrap; description needs human or auto-gen |
| Broken anchor link | Serious | 2.4.4 (A) | No - confirm which end changes |
| Ambiguous link text ("here", "click here") | Serious | 2.4.4 (A) | Yes - rewrite using surrounding context |
| Skipped heading level | Serious | 1.3.1 (A) | Yes - interpolate missing level |
| Multiple H1s | Serious | 1.3.1 (A) | Yes - demote all but first |
| Emoji in heading | Moderate | Cognitive | Yes - remove or translate per preference |
| Consecutive emoji (2+) | Moderate | 1.3.3 (A) | Yes - remove sequence or translate |
| Emoji used as bullet | Moderate | 1.3.1 (A) | Yes - replace with - |
| Em-dash in prose | Moderate | Cognitive | Yes - replace with - |
| Table without preceding description | Moderate | 1.3.1 (A) | Yes - add one-sentence summary |
| Bold text used as heading | Minor | 2.4.6 (AA) | Yes - convert to appropriate heading |
| Bare URL in prose | Minor | 2.4.4 (A) | Yes - wrap with descriptive text |
| Emoji used for meaning, single inline | Minor | 1.3.3 (A) | Conditional - remove-all: yes; remove-decorative: flag; translate: translate |
File Score = 100 - (sum of weighted findings)
Critical: -15 pts each
Serious: - 7 pts each
Moderate: - 3 pts each
Minor: - 1 pt each
Floor: 0
| Score | Grade | Meaning |
|---|---|---|
| 90-100 | A | Excellent - accessible documentation |
| 75-89 | B | Good - minor issues |
| 50-74 | C | Needs Work - several barriers |
| 25-49 | D | Poor - significant barriers |
| 0-24 | F | Failing - critical AT barriers |
The agent supports four modes configured during Phase 0:
| Mode | Description | Default? |
|---|---|---|
remove-all | Strip every emoji from prose, headings, and bullets | No |
remove-decorative | Remove emoji in headings, bullets, and consecutive sequences; flag single inline for review | Yes (default) |
translate | Replace known emoji with (English) text; flag unknown for review | No |
leave-unchanged | Do not flag or modify any emoji | No |
When using translate mode, replace each emoji with the parenthesized English equivalent:
| Emoji | Translation | Emoji | Translation |
|---|---|---|---|
| 🚀 | (Launch) | ✅ | (Done) |
| ⚠️ | (Warning) | ❌ | (Error) |
| 📝 | (Note) | 💡 | (Tip) |
| 🔧 | (Configuration) | 📚 | (Documentation) |
| 🎯 | (Goal) | ✨ | (New) |
| 🔍 | (Search) | 🛠️ | (Tools) |
| 👋 | (Hello) | 🎉 | (Celebration) |
| ⭐ | (Featured) | 💬 | (Discussion) |
| 🏠 | (Home) | 📊 | (Data) |
| 🔒 | (Security) | 🌐 | (Web) |
| 📦 | (Package) | 🔗 | (Link) |
| 📋 | (Checklist) | 🏆 | (Achievement) |
| ⚡ | (Quick) | 👍 | (Approved) |
| 👎 | (Rejected) | 🐛 | (Bug) |
| 🤝 | (Collaboration) | 🎓 | (Learning) |
| 🔑 | (Key) | 📌 | (Pinned) |
| ℹ️ | (Info) | 🔄 | (Refresh) |
| ➕ | (Add) | ➖ | (Remove) |
| 💻 | (Code) | 🔔 | (Notification) |
| 📣 | (Announcement) | 🧪 | (Test) |
| 🎨 | (Design) | 🌟 | (Highlight) |
| 📈 | (Increase) | 📉 | (Decrease) |
| 🏗️ | (Build) | 🔐 | (Locked) |
| 📂 | (Folder) | 📁 | (Folder) |
| 🗂️ | (Category) | 🗃️ | (Archive) |
| ⚙️ | (Settings) | 🏁 | (Finish) |
| 🚧 | (In Progress) | 🚫 | (Not Allowed) |
| ✔️ | (Check) | ➡️ | (Next) |
| ⬆️ | (Up) | ⬇️ | (Down) |
For emoji not in this table: flag as needs-human-review. Do not guess.
[\u{1F600}-\u{1F64F}] - Emoticons
[\u{1F300}-\u{1F5FF}] - Misc symbols and pictographs
[\u{1F680}-\u{1F6FF}] - Transport and map symbols
[\u{1F700}-\u{1F77F}] - Alchemical symbols
[\u{1F780}-\u{1F7FF}] - Geometric shapes extended
[\u{1F900}-\u{1F9FF}] - Supplemental symbols
[\u{1FA70}-\u{1FAFF}] - Symbols and pictographs extended
[\u{2600}-\u{26FF}] - Misc symbols
[\u{2700}-\u{27BF}] - Dingbats
[\u{1F1E0}-\u{1F1FF}] - Flags
[\u{FE00}-\u{FE0F}] - Variation selectors
Emoji-as-bullet pattern: list item where the first non-whitespace character is an emoji.
Lines matching ```mermaid (with optional leading spaces/tabs).
| Type | Description Template |
|---|---|
graph TD/LR/RL/BT / flowchart | "The following [direction] diagram shows: [list major nodes and connections from source]" |
sequenceDiagram | "The following sequence diagram shows the interaction between [participants]: [list each message in order]" |
classDiagram | "The following class diagram shows [N] classes: [list class names, key properties, and relationships]" |
erDiagram | "The following entity-relationship diagram shows [entities] with these relationships: [list relationships]" |
gantt | "The following Gantt chart shows project tasks: [list section names and tasks with dates if available]" |
pie | "The following pie chart shows [title] with values: [list each label and percentage/value if available]" |
stateDiagram | "The following state diagram shows [N] states: [list state names and transition triggers]" |
mindmap | "The following mind map shows [root topic] with branches: [list top-level branch names]" |
timeline | "The following timeline shows events: [list events in chronological order]" |
Auto-generate description for: graph, flowchart, pie, gantt, mindmap, timeline.
Flag for human review: sequenceDiagram, classDiagram, erDiagram, stateDiagram (complex enough to need human verification).
[Generated or user-provided text description - this is the primary accessible content]
<details>
<summary>Diagram source (Mermaid)</summary>
```mermaid
[original diagram source - unchanged]
```text
</details>
ASCII art patterns: non-code-block lines (or unnamed code blocks) containing combinations of +, -, |, /, \, >, <, ^, v, * forming a visual structure. Minimum 3 lines with consistent column alignment.
[Generated or user-provided text description - this is the primary accessible content]
<details>
<summary>ASCII diagram</summary>
[original ASCII art - unchanged]
</details>
Match these patterns (case-insensitive, trim whitespace):
here, click here, read more, learn more, more, more info,
link, details, info, go, see more, continue, start, download,
view, open, submit, this, that
click here to ..., read more about ..., learn more about ...,
here to ..., see more ...
Any link where visible text matches https?:// or www\.
Multiple [X](url1) and [X](url2) with same X but different URLs on the same page.
[](url) at top of README[Installation](#installation) where text matches headingGitHub converts headings to anchor IDs using these rules:
| Heading | Anchor |
|---|---|
# Getting Started | #getting-started |
## API: v2.0 Reference | #api-v20-reference |
### What's New? | #whats-new |
## C# and .NET Support | #c-and-net-support |
## Step 1: Installation | #step-1-installation |
## FAQ (Frequently Asked Questions) | #faq-frequently-asked-questions |
## 🚀 Quick Start | #-quick-start (emoji becomes empty, may vary) |
For headings containing emoji: GitHub strips the emoji character and generates an anchor from the remaining text. Anchors referencing emoji-containing headings are fragile and should be flagged.
Unicode emoji ranges for regex detection:
[\u{1F600}-\u{1F64F}] # Emoticons
[\u{1F300}-\u{1F5FF}] # Misc symbols and pictographs
[\u{1F680}-\u{1F6FF}] # Transport and map symbols
[\u{1F700}-\u{1F77F}] # Alchemical symbols
[\u{1F780}-\u{1F7FF}] # Geometric shapes extended
[\u{1F800}-\u{1F8FF}] # Supplemental arrows-C
[\u{1F900}-\u{1F9FF}] # Supplemental symbols and pictographs
[\u{1FA00}-\u{1FA6F}] # Chess symbols
[\u{1FA70}-\u{1FAFF}] # Symbols and pictographs extended-A
[\u{2600}-\u{26FF}] # Misc symbols
[\u{2700}-\u{27BF}] # Dingbats
[\u{FE00}-\u{FE0F}] # Variation selectors
[\u{1F1E0}-\u{1F1FF}] # Flags
Emoji-as-bullet pattern: List item where first non-whitespace character is an emoji.
Detection patterns:
- Unicode em-dash (U+2014)
- Unicode en-dash (U+2013)
--- Three hyphens in prose (not on its own line as HR)
-- Two hyphens in prose (used as em-dash substitute)
Safe to skip (do not modify):
--- (horizontal rule)``` code fences<!-- -->Replacement: - (space + hyphen + space)
En-dash in numeric ranges: 2 - 4 hours -> 2 - 4 hours
Detection: Lines matching ```mermaid (with optional leading spaces/tabs)
Diagram types and description guidance:
| Type | Description Template |
|---|---|
graph TD/LR/RL/BT | "The following diagram shows a [direction] flowchart: [list major nodes and connections]" |
sequenceDiagram | "The following sequence diagram shows the interaction between [participants]: [list message exchanges]" |
classDiagram | "The following class diagram shows [N] classes: [list class names and key relationships]" |
erDiagram | "The following entity-relationship diagram shows [entities] and their relationships: [list relationships]" |
gantt | "The following Gantt chart shows project phases: [list tasks and timeframes]" |
pie | "The following pie chart shows [title] with values: [list segment names and values if available]" |
stateDiagram | "The following state diagram shows [N] states and transitions: [list states and transition triggers]" |
Wrapping template:
[Generated or user-provided text description]
<details>
<summary>Diagram source (Mermaid)</summary>
```mermaid
[original diagram source]
```text
</details>
# Before
For more information, see [here](https://example.com/guide).
# After
For more information, see the [installation guide](https://example.com/guide).
# Before
- 🚀 Deploy to production
- ✅ Run tests
# After
- Deploy to production
- Run tests
# Before
## 🔧 Configuration
# After
## Configuration
# Before
The agent - when invoked - will scan all files.
# After
The agent - when invoked - will scan all files.
# Before
| Rule | Severity | Auto-fix |
|------|----------|----------|
# After
The following table lists rules with their severity level and whether they can be fixed automatically.
| Rule | Severity | Auto-fix |
|------|----------|----------|
# Before (broken)
See [Installation](#instalation) for setup steps.
# Heading in file
## Installation
# After (corrected)
See [Installation](#installation) for setup steps.
| Rule | Name | Accessibility Relevance |
|---|---|---|
| MD001 | heading-increment | Heading hierarchy (WCAG 1.3.1) |
| MD022 | blanks-around-headings | Parsing reliability |
| MD024 | no-duplicate-heading | Unique section identity (WCAG 2.4.6) |
| MD025 | single-title / single-h1 | One H1 per document |
| MD033 | no-inline-html | May hide structure from parsers |
| MD034 | no-bare-urls | Ambiguous links (WCAG 2.4.4) |
| MD041 | first-line-heading | Document structure |
| MD055 | table-pipe-style | Table parsing consistency |
| MD056 | table-column-count | Table structural integrity |
Command: npx --yes markdownlint-cli2 <filepath>