关于 markdown-accessibility
面向 Markdown 无障碍审计的可复用知识模块，供相关 Agent 和指令使用。它涵盖 9 个领域，并提供问题分级、修复模板及检测规则。
主要功能
- 01覆盖 9 类 Markdown 无障碍问题
- 02按严重程度为问题评分
- 03提供修复模板与模式库
- 04包含 Emoji 处理模式
- 05提供 Mermaid 和 ASCII 图表描述模板
- 06包含 GitHub 锚点生成规则
适用场景
- 01审查文档中的链接、图片替代文本和标题层级
- 02评估表格与图表的无障碍性
- 03按偏好处理文档中的 Emoji
- 04验证锚点链接并规范破折号
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/markdown-accessibility确认已加载。
详细介绍
Markdown 无障碍技能
供 markdown-a11y-assistant、markdown-scanner 和 markdown-fixer Agent 以及 markdown-accessibility 常驻指令使用的可复用知识模块。提供模式库、严重程度评分、修复模板、表情符号翻译映射、图表描述模板以及 GitHub 锚点生成规则，用于全面审计 Markdown 在 9 个领域的无障碍性。
覆盖领域
- 描述性链接（WCAG 2.4.4）- 含义模糊的链接文本、裸 URL、重复的相同文本
- 图片替代文本（WCAG 1.1.1）- 缺少替代文本、替代文本为空、以文件名作为替代文本、通用占位文本
- 标题层级（WCAG 1.3.1 / 2.4.6）- 跳过级别、多个 H1、用粗体代替标题
- 表格无障碍性（WCAG 1.3.1）- 缺少描述、表头为空、布局表格
- 表情符号（WCAG 1.3.3 / 认知）- 全部移除、移除装饰性表情符号、翻译或保持不变模式
- Mermaid 和 ASCII 图表（WCAG 1.1.1 / 1.3.1）- 替换为无障碍文本和可折叠源代码
- 长破折号 / 短破折号规范化（认知）- 规范化为
-或保持不变 - 锚点链接验证（WCAG 2.4.4）- 根据实际标题验证
#anchor链接 - 通俗语言和列表结构（认知）- 表情符号项目符号、被动语态、句子长度
严重程度评分
| 问题 | 严重程度 | WCAG | 可自动修复？ |
|---|---|---|---|
| 图片缺少替代文本 | 严重 | 1.1.1 (A) | 否 - 需要视觉判断 |
| Mermaid 图表没有文本替代内容 | 严重 | 1.1.1 (A) | 部分 - 简单图表可自动描述；复杂图表需要人工处理 |
| ASCII 图表没有文本描述 | 严重 | 1.1.1 (A) | 部分 - 标记并包裹；描述需要人工编写或自动生成 |
| 锚点链接失效 | 严重 | 2.4.4 (A) | 否 - 需确认要更改哪一端 |
| 含义模糊的链接文本（“here”“click here”） | 严重 | 2.4.4 (A) | 是 - 根据周围上下文重写 |
| 跳过标题级别 | 严重 | 1.3.1 (A) | 是 - 插入缺失级别 |
| 多个 H1 | 严重 | 1.3.1 (A) | 是 - 将除第一个以外的所有 H1 降级 |
| 标题中的表情符号 | 中等 | 认知 | 是 - 根据偏好移除或翻译 |
| 连续的表情符号（2 个及以上） | 中等 | 1.3.3 (A) | 是 - 移除连续表情符号或翻译 |
| 将表情符号用作项目符号 | 中等 | 1.3.1 (A) | 是 - 替换为 - |
| 正文中的长破折号 | 中等 | 认知 | 是 - 替换为 - |
| 表格前没有描述 | 中等 | 1.3.1 (A) | 是 - 添加一句话摘要 |
| 用粗体文本作为标题 | 轻微 | 2.4.6 (AA) | 是 - 转换为适当级别的标题 |
| 正文中的裸 URL | 轻微 | 2.4.4 (A) | 是 - 加上描述性文本 |
| 单独在行内用于表达含义的表情符号 | 轻微 | 1.3.3 (A) | 视情况而定 - 全部移除模式：是；移除装饰性表情符号模式：标记；翻译模式：翻译 |
评分公式
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
评分等级
| 分数 | 等级 | 含义 |
|---|---|---|
| 90-100 | A | 优秀 - 文档无障碍 |
| 75-89 | B | 良好 - 存在轻微问题 |
| 50-74 | C | 需要改进 - 存在多处障碍 |
| 25-49 | D | 较差 - 存在显著障碍 |
| 0-24 | F | 不合格 - 存在严重的辅助技术障碍 |
Emoji 处理模式
Agent 支持四种模式。当前模式由作用范围内最近的 markdown-accessibility.instructions.md 文件决定。如果没有说明文件设置模式，则默认使用 remove-decorative。
此仓库： 此仓库中的
.github/instructions/markdown-accessibility.instructions.md文件将模式设为remove-all。所有 emoji 都会被移除，而非翻译。此设置优先于技能默认值。
| 模式 | 描述 | 默认？ |
|---|---|---|
remove-all | 移除正文、标题和项目符号中的所有 emoji。保留周围纯文本的含义。 | 否（仓库覆盖设置为此模式） |
remove-decorative | 移除标题、项目符号和连续序列中的 emoji；标记单个行内 emoji 以供审核 | 技能默认值（无覆盖设置） |
translate | 将已知 emoji 替换为英文括号文本；标记未知 emoji 以供审核 | 否 |
leave-unchanged | 不标记或修改任何 emoji | 否 |
模式解析顺序：
- Agent 系统提示或每项任务的显式模式覆盖设置
- 作用范围内最近的
*.instructions.md文件（例如.github/instructions/markdown-accessibility.instructions.md） - 技能默认值（
remove-decorative）
Emoji 翻译映射表
使用 translate 模式时，将每个 emoji 替换为括号括起的英文对应词：
| Emoji | 翻译 | Emoji | 翻译 |
|---|---|---|---|
| 🚀 | (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) |
对于不在此表中的 emoji：标记为 needs-human-review。不要猜测。
Emoji 检测 Unicode 范围
[\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 项目符号模式：首个非空白字符为 emoji 的列表项。
模式库：Mermaid 和 ASCII 图表
Mermaid 检测
匹配 ```mermaid 的行（可带前导空格或制表符）。
Mermaid 描述模板
| 类型 | 描述模板 |
|---|---|
graph TD/LR/RL/BT / flowchart | "以下 [direction] 图展示了：[列出源图中的主要节点及其连接]" |
sequenceDiagram | "以下时序图展示了 [participants] 之间的交互：[按顺序列出每条消息]" |
classDiagram | "以下类图展示了 [N] 个类：[列出类名、关键属性和关系]" |
erDiagram | "以下实体关系图展示了 [entities] 及其关系：[列出各项关系]" |
gantt | "以下甘特图展示了项目任务：[列出各分区名称及任务，如有日期则一并列出]" |
pie | "以下饼图展示了 [title]，数值为：[列出每个标签及百分比/数值（如有）]" |
stateDiagram | "以下状态图展示了 [N] 个状态：[列出状态名称和转换触发条件]" |
mindmap | "以下思维导图展示了 [root topic] 及其分支：[列出各一级分支名称]" |
timeline | "以下时间线展示了各事件：[按时间顺序列出事件]" |
自动生成以下类型的描述：graph、flowchart、pie、gantt、mindmap、timeline。
标记以下类型以供人工审核：sequenceDiagram、classDiagram、erDiagram、stateDiagram（复杂度较高，需要人工核验）。
Mermaid 替换模板
[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 图检测
ASCII 艺术图模式：非代码块行（或未命名代码块）中包含 +、-、|、/、\、>、<、^、v、* 的组合，且形成可视结构。至少包含 3 行，且列对齐一致。
ASCII 图替换模板
[Generated or user-provided text description - this is the primary accessible content]
<details>
<summary>ASCII diagram</summary>
[原始 ASCII 艺术图 - 保持不变]
</details>
模式库：模糊链接检测
匹配以下模式（不区分大小写，去除首尾空白）：
完全匹配违规项
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 ...
URL 作为文本的模式
任何可见文本匹配 https?:// 或 www\. 的链接
重复的相同文本
同一页面上存在多个 [X](url1) 和 [X](url2)，其中 X 相同但 URL 不同。
安全模式（不标记）
- 徽章链接：README 顶部的
[](url) - 章节自引用：文本与标题相符的
[Installation](#installation) - 使用资源/工具名称作为文本的页脚资源列表
模式库：GitHub 锚点生成
GitHub 使用以下规则将标题转换为锚点 ID：
- 将整个字符串转换为小写
- 移除除以下字符以外的所有字符：字母（a-z）、数字（0-9）、空格、连字符
- 将空格替换为连字符
- 移除开头和结尾的连字符
示例
| 标题 | 锚点 |
|---|---|
# 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（表情符号会变为空，结果可能不同） |
对于包含表情符号的标题：GitHub 会剥离表情符号，并根据剩余文本生成锚点。引用包含表情符号标题的锚点不稳定，应予以标记。
模式库：表情符号检测
用于正则检测的 Unicode 表情符号范围：
[\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
表情符号作为项目符号的模式：列表项的第一个非空白字符是表情符号。
模式库：长破折号和短破折号
检测模式：
— 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)
可安全跳过（不修改）：
- 仅包含
---的行（水平分隔线） ```代码围栏中的内容- 反引号行内代码中的内容
- YAML front matter 块
- HTML 注释块 ``
替换为：-（空格 + 连字符 + 空格）
数值范围中的短破折号：2–4 hours -> 2 - 4 hours
模式库：Mermaid 图表
检测：匹配 ```mermaid 的行（可选前导空格/制表符）
图表类型和描述指南：
| 类型 | 描述模板 |
|---|---|
graph TD/LR/RL/BT | “以下图表展示了一个[方向]流程图：[列出主要节点和连接]” |
sequenceDiagram | “以下序列图展示了[参与者]之间的交互：[列出消息交换]” |
classDiagram | “以下类图展示了[N]个类：[列出类名和主要关系]” |
erDiagram | “以下实体关系图展示了[实体]及其关系：[列出关系]” |
gantt | “以下甘特图展示了项目阶段：[列出任务和时间范围]” |
pie | “以下饼图展示了[标题]，数值如下：[列出分段名称和数值（如有）]” |
stateDiagram | “以下状态图展示了[N]个状态和转换：[列出状态和转换触发条件]” |
包装模板：
[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.
Markdownlint 规则参考
| 规则 | 名称 | 与无障碍性的关联 |
|---|---|---|
| MD001 | heading-increment | 标题层级（WCAG 1.3.1） |
| MD022 | blanks-around-headings | 解析可靠性 |
| MD024 | no-duplicate-heading | 唯一的章节标识（WCAG 2.4.6） |
| MD025 | single-title / single-h1 | 每份文档只能有一个 H1 |
| MD033 | no-inline-html | 可能会对解析器隐藏结构 |
| MD034 | no-bare-urls | 模糊链接（WCAG 2.4.4） |
| MD041 | first-line-heading | 文档结构 |
| MD055 | table-pipe-style | 表格解析一致性 |
| MD056 | table-column-count | 表格结构完整性 |
命令：npx --yes markdownlint-cli2 <filepath>
评论
支持 Markdown