企业官网建设流程全解析

• 文档
• 教程
• 知识库

tldr 是一个面向命令行工具的协作式速查手册（cheatsheet）项目，仓库内按"平台 × 语言"组织了大量 Markdown 命令页。其中存在一类特殊的页面——别名页面（alias page），用于告诉用户某个命令其实是另一个命令的别名，并引导他们查看原命令的文档。本文以保加利亚语（pages.bg）下的 clojure 命令页 为实际样本，逐行解读别名页面的结构、多语言模板约定、脚本化生成机制与自动化校验流程，帮助读者彻底理解如何在 tldr 仓库中创建、同步和检查别名页面。

从一份 7 行的保加利亚语页面说起

仓库中的 pages.bg/common/clojure.md 全文如下：

# clojure > Тази команда е псевдоним на `clj`. - Виж документацията за оригиналната команда: `tldr clj`

这份页面短小精悍，只包含三个核心信息：

1. 页面标题：# clojure，即被文档化的命令名称（文件名与标题保持一致）。
2. 描述行：> Тази команда е псевдоним наclj.，保加利亚语意为"此命令是clj的别名"。
3. 引导命令：tldr clj，提示用户用 tldr 客户端查看原命令clj的完整文档。

它的存在价值在于：当用户在终端中输入clojure时，tldr 客户端匹配到的页面能明确告知"这是一个别名"，并快速跳转到真正的命令页 pages/common/clj.md，而不是让用户陷入"为什么这个命令查不到详细用法"的困惑。

别名页面的通用格式约定

别名页面并非保加利亚语独有，它是 tldr 仓库中的一种标准页面类型。仓库的维护规范 contributing-guides/style-guide.md 在第 96～123 行（Aliases小节）对此有明确约定：

如果一个命令可以用其他名字调用（例如vim可以通过vi调用），可以创建别名页面，把用户引导到原命令名。

规范给出了通用模板：

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

并以vi为例展示了真实写法：

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

在仓库中，英文版 pages/common/clojure.md 恰好就是这个模板的又一实例：

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

可以看到，保加利亚语页面 pages.bg/common/clojure.md 与英文页面在结构上完全一一对应，只是描述行与引导行被翻译成了保加利亚语。这种"英文模板 + 本地化翻译"的模式正是整个仓库多语言协作的基础。

为什么clojure需要一张别名页

要理解这张页面的意义，需要回到原命令clj本身。仓库中的 pages/common/clj.md 记录了clj的用途：

Clojure tool to start a REPL or invoke a function with data. All options can be defined in adeps.ednfile.

也就是说，clj是 Clojure 生态中启动 REPL、调用函数的主要命令行工具，并且所有选项都可以在deps.edn文件中配置。其速查页给出的典型用法包括：

• 启动一个交互式 REPL：clj
• 执行一个函数：clj -X {{namespace/function_name}}
• 运行指定命名空间的主函数：clj -M {{[-m|--main]}} {{namespace}} {{args}}
• 解析依赖、下载库并构建/缓存 classpath 以准备项目：clj -P
• 启动带 CIDER 中间件的 nREPL 服务器：clj -Sdeps '{:deps {nrepl {:mvn/version "0.7.0"} cider/cider-nrepl {:mvn/version "0.25.2"}\}\}' {{[-m|--main]}} nrepl.cmdline --middleware '["cider.nrepl/cider-middleware"]' --interactive
• 为 ClojureScript 启动 REPL 并打开浏览器：clj -Sdeps '{:deps {org.clojure/clojurescript {:mvn/version "1.10.758"}\}\}' {{[-m|--main]}} cljs.main {{[-r|--repl]}}

clojure命令在功能上等价于clj，因此仓库为它单独建立别名页而非重复展开全部用法。这样做的好处很明确：避免同一工具在不同命令名下维护多份几乎重复的文档，当clj的用法更新时只需维护一份正文页，别名页始终保持"指向原命令"的轻量形态。

多语言模板：alias-pages.md 与保加利亚语条目

为了让所有语言的别名页面保持完全一致的格式，仓库维护了一份官方翻译模板清单：contributing-guides/translation-templates/alias-pages.md。这份文件按语言（en、ar、bg、zh、zh_TW等 40 余种）分别给出了别名页面的标准译文。

其中保加利亚语（bg）模板位于该文件第 81～91 行：

# example > Тази команда е псевдоним на `example`. - Виж документацията за оригиналната команда: `tldr example`

对照 pages.bg/common/clojure.md 可以确认：该页面就是把模板中的三个example占位符分别替换为页面标题clojure、原命令名clj和文档引导命令clj之后得到的结果。同样的规则也适用于其他保加利亚语别名页，例如 pages.bg/common/vi.md（vi→vim）、pages.bg/common/pip3.md（pip3→pip）、pages.bg/common/c++.md（c++→g++）、pages.bg/common/r2.md（r2→radare2）以及 pages.bg/common/helix.md（helix→hx），它们共享同一套保加利亚语措辞："Тази команда е псевдоним наxxx."。

这种模板机制的工程意义在于：语言团队只需维护一份标准译文，就能保证该语言下所有别名页面风格统一，且脚本可以据此自动生成、比对和同步页面。

源码视角：set-alias-page.py 如何生成别名页面

别名页面并非全部靠手工复制粘贴。仓库提供了专门的维护脚本 scripts/set-alias-page.py，用于"生成或更新别名页面"，其核心逻辑与模板机制深度绑定。

脚本中有一个名为generate_alias_page_content的函数（scripts/set-alias-page.py），职责就是把语言模板中的example占位符替换成真实命令：

def generate_alias_page_content( template_content: str, page_content: AliasPageContent, ) -> str: template_command = "example" # Replace placeholders in template with actual values result = template_content.replace(template_command, page_content.title, 1) result = result.replace(template_command, page_content.original_command, 1) result = result.replace(template_command, page_content.documentation_command) return result

可以看到，脚本按顺序完成三次替换：第一次把首个example换成页面标题（# clojure），第二次把描述行内码片中的example换成原命令（clj），第三次把tldr example换成文档引导命令（clj）。这与 pages.bg/common/clojure.md 的实际内容完全吻合。

set_alias_page函数（scripts/set-alias-page.py）则负责实际落盘：先通过get_locale（定义于 scripts/_common.py）从路径解析出语言区域（例如从pages.bg/...解析出bg），再校验该语言的模板是否存在；随后用正则剥离已有页面的占位内容（把标题行改为#、把命令改为空码片、把tldr x改为tldr），与模板比对以判断页面是否需要更新。模板本身由 scripts/_common.py 的get_templates函数从 contributing-guides/translation-templates/alias-pages.md 中解析加载。

该脚本支持的命令行参数包括：

典型用法示例（源自脚本的 usage 文档）：

# 1. 交互式创建一个新的别名页面 python3 scripts/set-alias-page.py -p osx/gsum # 2. 读取英文别名页面，同步到所有语言的翻译 python3 scripts/set-alias-page.py -S # 3. 只同步巴西葡萄牙语 python3 scripts/set-alias-page.py -S -l pt_BR # 4. 同步并暂存修改 python3 scripts/set-alias-page.py -Ss # 5. 预览将要发生的变更（不实际修改） python3 scripts/set-alias-page.py -Sn

交互式向导（prompt_alias_page_info函数，scripts/set-alias-page.py）会依次询问页面标题、原命令名和文档引导命令，并给出生成页面的预览，确认后才会写入。需要注意的是，脚本文档也提示该脚本的同步模式会产生较多误报，建议仅用-l限定语言并人工核对改动。

质量控制：别名页面如何通过自动化检查

tldr 仓库对页面格式有严格的自动化校验，别名页面也不例外。从 scripts/test.sh 可以看到测试流水线主要由三部分组成：

• 用markdownlint对所有pages*目录下的.md文件做 Markdown 格式检查（scripts/test.sh）；
• 用tldr-lint（npm 包）对各语言页面做 tldr 专用规则检查（scripts/test.sh）；
• 对scripts目录执行black、flake8、pytest、shellcheck等代码质量检查（scripts/test.sh）。

其中语言相关的 lint 规则由 scripts/test-tldr-lint.sh 控制：默认忽略TLDR104规则，而对从右到左书写的语言（如ar、fa）额外忽略TLDR003、TLDR004、TLDR015，对中文则忽略TLDR003、TLDR004、TLDR005、TLDR015。保加利亚语页面不在特殊豁免列表中，意味着它需要满足更完整的 lint 规则集。此外，scripts/set-alias-page.py 自身也内置了test_ignore_files等 pytest 用例，确保脚本的解析逻辑本身可回归验证。

用户侧体验：客户端如何利用别名页

从使用者的角度看，别名页面的最后一行tldr clj就是实际可执行的命令。tldr 客户端文档 pages/common/tldr.md 说明了基本用法：

• tldr {{command}}：打印某个命令的速查页；
• tldr {{[-L|--language]}} {{language_code}} {{command}}：按指定语言打印（可用则用，否则回退英文）；
• tldr {{[-p|--platform]}} {{platform}} {{command}}：按平台打印。

因此在支持语言选择的客户端上，保加利亚语用户执行tldr -L bg clojure（或客户端按LANG自动匹配）时，会优先命中 pages.bg/common/clojure.md 这张保加利亚语别名页；再按页面提示执行tldr clj，就能看到clj的完整速查页 pages/common/clj.md。这条"别名页 → 原命令页"的跳转链路，就是 tldr 让别名命令与主命令共享一套文档的设计核心。

小结

本文以保加利亚语 pages.bg/common/clojure.md 为样本，梳理了 tldr 别名页面的完整生态：

• 格式约定来自 contributing-guides/style-guide.md 的Aliases小节；
• 多语言模板统一维护在 contributing-guides/translation-templates/alias-pages.md，保加利亚语条目位于bg小节；
• 生成与同步由 scripts/set-alias-page.py 基于模板占位符替换实现，配合 scripts/_common.py 的路径解析与模板加载工具函数；
• 质量保障由 scripts/test.sh 与 scripts/test-tldr-lint.sh 中的markdownlint、tldr-lint检查完成；
• 终端体验则由各 tldr 客户端按语言/平台路由到对应页面，实现"一行别名、指向原命令"的速查体验。

对 tldr 仓库的贡献者而言，新增或翻译一张别名页的正确路径是：先查阅目标语言在 contributing-guides/translation-templates/alias-pages.md 中的模板，然后逐字段替换example占位符，最后运行 scripts/test.sh 确认通过 lint 与 markdown 检查；批量维护时则可借助 scripts/set-alias-page.py 的交互式向导或--sync同步能力。

• 文档
• 教程
• 知识库