在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

tldr-pages/tldr

菜单

内容结构和组织

相关源文件

本文档解释了 tldr-pages 项目中内容的组织方式，包括目录结构、页面格式、平台差异和国际化（i18n）机制。理解这些内容架构对于参与 tldr-pages 生态系统的贡献者和开发者至关重要。

有关构建和部署此内容的技​​术基础结构的信息，请参阅 技术基础架构。

目录结构

在最高层面上，tldr-pages 按语言和平台组织内容。

来源： CLIENT-SPECIFICATION.md80-95 CONTRIBUTING.md55-81

主要内容目录

  • pages/：包含所有英文页面。
    • 特定平台的目录，例如 common/、linux/、windows/ 等。
    • 每个命令都有一个 markdown 文件（例如 ls.md、git-commit.md）。

翻译目录

  • pages.<locale>/：包含特定语言的翻译页面。
    • 例如：pages.fr/ (法语)，pages.zh_TW/ (繁体中文)。
    • 结构与主 pages/ 目录相似。
    • 仅包含已完成的翻译。

翻译目录遵循 POSIX Locale Name 模式：<language>[_<country>]，其中：

  • <language> 是 ISO 639 语言代码（例如 fr、zh、es）。
  • <country> 是可选的 ISO 3166-1 国家/地区代码，用于区域变体（例如 pt_BR、zh_TW）。

来源： CONTRIBUTING.md156-193 .github/CODEOWNERS1-45

页面格式与结构

每个 tldr 页面都遵循标准化的 markdown 格式。

来源： contributing-guides/style-guide.md15-65 CONTRIBUTING.md82-100

标准页面模板

关键组件

  • 标题：命令名称作为一级标题，精确匹配文件名。
  • 描述：简要说明（1-2行）命令的作用。
  • 更多信息：用尖括号括起来的官方文档链接。
  • 示例：最多 8 个示例，展示命令的常见用法。

每个示例包括：

  1. 对命令作用的描述（使用祈使句动词）。
  2. 实际的命令及选项和参数。

来源： contributing-guides/style-guide.md15-75 CONTRIBUTING.md82-100

占位符语法

tldr-pages 使用特定的占位符语法来指示用户提供的值。

占位符类型示例描述
简单{{filename}}用户输入的基本占位符。
路径{{path/to/file}}路径占位符（Windows 系统请使用反斜杠）。
多个选项{{arg1|arg2}}多个选项之间的选择。
多个参数{{arg1 arg2 ...}}可变数量的参数。
选项变体{{[-o|--output]}}选项的短形式和长形式。

来源： contributing-guides/style-guide.md422-449 CLIENT-SPECIFICATION.md120-140

平台组织

页面按平台分类，以处理在不同操作系统上行为不同的命令。

来源： CONTRIBUTING.md63-81 CLIENT-SPECIFICATION.md19-27

平台目录

  • common/：在多个平台表现相同的命令。
  • 特定平台目录：:
    • linux/：Linux 发行版。
    • windows/：Microsoft Windows。
    • osx/：macOS (别名：macos)。
    • android/：Android。
    • sunos/：SunOS。
    • freebsd/、openbsd/、netbsd/：BSD 变体。

平台解析规则

当客户端查找页面时，它遵循此解析顺序：

  1. 检查宿主平台目录（例如，在 Linux 系统上检查 linux/）。
  2. 如果未找到，则检查 common/ 平台。
  3. 如果仍然未找到，则检查其他平台并发出警告。

来源： CLIENT-SPECIFICATION.md152-173

本地化系统

tldr-pages 项目支持翻译成多种语言。

来源： CONTRIBUTING.md172-198 CLIENT-SPECIFICATION.md105-119

翻译流程

  1. 页面始终从英文原版翻译。
  2. 翻译保持与原版相同的结构和格式。
  3. 特定语言的格式规则可能适用（请参阅风格指南）。

语言解析

客户端根据以下内容确定要显示的语言：

  1. 环境变量：LANG、LANGUAGE 和 LC_MESSAGES。
  2. 用户配置设置。
  3. 如果翻译不可用，则回退到英文。

来源： CLIENT-SPECIFICATION.md190-232

特殊页面类型

该项目支持几种特殊页面类型以应对特定场景。

别名页面

对于具有别名的命令（例如，vi 是 vim 的别名）。

来源： contributing-guides/style-guide.md120-146

歧义页面

用于多个命令共享同一名称的情况。

来源： contributing-guides/style-guide.md209-226 CONTRIBUTING.md279-287

子命令组织

带子命令的命令遵循特定结构。

  1. 主命令：command.md（例如 git.md）。
  2. 子命令：command-subcommand.md（例如 git-commit.md）。
  3. 主页面引用子命令。

来源： CONTRIBUTING.md130-164

内容验证和质量控制

为保持一致性和质量，该项目使用了多种验证机制

来源： contributing-guides/style-guide.md71-78 CONTRIBUTING.md205-227

验证工具

  • tldr-lint：检查页面格式合规性的命令行工具
  • GitHub Actions：对拉取请求进行自动验证
  • 人工审核：维护者审核内容的准确性和风格

风格指南

详细的 style guide 定义了相关规则

  • 页面布局和结构
  • 编写祈使句描述
  • 格式化示例和占位符
  • 特定语言的格式规则

来源： contributing-guides/style-guide.md CONTRIBUTING.md34-49

内容与 tldr 客户端的关系

内容结构旨在与各种向用户展示页面的客户端应用程序配合使用

来源： CLIENT-SPECIFICATION.md README.md59-96

客户端规范

Client Specification 定义了客户端应如何

  1. 根据平台和语言解析页面
  2. 解析和渲染页面内容
  3. 处理占位符和特殊语法
  4. 缓存内容以便离线使用

来源： CLIENT-SPECIFICATION.md

总结

tldr-pages 项目使用一种定义明确的内容结构，该结构

  • 按语言和平台组织页面
  • 遵循一致的页面格式
  • 支持翻译成多种语言
  • 适应特定平台的命令变体
  • 通过验证工具和流程维护质量

这种组织方式使贡献者能够添加和维护清晰、简洁的命令文档，用户可以跨不同平台和语言访问这些文档。

来源： README.md CONTRIBUTING.md CLIENT-SPECIFICATION.md