文档教程知识库【免费下载链接】tldrCollaborative cheatsheets for console commands .项目地址https://gitcode.com/GitHub_Trending/tl/tldr点击查看免费下载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,...}}将页面格式化输出到stdouttldr-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 给出了德语侧的标准占位符英文占位符德语占位符path/to/filepfad/zu/dateipath/to/directorypfad/zu/verzeichnispath/to/file_or_directorypfad/zu/datei_oder_verzeichnispackagepaketusernamebenutzernamepasswordpasswortcommandbefehlportportvaluewert规则 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 的最终目标是让用户尽可能直观地判断命令如何工作、该填入什么值。客户端能够对{{...}}高亮因此占位符本身就承担了教学职责。技术术语的反引号语法描述行中的技术术语应使用反引号语法。需要加反引号的三类内容路径如package.json、/etc/package.json文件扩展名如.dll命令如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.jsonnpm 脚本入口仓库根目录 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检查随后依次执行 BlackPython 代码风格、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的语言适配层它根据目录名决定要忽略的规则checksTLDR104 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从三个层面保证了速查页面的质量布局层面要求标准模板与自动 LinterToken 层面用八条细则规范占位符的命名、路径写法与安全底线并配合反引号统一技术术语表达层面用串行逗号消除列举歧义。仓库中的 scripts/test.sh、scripts/test-tldr-lint.sh 与 scripts/wrong-filename.py 则将上述规范固化为可持续运行的自动检查任何语言的新页面都必须通过它们才能合入。对希望为pages.de/贡献德语页面的开发者而言遵循本指南即可写出规范、易读且能被客户端正确高亮渲染的内容。赞分享文档教程知识库【免费下载链接】tldrCollaborative cheatsheets for console commands .项目地址https://gitcode.com/GitHub_Trending/tl/tldr点击查看免费下载相关推荐Mastra 文档页面风格指南从页面类型到 MDX 结构的完整写作规范Mastra 文档页面风格指南从页面类型到 MDX 结构的完整写作规范 导读 本文基于 Mastra 仓库的 docs/styleguides/DOC.md人工智能Agent 框架AI AgentRAG后端20分钟上手Notepad--目录查找替换与文件对比20分钟上手Notepad 目录查找替换与文件对比 Notepad 是一款免费的跨平台文本编辑器Windows、Linux、macOS 都能跑。多标签编辑、桌面应用Mastra 文档编写指南Reference 页面风格规范API / 配置 / CLI 查用文档写法Mastra 文档编写指南Reference 页面风格规范API / 配置 / CLI 查用文档写法 本文面向为 Mastra 开源项目TypeScri人工智能Agent 框架AI AgentRAG后端上一篇本地以图搜图实战部署 ImageSearch把千万级图库变成可检索的私人图片引擎下一篇WPS-Zotero插件Linux学术写作的文献管理难题一条命令就解决创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考