企业官网建设流程全解析

• 文档
• 教程
• 知识库

导读

gh a11y是 GitHub CLI 无障碍（accessibility）功能的简短别名，在 tldr 项目中以“别名页（alias page）”的形式存在，其内容指向真正的原命令gh accessibility。本文以 pages.ar/common/gh-a11y.md 为主体，讲解 tldr 别名页的文档结构、多语言翻译模板、底层原命令的用法，以及仓库中负责生成与同步这些别名页的工具链，帮助你理解并正确使用、维护这类“一行式跳转”文档。

一、gh a11y是什么：一份 tldr 别名页的完整解剖

在 tldr 仓库中，gh a11y并不是一份独立的功能说明文档，而是一张“跳转卡片”，完整内容如下（阿拉伯语版）：

# gh a11y > هذا الأمر هو اسم مستعار لـ `gh accessibility`. - إعرض التوثيقات للأمر الأصلي: `tldr gh accessibility`

逐行拆解可以看到别名页的固定骨架（与英文原版 pages/common/gh-a11y.md 一一对应）：

• 第一行标题# gh a11y：以实际被用户键入的命令名作为页面标题，文件名与命令名严格一致；
• 第二行别名声明>：阿拉伯语“هذا الأمر هو اسم مستعار لـ”意为“此命令是gh accessibility的别名”，用反引号标出原命令名，这是整页唯一的“实质信息”，告知用户该命令并不独立存在；
• 第三条示例行：阿拉伯语“إعرض التوثيقات للأمر الأصلي”意为“查看原命令的文档”，并给出可复制的命令`tldr gh accessibility`，指引用户查询真正承载功能细节的页面。

这一结构在 contributing-guides/style-guide.md 的 “Aliases” 一节有明确规定：当某条命令可以以别名形式被调用（如vi之于vim）时，就创建别名页把用户引导到原命令名。tldr 别名页因此天然“内容极简”，因为它存在的意义是路由而非讲解。

二、别名背后的真实命令：gh accessibility

要理解gh a11y究竟能做什么，需要读取它指向的原命令页面 pages/common/gh-accessibility.md：

# gh accessibility > Learn about GitHub CLI's accessibility experiences. > More information: <https://cli.github.com/manual/>. - Open the GitHub Accessibility site in your browser: `gh {{[a11y|accessibility]}} {{[-w|--web]}}`

关键事实如下：

• 该命令的用途是在浏览器中打开 GitHub 官方无障碍（Accessibility）站点，用于了解 GitHub CLI 的无障碍体验；
• 示例命令使用 tldr 特有的{{占位符}}语法，其中{{[a11y|accessibility]}}表示此位置既可以写a11y也可以写完整形式accessibility，二者等价——这正是别名存在的官方佐证；
• {{[-w|--web]}}表示可选的-w/--web参数，用于强制以 Web 方式打开；
• 该页同时提供了官方手册链接（More information字段指向cli.github.com/manual/）。

因此实际使用时，以下命令效果等价：

gh a11y --web gh accessibility -w

而想查阅命令说明，则执行tldr gh accessibility即可命中上述原命令页。

三、别名页的多语言模板机制

别名页虽小，却有着完整的多语言覆盖规范。仓库在 contributing-guides/translation-templates/alias-pages.md 中为四十余种语言各准备了一份“填空模板”，统一格式如下（以英文与阿拉伯文为例）：

# example > This command is an alias of `example`. - View documentation for the original command: `tldr example`

# example > هذا الأمر هو اسم مستعار لـ `example`. - إعرض التوثيقات للأمر الأصلي: `tldr example`

模板中example是三处占位符，分别对应：页面标题、原命令名（写入第二行的反引号中）、文档查询命令（写入最后一行tldr之后）。pages.ar/common/gh-a11y.md 正是把三处占位符分别替换为gh a11y、gh accessibility、gh accessibility后的产物。

四、仓库级支撑：别名页的生成与同步工具

仓库提供了专门脚本 scripts/set-alias-page.py 来维护这些别名页，从源码可以确认其工作机制：

• 交互式创建/更新：python3 scripts/set-alias-page.py -p common/gh-a11y.md会进入向导，依次询问页面标题、原命令、文档查询命令，并展示生成预览；
• 跨语言同步：python3 scripts/set-alias-page.py -S会扫描英文别名页并同步到所有翻译目录，可用-l ar限定只同步阿拉伯语等指定语言；
• 校验模板一致性：脚本中的get_alias_command_in_page()会按模板逐项比对（标题、原命令、文档命令），并用正则剥离代码块后与“去占位符”的模板对照，非标准写法需加-i/--inexact才被认可；
• 安全操作：-n/--dry-run只预览改动，-s/--stage可将改动暂存到 Git，避免批量同步误伤已验证的翻译（脚本文档明确提示 sync 会产生较多误报）。

这意味着pages.ar/common/gh-a11y.md并非手写零散产物，而是由模板与工具共同维护、可在所有语言目录中保持一致形态的结构化文档。

五、如何在终端中验证与使用

对于终端用户，使用路径非常短：

# 查询原命令的完整说明 tldr gh accessibility # 直接执行命令打开无障碍站点 gh a11y --web

对想要自行维护别名页的贡献者，建议按 contributing-guides/style-guide.md 的 Aliases 章节核对以下要点：

1. 标题行#后必须是被调用的别名命令名，文件名与之完全一致；
2. 第二行必须说明“此命令是原命令的别名”，并使用反引号包裹原命令；
3. 最后一行必须是tldr 原命令，用最简单的方式完成跳转；
4. 翻译版本必须严格套用 alias-pages.md 中对应语言的模板，避免自由发挥。

结语

gh a11y别名页是 tldr 项目中“小而规范”的典型：它自身只有三行，却完整承载了别名路由、多语言模板、工具链同步三层设计。理解它，也就理解了 tldr 如何在数千条命令的规模下，通过一致的别名页机制让用户快速找到真正的命令文档——pages.ar/common/gh-a11y.md 指向的tldr gh accessibility，永远是该命令唯一的权威入口。

• 文档
• 教程
• 知识库