GitHub Copilot 无障碍文档审查指南：基于 awesome-copilot 的 Markdown 可访问性最佳实践
GitHub Copilot 无障碍文档审查指南：基于 awesome-copilot 的 Markdown 可访问性最佳实践
Markdown 是文档、README、博客与项目说明的事实标准，但「能被渲染」不等于「能被所有用户阅读」。本指南以 awesome-copilot 仓库中的 Markdown 无障碍审查指南 为核心，系统讲解描述性链接、图片替代文本、标题层级、平实语言、列表与 Emoji、多媒体及表格等七大检查维度，并给出可执行的审查优先级与语气规范。读完本文，你将掌握一套可直接用于审查与改造任意 .md 文件的完整清单，并理解每条规则背后的辅助技术原理与受影响用户群体。
一、这份指令是什么
instructions/markdown-accessibility.instructions.md 是一份面向 GitHub Copilot 的自定义指令（Custom Instruction），通过 front matter 中的 applyTo: '**/*.md' 声明其作用范围：只要 Copilot 在会话中处理 Markdown 文件，就应自动应用这套无障碍审查规则。
---
description: 'Markdown accessibility guidelines based on GitHub''s 5 best practices for inclusive documentation'
applyTo: '**/*.md'
---
指令的规则来源在文档开头有明确交代：基于 GitHub 官方博客提出的 5 条「让 GitHub 个人主页具备可访问性」的最佳实践，以及 Smashing Magazine 关于提升 Markdown 可访问性的专文。它把这两套公开方法论转写为一条条可执行的检查项——每条规则都同时给出「违规表现」与「修复方向」，并要求审查者在报告问题时解释无障碍影响。
值得一提的是，本仓库还提供了与之配套的专用 Agent Markdown Accessibility Assistant，将该指令的五项核心原则（描述性链接、图片 alt 文本、标题层级、平实语言、列表与 Emoji）固化为一个完整的审查工作流，包括与 markdownlint 的联动方式（npx --yes markdownlint-cli2 <filepath>）、「哪些问题直接改、哪些问题只标记等人工确认」的分工策略，以及改进说明的示例格式。
二、如何在项目中使用这套指令
按照 自定义指令使用说明 的说明，你有两种落地方式：
- 复制到工作区根指令：将
instructions/markdown-accessibility.instructions.md的内容复制到工作区的.github/copilot-instructions.md，让指令对当前仓库全局生效。 - 创建任务级指令文件：在工作区的
.github/instructions/目录下存放*.instructions.md文件，按任务场景按需启用。
安装后，Copilot 在处理 Markdown 文件时会自动把下文列出的检查项作为审查基准，输出问题时附带无障碍影响说明与具体修复建议。
三、核心检查维度
1. 描述性链接（Descriptive Links）
为什么重要：屏幕阅读器用户通常会把页面上的链接抽取成「链接列表」来快速导航。此时链接文本会脱离上下文被单独朗读，像 "click here"、"here"、"this"、"read more"、"link" 这样的通用文本完全无法传达目的地信息。
检查要点：
- 标记
click here、here、this、read more、link等无信息量链接文本； - 链接文本必须在脱离上下文时依然有意义；
- 标记同一页面中文本完全相同但指向不同地址的多个链接（用户听到的是重复的链接名，无法区分目标）；
- 正文中的裸 URL 应转换为描述性链接。
正反例对照（原指令示例）：
Bad: Read my blog post [here](https://example.com)
Good: Read my blog post "[Crafting an accessible resume](https://example.com)"
注意，示例中的"Good"做法把链接目标主题写进了链接文本。这与 WCAG 2.2 的 2.4.4「链接目的（Link Purpose, A 级）」直接对应——链接目的应能从文本或上下文确定（参见仓库中的 WCAG 2.2 速查表）。审查时可以顺带核对两条更细的规则：同一页面链接文本是否重复指向不同地址（违例），以及是否滥用 target="_blank" 打开新窗口（见后文「其他」小节）。
2. 图片替代文本（Image Alternative Text）
为什么重要：低视力用户依赖屏幕阅读器朗读图片描述来理解视觉内容；alt 文本同时也是搜索引擎理解图片语义的重要渠道。
检查要点：
- 标记空 alt 文本（
），除非该图片明确是装饰性用途； - 标记把文件名当 alt 的情况（如
img_1234.jpg）或通用占位符（如screenshot、image）； - alt 文本应简洁且有描述性，并包含图片中可见的全部文字；
- 相关场景使用 "screenshot of" 前缀，但不要加 "image of" 前缀——屏幕阅读器会自动宣告「图片」，重复朗读会造成冗余；
- 对复杂图片（图表、信息图），在 alt 中概述数据要点，并通过
<details>标签或链接内容提供更长的描述； - 关键边界：提出 alt 改进建议时应以「推荐给作者复核」的口吻呈现。alt 文本依赖对视觉内容与上下文的理解，只有作者本人才能准确评估——这与配套 Agent 中「alt 文本问题只标记、等人工确认」的工作流一致（见 agents/markdown-accessibility-assistant.agent.md）。
配套 Agent 还给出了一条非常实用的写作准则：把 alt 文本当作一条「推文」来写——简洁、完整、信息密度高。其示例展示了一段出色的描述性 alt：
可见优秀 alt 的共性：交代画面主体、服饰细节、背景元素与图片中出现的文字，让盲人用户获得与明眼人等价的信息量。这一点也与 WCAG 1.1.1「非文本内容（A 级）」呼应：所有非文本内容都要有文本替代物，装饰性图片则显式使用空 alt（alt=""）。
3. 标题层级（Heading Hierarchy）
为什么重要：正确的标题结构是文档的「骨架」。辅助技术用户通过标题跳转来导航页面（类似目录快捷键），视障、注意力障碍（如 ADHD）、阅读障碍（如读写困难）的用户则依赖标题快速扫描内容。
检查要点：
- 每个文档只能有一个 H1（
#），用作页面标题； - 特别提示：在 H1 由 front matter 自动生成的场景（如部分静态站点生成器），正文应从 H2 开始；
- 标题必须遵循逻辑层级，不得跳级（例如
##之后直接出现####属于违规）； - 标记用粗体文本（
**text**）冒充标题的做法——粗体没有标题语义，无法进入标题导航树。
配套 Agent 用「报纸排版」做了直观类比：最重要的内容用最大标题，逐级递减。推荐的层级结构示例：
# Welcome to My Project ← 唯一 H1
## Getting Started ← H2
### Installation ← H3
### Configuration ← H3
## Contributing ← H2
### Code Style ← H3
### Testing ← H3
这条规则与 WCAG 2.4.6「标题和标签（AA 级）」及 1.3.1「信息和关系（A 级）」对应——结构必须能以编程方式被感知。同时它与仓库中 CommonMark Markdown 指令 对 ATX 标题的语法要求（1–6 个 # 后跟空格）互补：语法正确是「渲染正确」，层级正确才是「语义正确」。
4. 平实语言（Plain Language）
为什么重要：清晰直白的文字让所有人受益，尤其是认知障碍用户、非母语使用者以及依赖翻译工具阅读文档的用户。
检查要点：
- 标记可简化但仍复杂的行话或术语堆砌；
- 偏好短句、常用词与主动语态；
- 标记过长过密、应拆分为更小段落或列表的段落；
- 描述 UI 导航时：先用平实语言写成顺序步骤（如 "open Settings, then select Preferences"），使用通用、稳定的标签，而不是图标名或视觉描述；可以补充括号形式的视觉参照（如 "(gear icon > Preferences)"），但绝不能只用视觉面包屑符号或图标名来描述导航路径——依赖颜色、形状、图标传达信息会触发 WCAG 1.3.3「感官特性（A 级）」问题；
- 关键边界：平实语言建议同样以「推荐给作者复核」的口吻提出——语言决策依赖对受众、语境与语气的理解。
配套 Agent 在「Guidelines for Excellence」中补充了一个反直觉但重要的观点：更少的词并不等于更可访问，清晰比简短更重要（"Assume fewer words always means more accessible" 是明确禁止的）。这提醒审查者不要为了「简化」而丢失必要的技术精度。
5. 列表与 Emoji 使用（Lists and Emoji Usage）
列表
- 标记用 Emoji 或特殊字符当项目符号、而非使用标准 Markdown 列表语法（
-、*、+或1.）的情况； - 标记应以列表呈现却写成纯文本的连续项目；
- 原理：正确的列表标记让屏幕阅读器能宣告列表上下文（如 "item 1 of 3"），帮助用户了解内容规模与进度。
Emoji
- 标记连续堆叠的多个 Emoji——屏幕阅读器会把每个 Emoji 的完整名称逐一朗读出来（如 "rocket"、"sparkles"、"fire"），造成严重的听觉噪音；
- 标记「含义只通过 Emoji 传达、未同步用文字表达」的情况——当 Emoji 承载意义时，失去视觉的用户会彻底错过信息；
- Emoji 应克制而有目的性地使用。
配套 Agent 进一步解释：屏幕阅读器会朗读 Emoji 的官方全名（如 "face with stuck-out tongue and squinting eyes"），而且部分浏览器/设备并不支持所有 Emoji 变体。这一点与仓库 README.md 的实践形成对照——项目头部虽使用 Emoji 装饰，但所有关键信息（资源分类、安装方式）都以文字承载，装饰性 Emoji 不传递唯一语义。
6. 多媒体（Multimedia）
- 视频必须提供字幕（captions），录音必须提供文字记录（transcripts）——对应 WCAG 1.2.1（纯音频/纯视频，A 级）与 1.2.2（预录视频字幕，A 级）；
- 禁止自动播放音频与视频；
- 建议动图（GIF 等）与其他动画在页面加载时处于暂停状态——对应 WCAG 2.2.2「暂停、停止、隐藏（A 级）」：自动更新的内容必须可以被暂停。
7. 其他（Other）
- 链接：避免在新标签页或新窗口打开链接。
target="_blank"会打断辅助技术用户的浏览上下文，且常伴随焦点不迁移的问题； - 粗体与斜体：屏幕阅读器通常不会朗读粗体/斜体的强调效果，因此关键信息不能只依赖这类样式呈现——强调必须同时通过语言结构（如"重要"、"注意"措辞、标题层级）传递；
- 表格：表格只用于数据，不得用于页面布局；避免嵌套表格；避免复杂表格——标准 Markdown 难以将其转换为可访问格式。对应 WCAG 1.3.1：布局表格会干扰辅助技术对表格语义的解析。
四、审查优先级：资源有限时的处理顺序
当一份文档同时存在多个问题时，原指令明确给出了推荐的处理顺序。这是一个重要的工程决策——无障碍改进不是「平均用力」，而是优先消除「完全阻断访问」的问题：
| 优先级 | 检查项 | 影响等级 |
|---|---|---|
| 1 | 图片缺失或空的 alt 文本 | 内容对屏幕阅读器用户完全不可见 |
| 2 | 标题层级跳级或层级错误 | 结构导航失效，扫描困难 |
| 3 | 无描述性链接文本 | 链接列表导航效率骤降 |
| 4 | Emoji 用作项目符号或列表标记 | 听觉噪音、语义丢失 |
| 5 | 平实语言改进 | 认知障碍与非母语用户理解门槛 |
| 6 | 多媒体问题 | 音视频信息不可达 |
| 7 | 其他（新窗口链接、表格布局等） | 体验细节 |
这个优先级排序与 WCAG 2.2 无障碍标准指令 的严重度分级思想一脉相承——那里把问题划分为 CRITICAL（用户完全无法访问，合并前必须修复）、IMPORTANT（对辅助技术用户构成显著障碍，当迭代修复）、SUGGESTION（改进可用性，后续规划），本文档的「缺失 alt 文本」正属于 CRITICAL 层级。
五、审查语气：解释影响，而非机械报错
原指令对审查者的输出方式提出了三条明确要求，这也是这套指令区别于普通 lint 规则的核心：
- 解释每个问题的无障碍影响，并指明受影响的具体用户群——例如「屏幕阅读器用户」「认知障碍人士」「非母语使用者」。仅有「这里用了 emoji 当项目符号」是不够的，必须说明「屏幕阅读器会逐个朗读 emoji 全名，连续多个 emoji 会造成严重听觉噪音」；
- 不要抹去写作中的个性与声音——无障碍与有吸引力的内容并不互斥。不要把文档改造成干瘪的模板语言；
- 建议必须可操作、够具体——给出具体的改写方向，而不是泛泛而谈的「请改进」。
配套 Agent 提供的「改进说明示例」展示了理想形态：逐条列出改动位置（行号）、before/after 对照、命中的原则、以及「哪些用户如何受益」的影响描述。这种「改一条、讲清一条」的汇报格式，既教育了文档作者，也让审查结论可复核。
六、与 markdownlint 的分工：机器与语义各管一摊
原指令虽未直接提及 linter，但配套 Agent 给出了清晰的分工模型，值得在团队内推广：
- markdownlint 能抓的（结构性）：标题跳级（MD001）、标题周围缺空行（MD022）、应格式化为链接的裸 URL（MD034）等语法问题；
- markdownlint 抓不到的（语义性，需人工/审查者判断）：标题层级是否在语义上合理、链接是否有描述性、alt 文本是否恰当、Emoji 是否被滥用当列表标记、平实语言与可读性问题。
推荐的协作流程是：先通读文档理解内容与结构 → 运行 npx --yes markdownlint-cli2 <filepath> 捕获结构问题 → 结合 linter 结果做无障碍语义评估 → 确定修复方案（例如 linter 报告 h1 → h4 跳级时，由审查者判断 h4 应该降为 h2 还是 h3）。
七、反例速查表
将原指令的检查项压缩为一张「开合清单」，适合贴在文档评审的入口处：
| 违例现象 | 正确做法 | 主要受影响用户 |
|---|---|---|
click here、read more、link |
描述性链接文本，脱离上下文可理解 | 屏幕阅读器用户（链接列表导航） |
 或 alt="img_1234.jpg" |
简洁描述性 alt，含图中文字；装饰图用空 alt | 低视力/盲人用户 |
| 多个链接文本相同、指向不同 | 链接文本唯一化，带目标语境 | 屏幕阅读器用户 |
一个文档多个 # |
全文档仅一个 H1 | 标题导航用户 |
## 直接跳到 #### |
逐级递进，不跳级 | 标题导航用户 |
**粗体** 冒充标题 |
使用真实标题语法 | 结构导航用户 |
| 术语堆砌、长句长段 | 短句、常用词、主动语态、拆分段落 | 认知障碍、非母语用户 |
| 用图标/视觉面包屑描述导航 | 平实文字步骤 + 括号视觉参照 | 认知障碍、屏幕阅读器用户 |
| Emoji 当项目符号、连用多个 Emoji | 标准列表语法；Emoji 克制使用 | 屏幕阅读器用户 |
| 视频无字幕、音频无记录 | 提供字幕与文字记录 | 听障用户 |
| 自动播放音视频 | 关闭自动播放，动画默认暂停 | 认知障碍、注意力敏感用户 |
| 链接新窗口打开 | 同窗口打开，避免打断浏览上下文 | 所有用户（尤其辅助技术用户） |
| 关键信息只靠粗体/斜体 | 同步通过措辞与结构强调 | 屏幕阅读器用户 |
| 表格做布局、嵌套表、复杂表 | 仅数据用表格，结构简单 | 屏幕阅读器用户 |
八、总结
Markdown 无障碍不是「给图片加个 alt」的单点修补，而是一套贯穿写作与审查的完整方法论。以 markdown-accessibility.instructions.md 为核心的这套实践，把描述性链接、alt 文本、标题层级、平实语言、列表与 Emoji、多媒体与表格七类检查项，配上明确的审查优先级与「解释影响、保留个性、给出可操作建议」的语气规范，形成了一份可以直接嵌入 GitHub Copilot 工作流的可执行标准。
在本仓库中，它可以与 WCAG 2.2 无障碍标准指令（提供权威成功标准与严重度分级）、CommonMark/GFM 语法指令（保证渲染正确性）以及 Markdown Accessibility Assistant Agent（提供与 markdownlint 联动的完整审查工作流）组合使用，构成「语法正确 → 语义正确 → 语义可达」的三层保障。对任何以 Markdown 为第一写作载体、并希望文档真正服务所有读者的项目来说，这套指南都值得作为默认的文档评审基线。