企业官网建设流程全解析

• 文档
• 教程
• 知识库

本文以 tldr 仓库中的阿拉伯语别名页面 pages.ar/common/npm-list.md 为核心样本，完整拆解 tldr 项目中"别名页面（alias pages）"的文档设计：它如何通过多语言模板与自动化脚本生成、如何被命名校验与 linter 守护，以及使用者如何借助它直达原命令npm ls的完整文档。读完本文，你将掌握 tldr 别名页面的结构规范、多语言同步流程与底层脚本实现，并能够熟练阅读、使用乃至贡献这类页面。

一、关联文档速览：一个六行的阿拉伯语别名页

npm list在 npm 中并不是一个独立功能，而是npm ls的别名。tldr 项目为此在 pages.ar/common/npm-list.md 中单独建立了一张阿拉伯语页面，全文仅由三部分组成：

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

逐行解读：

• 第一行：以#开头的标题，必须与文件名npm-list完全一致（文件名要求全小写）；
• 描述行（>）：阿拉伯语说明"此命令是npm ls的别名"，并用反引号标出原命令名npm ls；
• 示例区：唯一的示例是"查看原命令的文档"，命令为`tldr npm ls`。

这张页面自身不承载命令参数，它的全部职责是引导用户去查阅原命令页面。这与 tldr "社区协作的命令行速查表"的定位直接相关——当一条命令只是另一条命令的别名时，不再重复维护一份参数文档，而是通过别名页跳转，避免内容重复和版本漂移。

二、别名页是什么：tldr 文档体系中的一类特殊页面

2.1 别名页 vs 普通页面的定位差异

tldr 仓库在pages/（英文）及各pages.xx/（翻译）目录下存放两类页面：

• 普通页面：如 pages.en/common/npm-ls.md，直接讲解命令的用法、参数与示例；
• 别名页面（alias pages）：如 pages.en/common/npm-list.md，仅说明"本命令是某命令的别名"并给出跳转命令。

以npm ls的英文原页面对照，可以看出普通页面承载的信息密度：

# npm ls > Print installed packages to `stdout`. > More information: <https://docs.npmjs.com/cli/npm-ls/>. - Print all versions of direct dependencies in the current project to `stdout`: `npm {{[ls|list]}}` - Print all installed packages including peer dependencies: `npm {{[ls|list]}} {{[-a|--all]}}` - Print all globally installed packages: `npm {{[ls|list]}} {{[-g|--global]}}` - Print dependencies with extended information: `npm {{[ls|list]}} {{[-l|--long]}}` - Print dependencies in parseable format: `npm {{[ls|list]}} {{[-p|--parseable]}}` - Print dependencies in JSON format: `npm {{[ls|list]}} --json`

而别名页 pages.en/common/npm-list.md 只有：

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

2.2{{[ls|list]}}占位符的意义

注意原命令页中{{[ls|list]}}这种写法：它并非 npm 的参数，而是 tldr 的**选项占位符（option placeholder）**语法，表示"用户既可以敲npm ls也可以敲npm list"。tldr 客户端在渲染时会据此高亮可替换片段，并在支持的环境下让用户自行选择展示短选项还是长选项。这也是为什么项目要单独为npm list建别名页——它是 npm 官方认可的命令写法，用户在终端里真的会敲npm list，但它的文档主体却在npm ls名下。

三、多语言模板机制：别名页的"骨架"从哪来

为了让 40 多种语言的别名页保持统一结构，仓库在 contributing-guides/translation-templates/alias-pages.md 中集中维护了一套按语言分节的模板。每个小节以### ar、### zh这样的语言标签开头，紧随其后是markdown代码块中的完整模板。

其中ar（阿拉伯语）模板与本文的npm list页面逐字对应：

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

模板中的example是占位符，实际生成页面时会被替换为：别名命令名（如npm list）、原命令名（如npm ls）以及tldr后的跳转命令。阿拉伯语翻译模板与英语模板在语义上一一对应：

从仓库现状看，npm-list.md的别名页几乎在所有语言目录下都有对应的翻译副本（如 pages.zh/common/npm-list.md、pages.ja/common/npm-list.md 等 39 个文件），这正是模板机制驱动多语言"一页多译"的直接体现。

四、底层实现：set-alias-page.py如何生成与同步别名页

模板的落地由脚本 scripts/set-alias-page.py 负责。它从 scripts/_common.py 导入通用工具，整体工作流可以概括为三步。

4.1 读取模板：get_templates()

_common.py 中的get_templates(root, "alias-pages.md")会解析模板文件：扫描以###开头的行作为语言标签，提取其下markdown代码块内的文本，最终产出一个{语言: 模板字符串}字典。脚本主入口处即通过这行代码加载全部语言模板：

templates = get_templates(root, "alias-pages.md")

4.2 填充占位符：generate_alias_page_content()

核心替换逻辑（scripts/set-alias-page.py）把模板中的example依次替换为三个真实值：

template_command = "example" result = template_content.replace(template_command, page_content.title, 1) # 第一个 example -> 标题（如 npm list） result = result.replace(template_command, page_content.original_command, 1) # 第二个 example -> 原命令（如 npm ls） result = result.replace(template_command, page_content.documentation_command) # 其余 example -> tldr 后的命令

三个字段的含义通过prompt_alias_page_info()（scripts/set-alias-page.py）的交互式向导收集：标题默认取文件名；原命令（original command）将出现在"此命令是某命令的别名"描述中；文档命令（documentation command）将出现在tldr ...跳转行，默认与原命令相同。以npm list为例，即：标题npm list、原命令npm ls、文档命令npm ls。

4.3 同步与校验：--sync与get_alias_command_in_page()

脚本支持两种运行方式：

• 单页创建/更新：python3 scripts/set-alias-page.py -p common/npm-list.md -l ar，通过交互向导写入指定语言页面；
• 批量同步：python3 scripts/set-alias-page.py -S，读取英文pages/下全部别名页，再同步到各语言目录；-S -l ar则只同步阿拉伯语；加-n为 dry-run 预览改动，加-s可自动git add暂存。

同步时get_alias_command_in_page()（scripts/set-alias-page.py）会反向解析已有页面：提取标题、别名描述行中的原命令（反引号内容）和tldr行中的文档命令，并比对去占位后的模板与现有页面的"骨架"是否一致（stripped_translation_template == stripped_translation），只有不一致时才重写页面。这套机制保证了"模板一旦更新，各语言别名页可以被批量对齐"，这也是阿拉伯语npm list页面能长期保持与模板逐字一致的根本原因。

五、规范守护：命名校验、样式指南与 lint

5.1 文件命名与标题一致性

scripts/wrong-filename.py 会扫描所有pages*目录下的.md文件，校验"文件名"与"标题"是否一致：它把文件名去掉.md、把标题去掉#，分别做归一化（-转空格、小写、折叠空白）后比较。npm-list.md的标题恰好是npm list，归一化后两者完全一致，因此能通过校验。同时该脚本支持"消歧后缀"例外（如just.js对just），确保特殊命名不误报。

5.2 阿拉伯语样式指南中的别名规范

contributing-guides/style-guide.ar.md 的"الألقاب"（别名）章节对阿拉伯语别名页给出了明确指导：当命令可用别名调用（如vim可通过vi调用）时，应创建别名页指回原命令，结构同样为"标题 + 别名说明 +tldr跳转"。该指南还特别覆盖了 PowerShell 别名的三类情况（替代 cmd 命令、仅限 PowerShell 的新别名、与外部程序冲突的别名），说明别名页的规则是成体系的，而非仅限 npm 一例。

5.3 lint 检查

scripts/test-tldr-lint.sh 说明了对阿拉伯语目录执行npx tldr-lint --ignore "TLDR104,TLDR003,TLDR004,TLDR015" pages.ar：其中 TLDR104 与占位符括号规范相关，阿拉伯语目录会忽略这些规则以适配其翻译语法。此外 scripts/check-errors.sh 还会全局检查反引号配对、感叹号句式、……/—等字符混用等常见错误——别名页中用于标记命令名的反引号数量必须成对，这是每个页面（含别名页）都必须满足的硬性要求。

六、实战使用：如何消费这张别名页

6.1 通过 tldr 客户端查看

在任何支持 tldr 协议的客户端（CLI、Web 端、编辑器插件等）中，输入：

tldr npm list

客户端会命中别名页，渲染出阿拉伯语说明并提示原命令为npm ls；继续执行：

tldr npm ls

即可看到 pages.en/common/npm-ls.md（或按语言优先命中对应翻译）展示的完整用法。语言选择通常由客户端的--language/-L参数或系统区域设置决定，例如tldr -L ar npm ls可强制查看阿拉伯语版本。

6.2 结合原命令页掌握npm list的完整能力

尽管别名页本身不列参数，但通过跳转到的npm ls页面可以完整掌握npm list的等效用法：

这正是别名页设计哲学的落点：文档只维护一份，别名页负责指路，原命令页负责讲透，从而保证npm list与npm ls永远共享同一套最新文档，不会出现两份内容漂移。

七、总结

以 pages.ar/common/npm-list.md 为代表的别名页，是 tldr 项目"一命令一页、一页一主题"原则下的一种精简化特殊页面。它的完整生命周期由仓库内的四类资产共同支撑：

• 模板：contributing-guides/translation-templates/alias-pages.md 定义各语言骨架；
• 生成/同步：scripts/set-alias-page.py 负责填充占位符与批量同步；
• 规范约束：contributing-guides/style-guide.ar.md 与 scripts/wrong-filename.py 约束措辞与命名；
• 质量门禁：scripts/test-tldr-lint.sh 与 scripts/check-errors.sh 在 CI 与本地双通道把关。

读懂这张六行页面，你就同时理解了 tldr 的多语言文档体系、占位符模板机制、自动化脚本工作流和质量保障链条——这也是向 tldr 贡献新别名页或翻译时最值得复用的方法论。

• 文档
• 教程
• 知识库