企业官网建设流程全解析

• 文档
• 教程
• 知识库

tldr 是一个协作式的命令速查手册（cheatsheet）仓库，pages.de/目录承载着德语页面的维护工作。本文以仓库内 contributing-guides/style-guide.de.md 为主线，系统讲解德语tldr页面的标准布局、{{Token}}占位符语法、反引号规范与串行逗号（Serial Comma）规则，并结合仓库中的 Linter 与 CI 脚本，说明这些规范如何被自动化校验。读完本文，你将能够编写并自检一份符合社区标准的德语tldr页面。

标准页面布局：一份 tldr 页面的"最小骨架"

德语风格指南规定，一份标准的tldr页面应当严格遵循以下格式：

# befehl > Kurze Beschreibung. > Möglichst nur eine Zeile; wenn nötig, sind zwei akzeptabel. > Weitere Informationen: <https://example.com>. - Beispielbeschreibung: `befehl -opt1 -opt2 -arg1 {{arg_wert}}` - Beispielbeschreibung: `befehl -opt1 -opt2`

这个模板的每个部分都有明确职责：

• 标题（# befehl）：与命令名严格一致，文件名必须全小写（见下文"文件名与标题一致性"）；
• 描述行（>开头）：以"尽可能一行、必要时两行"为原则，凝练说明命令功能；Weitere Informationen行提供官方文档链接，链接必须用尖括号< >包裹以保证客户端正确渲染；
• 示例：每条示例由"示例描述 + 反引号包裹的命令行"组成，命令中的用户输入用{{Token}}占位。

仓库中的真实德语页面都遵循这一骨架。例如 pages.de/common/cd.md 的标题为# cd，描述为> Ändere das aktuelle Arbeitsverzeichnis.（更改当前工作目录），示例行则写成cd {{pfad/zu/verzeichnis}}。再如 pages.de/common/7z.md，每条示例的描述（如[a]rchiviere eine Datei oder ein Verzeichnis）都使用动词开头的命令式短语，命令行中的占位符统一使用德语命名。

Linter：让格式校验自动化

社区提供了tldr-lintLinter 来强制上述格式。它会在每次 Pull Request 时被自动执行，但也可以手动安装，以便在提交新页面之前先进行本地校验：

npm install --global tldr-lint tldr-lint {{seite.md}}

tldr-lint还有其他用法，例如对整个目录进行 lint。仓库内 pages/common/tldr-lint.md 记录了其常用能力：

• 检查单个页面或整个目录：tldr-lint {{path/to/page_or_directory}}；
• 忽略特定错误码（如TLDR001,TLDR002,...）：tldr-lint {{[-I|--ignore]}} {{TLDR001,TLDR002,...}}；
• 将页面格式化输出到stdout：tldr-lint {{[-f|--format]}} {{path/to/page.md}}；
• 就地格式化页面：tldr-lint {{[-f|--format]}} {{[-i|--in-place]}} {{path/to/page.md}}。

tldr-lint还提供别名tldrl，两种写法等价，可任选其一。

本地预览页面

许多tldr客户端支持--render标志来直接渲染显示一个本地页面文件，方便在提交前检查视觉效果：

tldr --render {{seite.md}}

Token 语法：让占位符可高亮、可填充

用户输入的值应使用{{Token}}语法，这样tldr客户端就能对它们进行高亮显示。德语风格指南为 Token 定义了八条规则，逐条说明如下。

规则 1：简短且具有描述性

Token 应当简短、描述性强，例如{{source_file}}或{{wallet.txt}}。目标是让读者一眼就能明白该填什么值。

规则 2：多词 Token 使用 snake_case

由多个单词组成的 Token 应使用snake_case连接，例如{{source_file}}。这一点在德语页面中同样适用，仓库维护的常用参数翻译表 contributing-guides/translation-templates/common-arguments.md 给出了德语侧的标准占位符：

规则 3：使用{{filename}}而非{{file_name}}

当只需要文件名时，用{{filename}}这种单字占位符，不要拆成file_name。

规则 4：路径使用{{path/to/<Platzhalter>}}格式

文件或目录路径应写成{{path/to/<占位符>}}的形式。例如ln -s {{path/to/file}} {{path/to/symlink}}。当占位符既可能是文件也可能是目录时，使用{{path/to/file_or_directory}}。德语页面中的对应写法就是{{pfad/zu/datei}}、{{pfad/zu/verzeichnis}}。

规则 5：除非位置隐含，路径类命令一律遵循 path/to 约定

所有涉及路径的命令都应遵循{{path/to/<占位符>}}约定，除非文件位置本身是隐含的（例如某些命令默认操作当前目录）。

规则 6：期望特定扩展名时使用它

• 如果命令期望特定文件扩展名，就把它写进占位符，例如unrar x {{compressed.rar}}；
• 需要表示"通用的扩展名"时使用{{.ext}}，但仅当扩展名确实必要时才用；
• pages.de/common/find.md 的 "Dateien nach Erweiterung suchen"（按扩展名查找文件）示例中，find {{root_path}} -name '{{*.ext}}'用{{*.ext}}既说明了命令又不至于过度具体；
• 而像wc -l {{file}}这种场景，{{file}}（不带扩展名）就足够了。

规则 7：具体数值优于抽象变量

当示例用具体值更清晰时，应使用示例值。例如写iostat {{2}}而不是iostat {{interval_in_secs}}，这样读者可以直接理解参数的含义。

规则 8：不可逆操作必须防止盲目复制粘贴

如果命令会对文件系统或设备执行不可逆的修改，示例必须写成无法被"无脑复制粘贴"的形式。例如，应写ddrescue --force --no-scrape {{/dev/sdX}} {{/dev/sdY}}而非ddrescue --force --no-scrape /dev/sda /dev/sdb；对于块设备应使用{{/dev/sdXY}}占位符而非/dev/sda1。

总体原则

Token 的最终目标是：让用户尽可能直观地判断命令如何工作、该填入什么值。客户端能够对{{...}}高亮，因此占位符本身就承担了"教学"职责。

技术术语的反引号语法

描述行中的技术术语应使用反引号（`）语法。需要加反引号的三类内容：

1. 路径，如package.json、/etc/package.json；
2. 文件扩展名，如.dll；
3. 命令，如ls。

这与仓库内的英文主指南 contributing-guides/style-guide.md 中关于标准流（stdout/stdin/stderr）、压缩算法（zip、7z、xz）等术语的反引号要求一脉相承，德语页面同样适用。

Serial Comma：消除列表歧义

当列表包含 3 个或更多元素时，应使用串行逗号（Serial Comma，又称 Oxford Comma）来避免歧义。

看下面这个例子：

Delete the Git branches, tags and remotes.

这个句子没有使用串行逗号，因此存在两种解读：

• 删除名为tags和remotes的 Git 分支；
• 删除 Git 分支、Git 标签和 Git remote 这三类对象。

在 "and" 或 "or" 之前插入一个逗号即可解决歧义：

Delete the Git branches, tags, and remotes.

这一规则对德语页面同样有效，因为在列举三个及以上元素时，缺少逗号同样会造成语义模糊。英文主指南 contributing-guides/style-guide.md 也强调这是声明 3 个及以上列表项时必须遵守的规则。

仓库中的自动化校验：规范如何被执行

风格指南不只是纸面约定，仓库通过多层脚本把上述规则落到了 CI 流程中。理解这些机制，有助于你在本地提交前自查。

package.json：npm 脚本入口

仓库根目录 package.json 中声明了与页面质量相关的 npm 脚本：

"scripts": { "lint-markdown": "markdownlint pages*/**/*.md", "lint-tldr-pages": "tldr-lint ./pages", "test": "bash scripts/test.sh" }

其中markdownlint负责通用 Markdown 语法检查，tldr-lint负责tldr页面特有的格式约束，二者共同构成页面质量的自动防线。

test.sh：并行执行全套测试

scripts/test.sh 是npm test的执行入口。它的run_tests函数用xargs按 2000 个文件为一组、以 CPU 核数为并行度对pages*下的所有.md文件跑markdownlint，再对每个语言目录调用scripts/test-tldr-lint.sh做tldr-lint检查，随后依次执行 Black（Python 代码风格）、flake8、pytest 和 shellcheck。在 GitHub Actions 的 Pull Request 构建中，错误还会通过scripts/send-to-bot.py上报给 tldr-bot。

test-tldr-lint.sh：按语言动态放宽规则

scripts/test-tldr-lint.sh 是tldr-lint的语言适配层，它根据目录名决定要忽略的规则：

checks="TLDR104" case $1 in *ar*|*bn*|*fa*|*hi*|*ja*|*ko*|*lo*|*ml*|*ne*|*ta*|*th*|*tr*) checks+=",TLDR003,TLDR004,TLDR015" ;; *zh*) checks+=",TLDR003,TLDR004,TLDR005,TLDR015" ;; *en*) checks="" set -- "pages" ;; esac exec npx tldr-lint --ignore "$checks" "$1"

德语（de）目录默认只忽略TLDR104，其余规则全部生效；而阿拉伯语、波斯语等从右向左书写的语言以及中文、日文等 CJK 语言需要额外放宽行宽等规则，这体现了"语言差异由脚本显式管理"的设计。

wrong-filename.py：文件名与标题一致性检查

scripts/wrong-filename.py 专门校验"文件名与页面标题必须一致"这一规则：它读取每个.md文件的首行标题，将文件名与标题分别规范化（转小写、-替换为空格、折叠连续空白）后比对，不一致就写入inconsistent-filenames.txt。它同时支持消歧义页面（如just.js之于just）的特例判断，该逻辑直接引用了英文主指南 contributing-guides/style-guide.md 中的 Disambiguations 一节。因此，德语页面同样要求文件名全小写且与#标题匹配。

实战：编写一页符合规范的德语 tldr 页面

综合以上规则，一份合格的德语tldr页面可以按如下步骤产出。

第一步：确定命令与目录。若命令在common平台通用，放入pages.de/common/；若仅适用于特定平台，放入对应平台目录（如pages.de/linux/）。

第二步：套用标准骨架。标题、一行描述、可选 "Weitere Informationen" 链接、示例块。

第三步：使用德语 Token 与反引号。路径类占位符用pfad/zu/...系列，命令/路径/扩展名用反引号包裹。以 pages.de/common/7z.md 为范本，其示例7z a {{pfad/zu/archiv.7z}} {{pfad/zu/datei_oder_verzeichnis}}完美体现了规则 4、规则 6 与德语占位符的结合。

第四步：命令式描述 + 选项记忆符。示例描述用动词开头的命令式（如Wechsle in das angegebene Verzeichnis，见 pages.de/common/cd.md）；短选项可以用方括号标注其含义记忆符，例如7z页中的[a]rchiviere（-a表示 add/archive）、E[x]trahiere（-x表示 extract）。

第五步：本地校验。依次执行：

npm install --global tldr-lint tldr-lint {{seite.md}} tldr --render {{seite.md}}

若页面是别名页（如vi之于vim），可直接套用仓库维护的德语别名模板 contributing-guides/translation-templates/alias-pages.md：

# example > Dieser Befehl ist ein Alias von `example`. - Zeige die Dokumentation für den originalen Befehl an: `tldr example`

小结

tldr的德语风格指南（contributing-guides/style-guide.de.md）从三个层面保证了速查页面的质量：布局层面要求标准模板与自动 Linter；Token 层面用八条细则规范占位符的命名、路径写法与安全底线，并配合反引号统一技术术语；表达层面用串行逗号消除列举歧义。仓库中的 scripts/test.sh、scripts/test-tldr-lint.sh 与 scripts/wrong-filename.py 则将上述规范固化为可持续运行的自动检查，任何语言的新页面都必须通过它们才能合入。对希望为pages.de/贡献德语页面的开发者而言，遵循本指南即可写出规范、易读且能被客户端正确高亮渲染的内容。

• 文档
• 教程
• 知识库