企业官网建设流程全解析

• 文档
• 教程
• 知识库

导读

本文围绕仓库根目录下的 CLIENT-SPECIFICATION.md 展开，系统讲解 tldr-pages 官方客户端（Client）必须遵循的行为规范——包括标准化命令行参数、页面命名规则、pages目录与多语言翻译目录布局、{{...}}占位符渲染、平台/语言双重解析算法以及离线缓存下载策略。读完本文，你将理解一个"规范合规"的 tldr 客户端应如何实现参数解析、页面查找、语言选择与缓存更新，并能结合本仓库的实际页面（如 git-checkout.md、docker-inspect.md）与配套脚本（如 check-pr.sh）验证这些规则的落地形态。

需要先澄清一个边界：这份文档不是页面内容的书写格式规范（那是 contributing-guides/style-guide.md 的职责），它只规定"用户应如何与官方客户端交互"，即客户端与用户之间的接口契约。文档使用 RFC 2119 中的 MUST / MUST NOT / SHOULD / RECOMMENDED / MAY / OPTIONAL 等关键词表达强制与建议语义，当前规范版本为Unreleased。

核心术语：Page 与 Platform

规范首先定义了理解后续所有条款的两个基础概念：

• Page（页面）：tldr-pages 由大量pages组成，每个页面描述一个具体命令的用法。
• Platform（平台）：页面按平台（操作系统）分组，例如windows、linux、osx。其中common是特殊平台，存放"在多个平台上表现一致"的命令页面。

平台差异化处理有一条重要规则：如果一个命令在多个平台通用、但在某个平台上略有差异，则主页面仍存放在common目录，同时在差异平台的专属目录放一份针对该平台的副本。规范给出的例子是：命令foo在 mac、windows、linux 通用，但 windows 上行为不同——主页面放common，另在windows放修改后的副本。

此外，客户端SHOULD支持把common作为平台参数传入（即-p common与--platform common），以便在命令存在平台专属变体（如linux、openbsd下的版本）时，仍能强制显示通用页面。

标准化的命令行接口（CLI）

对于提供 CLI 的客户端，规范以表格形式规定了必须支持（Required）与可选支持的参数。关键约束是：一旦支持某个选项，就必须同时实现它的所有变体——例如实现-v的同时必须实现--version，实现缓存更新的客户端必须同时支持-u和--update。

关于短/长选项显示还有一条默认行为约定：当用户既未设置--short-options也未设置--long-options时，客户端SHOULD默认只显示长形式；两者同时给出时，则两种形式都显示（具体输出格式见下文"页面格式"小节）。

TTY 装饰规则：当标准输出是 TTY 时，客户端可以额外打印装饰；反之（如输出被管道重定向）则MUST NOT输出任何附加装饰。例如页面列表在非 TTY 下必须每行一个页面名，以便grep等标准工具处理。客户端也可以支持规范之外的额外自定义参数与语法。

官方示例调用：

tldr --update tldr --version tldr -l

页面名处理：空格转连字符、大小写统一

第一个不以短横线（-）开头的参数MUST被当作页面名。页面名允许包含空格与混合大小写，客户端需要透明地完成两步规范化：

• 空格 → 连字符：git checkout变为git-checkout；
• 统一转小写：eyeD3变为eyed3。

tldr 7za tldr eyeD3 # 等价于 tldr eyed3 tldr git checkout # 等价于 tldr git-checkout tldr --platform osx bash

这一规则在仓库目录结构中得到直接印证：pages/common下存在以连字符命名的页面文件，如git-checkout.md、adb-logcat.md、acme.sh-dns.md等；而7za.md、2to3.md这类带数字的命令则保持原名。

目录结构：pages 与多语言翻译目录

所有页面的主版本存放在pages目录（不直接放在其根下），内部按平台分子目录：

pages/ common/ linux/ windows/ osx/ ...etc.

客户端SHOULD支持将macos作为osx的别名。虽然客户端不必自动支持新平台（但规范RECOMMENDED支持），它们MUST NOT在 tldr-pages 新增平台时崩溃——这要求实现层面采用可动态发现的平台目录扫描，而不是硬编码平台列表。

页面文件以.md为扩展名存放在对应平台目录下，命令名与文件名的映射如下：

翻译目录：pages.<locale>

翻译目录与主pages目录平级，命名格式为pages.<locale>，其中<locale>是 POSIX Locale Name，形如<language>_<country>：

• <language>：所选语言最短的 ISO 639 语言代码；
• <country>：所选区域的双字母 ISO 3166-1 国家代码。

规范给出的例子：

• 中文（台湾）：pages.zh_TW
• 葡萄牙语（巴西）：pages.pt_BR
• 意大利语：pages.it

这些翻译目录的内部结构与主pages目录完全一致。在本仓库中可以看到大量实例：pages.zh/下含android/、common/、linux/、osx/、windows/等子目录（其中common已有 957 个页面文件），pages.zh_TW/同样具备完整的平台子目录。某语言可能还没有对应目录，或某个页面在该语言下尚无翻译——这些都属于正常状态，客户端必须容忍。

页面格式与占位符语法（{{...}} 与 {{[ | ]}}）

虽然规范的主体是客户端接口，但它也明确了页面使用的 Markdown 方言：页面以标准 CommonMark 书写，唯一的例外是{{、}}以及{{[、]}}非标准占位符语法：

• {{与}}包围示例中可编辑的值；
• {{[与]}}表示选项的短形式/长形式变体，两侧由单个|分隔——左侧是短形式，右侧是长形式。

渲染规则（MUST 级别）：

1. 客户端MAY高亮占位符，但MUST去掉其外层花括号；
2. 当选项占位符被设置为只显示短形式或只显示长形式时，MUST NOT再对其高亮（因为此时已不存在用户选择）；
3. 只显示短/长形式时，客户端MUST去掉选项占位符的方括号；
4. 使用\转义的\{\{与\}\}不应被视为占位符，而应显示字面花括号且去掉反斜杠；占位符转义仅当两侧花括号都被转义时才生效（如\{或\{{中的反斜杠必须显示）；
5. 当命令参数本身包含{}（如stash@{0}）时，外层花括号标记占位符，内层花括号必须原样显示；
6. 客户端MUST NOT因 CommonMark 规范范围内的页面格式变化而崩溃。

渲染示例（规范原文要求）：

这些语法在本仓库页面中均有真实案例：

• 短/长选项变体：git-checkout.md 使用`git checkout {{[-t|--track]}} {{remote_name}}/{{branch_name}}`，git-stash.md 使用`git stash {{[-u|--include-untracked]}}`与`git stash show {{[-p|--patch]}}`；
• 双重花括号转义：docker-inspect.md 中的 Go 模板参数完整展示了\{\{range.NetworkSettings.Networks\}\}这类转义写法；
• 命令自身含花括号：git-stash.md 的git stash show --patch {{stash@{0}}}体现了"外层花括号为占位符、内层保留"的规则；
• 嵌套占位符：windows/mount.md 中的\\{{computer_name}}\{{share_name}}展示了 Windows UNC 路径场景下的转义与嵌套处理。

仓库中的 scripts/check-errors.sh 用一组 grep 模式在 CI 中排查占位符与括号书写错误，例如检查{{[-A|--all]}}短/长选项是否被误写成{{-[a-zA-Z][a-zA-Z]|-、检查{{是否未闭合、反引号是否成对出现等，这相当于对上述渲染规则的反向校验。

页面解析算法

页面名经过空格→连字符、统一小写两步规范化后，客户端需要决策两件事：显示哪个语言的页面、显示哪个平台的页面。

平台解析

解析顺序遵循以下规则：

1. 客户端MUST默认显示"客户端所运行平台"的页面（例如运行在 Windows 11 上的客户端默认显示windows平台的页面；可用用户配置覆盖此默认行为）；
2. 若宿主平台没有该页面，MUST回退到特殊common平台；
3. 若宿主平台与common都没有，则SHOULD搜索其他平台并显示那里的页面，同时附上警告信息。

规范给出的示例：Windows 用户请求apt页面，解析顺序为windows（无）→common（无）→osx（无）→linux（找到），其中第 3、4 步顺序可互换。

这里要特别提醒：由于解析逻辑的存在，客户端可能展示不属于宿主平台的页面（例如页面只在common中存在而宿主平台没有）。因此客户端MUST NOT假设"某个命令在宿主平台上一定可执行"。规范还RECOMMENDED客户端自动探测pages目录下新增的平台。

页面找不到时：如果任何平台都找不到该页面，客户端RECOMMENDED显示错误信息并附上向tldr-pages/tldr仓库提交新 issue 的链接，链接形式如下：

https://github.com/tldr-pages/tldr/issues/new?title=page%20request:%20{command_name}

其中{command_name}是未找到的命令名。提供 CLI 且能控制退出码的客户端MUST在显示上述信息的同时以非零退出码结束（该要求自规范 v1.4 起生效）。

找到多个平台版本时：客户端MAY向用户显示一条提示，告知存在多个平台版本的页面。

语言解析

如果客户端能访问环境变量，MUST按下面的算法推导首选语言；否则（如浏览器环境）须基于所处环境的信息（如navigator.languages）做合理假设。

涉及的环境变量：

• LANG：用户首选区域，形如ll[_CC][.encoding]；
• LANGUAGE：区域优先级列表，形如l1:l2:...，用于在LANG指定的区域不可用时按序回退；
• 两者中的C或POSIX值应被忽略。

语言决定算法（MUST 执行）：

1. 检查LANG的值；若未设置，跳到第 5 步；
2. 从LANGUAGE提取优先级列表；若未设置，初始为空列表；
3. 将LANG的值追加到优先级列表末尾；
4. 按优先级列表顺序查找并使用第一个可用语言；
5. 若所有语言都不可用，回退到英语。

规范给出的完整示例表：

注意第二行的细节：LANGUAGE列表中的语言排在前面，LANG的值被追加到末尾，因此最终顺序是it, de, fr, cz, en而非cz在前。

此外，无论通过环境变量确定了何种语言，如果页面在用户首选语言下不存在，客户端MUST总是尝试回退到英语；客户端MAY在找不到首选语言页面时通知用户（可附带指向贡献指南翻译章节的链接）。规范还RECOMMENDED让语言可配置（而不只依赖环境），建议通过配置文件乃至命令行选项（如-L, --language）配置或覆盖语言；一旦用户显式指定该选项，客户端MUST严格遵守其值，MUST NOT以其他语言展示页面，否则应以恰当的错误信息失败。

LC_MESSAGES环境变量MAY存在：若客户端自身做了本地化且该变量存在，客户端MUST用它决定界面文本语言（与页面语言分开处理）；没有LC_MESSAGES时，则回退用LANG与LANGUAGE决定界面语言。

平台优先于语言（规范以 IMPORTANT 提示强烈推荐）：页面查找应优先考虑平台，即在检查下一个首选语言之前，先在每种语言下按平台查找，以保证页面解析有意义且正确。示例：在linux上设置LANG=it、LANGUAGE="it:fr:en"查找some-page：

可以看到算法先在每种语言下遍历linux平台，再遍历common平台，而不是先遍历完所有语言再切平台。本仓库的目录结构为此提供了天然支撑：pages.zh/linux/、pages.zh/common/、pages.zh_TW/linux/、pages.zh_TW/common/等目录并存，翻译目录结构（含平台子目录）与主pages完全一致，客户端可机械地按pages.<locale>/<platform>/<name>.md拼接路径探测。

缓存机制：离线页面归档的下载契约

如果合适，规范RECOMMENDED客户端实现页面缓存。一旦实现，客户端MUST从以下来源下载：

• 整个归档：https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip
• 按语言拆分的归档，格式为https://github.com/tldr-pages/tldr/releases/latest/download/tldr-pages.{{language-code}}.zip（例如tldr-pages.en.zip）
• 仅英语归档另有地址：https://github.com/tldr-pages/tldr/releases/latest/download/tldr-pages.zip

重要废弃警告（CAUTION）：在规范 2.2 版本之前，规范曾要求客户端从https://tldr.sh/assets下载归档；该地址在被弃用近两年后，已于2026 年 1 月 20 日从该位置移除（关联 PR 为 tldr-pages/tldr#20565）。仍使用旧地址的客户端将无法再下载页面——这是新实现必须规避的兼容性陷阱。

缓存还应遵循用户的语言配置（若有），避免为不使用的语言浪费磁盘空间；客户端MAY定期自动更新缓存。这与-u, --update参数形成闭环：客户端支持缓存时--update是强制实现项，下载源则必须遵守上述归档地址。

规范演进历史（Changelog 要点）

规范的变更记录本身就是客户端生态演进的重要参考，核心版本节点如下：

• v2.3（2025-03-07）：新增短/长选项（{{[ | ]}}）规范；明确common可作为受支持的平台选项；记录旧资产站点移除日期。
• v2.2（2024-03-20）：缓存下载地址改为 GitHub Releases；新增三重花括号占位符消歧要求；增加旧资产 URL 弃用提示。
• v2.1（2023-11-30）：要求支持占位符转义语法；建议自动探测pages目录新增平台。
• v2.0（2023-09-10）：建议支持macos作为osx别名；从--list中移除特殊的all平台；资产链接移除master分支；要求支持长选项；建议支持按翻译语言分别缓存归档。
• v1.5（2021-03-17）：要求页面名解析前统一转小写；归档链接改用 HTTPS。
• v1.4（2020-08-13）：要求 CLI 客户端在找不到页面时以非零退出码结束。
• v1.3（2020-06-11）：澄清语言解析中回退英语的规则；LANG/LANGUAGE对齐 GNU 规范。
• v1.2（2019-07-03）：新增-L, --language推荐选项；区域标签从 BCP-47 切换到 POSIX 风格，旧版规范废弃；明确缓存功能建议。
• v1.0（2019-01-23）：初始发布。

可以看到，现代 tldr 客户端的关键能力——占位符转义、短/长选项过滤、平台自动探测、按语言缓存、非零退出码——大多是 v1.4 之后陆续以"新增规范"形式确立的，这也解释了为什么新旧客户端在页面渲染上会存在差异。

客户端合规实现的仓库配套：lint、CI 与模板

规范定义了"客户端应当如何"，而仓库内还有一整套工具链保证"页面数据如何合规"，二者共同支撑客户端正确渲染：

1. 页面格式模板：contributing-guides/style-guide.md 定义了每个页面最多 8 条命令示例、# 命令名标题 +>简介 +> More information:链接的骨架，并要求文件名与标题一致、文件名必须小写。
2. 本地 lint：可通过npm install --global tldr-lint安装tldr-lint（别名tldrl）校验单个页面，详见 pages/common/tldr-lint.md；部分客户端还支持tldr --render path/to/tldr_page.md本地预览渲染效果。
3. 仓库级校验脚本：package.json 声明了lint-tldr-pages: tldr-lint ./pages与lint-markdown: markdownlint pages*/**/*.md两个 npm script；scripts/check-pr.sh 在 PR 上检测"平台目录出现 common 已有页面的副本"、"翻译页面缺英文原版"、"页面命令数与内容相对英文版过期"、.md扩展名缺失等异常；scripts/check-errors.sh 用 grep 规则扫描占位符、反引号配对、标点、标准流措辞等问题。
4. 翻译参数模板：contributing-guides/translation-templates/common-arguments.md 提供了path/to/file、package、username等常见占位符在数十种语言下的标准译法，是客户端渲染"可编辑值"时呈现内容的源头之一。

对于开发者而言，若要从零实现一个合规客户端，推荐按以下顺序对照规范自检：先实现-v/--version、-p/--platform等必需参数与短长选项；再实现页面名的空格→连字符、小写化规范化；接着按"平台 → common → 其他平台"的优先级实现页面查找，再叠加LANG/LANGUAGE/-L的语言解析（平台优先于语言）；最后按归档地址实现-u, --update缓存更新，并确保页面找不到时非零退出。每一步都能在本仓库的页面文件与 CI 脚本中找到对应的数据侧验证。

• 文档
• 教程
• 知识库