Markdown 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.

Markdown Accessibility Skill

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.

Domains Covered

1. Descriptive Links (WCAG 2.4.4) - Ambiguous link text, bare URLs, repeated identical text
2. Image Alt Text (WCAG 1.1.1) - Missing, empty, filename-as-alt, generic placeholders
3. Heading Hierarchy (WCAG 1.3.1 / 2.4.6) - Skipped levels, multiple H1s, bold-as-heading
4. Table Accessibility (WCAG 1.3.1) - Missing descriptions, empty headers, layout tables
5. Emoji (WCAG 1.3.3 / Cognitive) - Remove-all, remove-decorative, translate, or leave-unchanged modes
6. Mermaid and ASCII Diagrams (WCAG 1.1.1 / 1.3.1) - Replace with accessible text + collapsible source
7. Em-Dash / En-Dash Normalization (Cognitive) - Normalize to - or leave unchanged
8. Anchor Link Validation (WCAG 2.4.4) - Validate #anchor links against actual headings
9. Plain Language and List Structure (Cognitive) - Emoji bullets, passive voice, sentence length

Severity Scoring

Scoring Formula

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 Grades

Emoji Handling Modes

The agent supports four modes configured during Phase 0:

Emoji Translation Map

When using translate mode, replace each emoji with the parenthesized English equivalent:

For emoji not in this table: flag as needs-human-review. Do not guess.

Emoji Detection Unicode Ranges

[\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.

Pattern Library: Mermaid and ASCII Diagrams

Mermaid Detection

Lines matching ```mermaid (with optional leading spaces/tabs).

Mermaid Description Templates

Auto-generate description for: graph, flowchart, pie, gantt, mindmap, timeline. Flag for human review: sequenceDiagram, classDiagram, erDiagram, stateDiagram (complex enough to need human verification).

Mermaid Replacement Template

[Generated or user-provided text description - this is the primary accessible content]

<details>
<summary>Diagram source (Mermaid)</summary>

```mermaid
[original diagram source - unchanged]

ASCII Diagram Detection

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.

ASCII Diagram Replacement Template

[Generated or user-provided text description - this is the primary accessible content]

<details>
<summary>ASCII diagram</summary>

[original ASCII art - unchanged]

</details>

Pattern Library: Ambiguous Link Detection

Match these patterns (case-insensitive, trim whitespace):

Exact-match violations

here, click here, read more, learn more, more, more info,
link, details, info, go, see more, continue, start, download,
view, open, submit, this, that

Starts-with violations

click here to ..., read more about ..., learn more about ...,
here to ..., see more ...

URL-as-text pattern

Any link where visible text matches https?:// or www\.

Repeated identical text

Multiple [X](url1) and [X](url2) with same X but different URLs on the same page.

Safe patterns (do not flag)

• Badge links: [![text](img)](url) at top of README
• Section self-references: [Installation](#installation) where text matches heading
• Footer resource lists using the resource/tool name as text

Pattern Library: GitHub Anchor Generation

GitHub converts headings to anchor IDs using these rules:

1. Lowercase entire string
2. Remove all characters except: letters (a-z), digits (0-9), spaces, hyphens
3. Replace spaces with hyphens
4. Remove leading and trailing hyphens

Examples

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.

Pattern Library: Emoji Detection

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.

Pattern Library: Em-Dash and En-Dash

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):

• Line containing only --- (horizontal rule)
• Content inside ``` code fences
• Content inside backtick inline code
• YAML front matter block
• HTML comment blocks <!-- -->

Replacement: - (space + hyphen + space)

En-dash in numeric ranges: 2–4 hours -> 2 - 4 hours

Pattern Library: Mermaid Diagrams

Detection: Lines matching ```mermaid (with optional leading spaces/tabs)

Diagram types and description guidance:

Wrapping template:

[Generated or user-provided text description]

<details>
<summary>Diagram source (Mermaid)</summary>

```mermaid
[original diagram source]

Fix Templates

Ambiguous link fix

# Before
For more information, see [here](https://example.com/guide).

# After
For more information, see the [installation guide](https://example.com/guide).

Emoji bullet fix

# Before
- 🚀 Deploy to production
- ✅ Run tests

# After
- Deploy to production
- Run tests

Emoji heading fix

# Before
## 🔧 Configuration

# After
## Configuration

Em-dash fix

# Before
The agent—when invoked—will scan all files.

# After
The agent - when invoked - will scan all files.

Table description fix

# 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 |
|------|----------|----------|

Broken anchor fix

# Before (broken)
See [Installation](#instalation) for setup steps.

# Heading in file
## Installation

# After (corrected)
See [Installation](#installation) for setup steps.

Markdownlint Rules Reference

Command: npx --yes markdownlint-cli2 <filepath>