TLDR 自定义页面创建通用指南报告

1. 概述

TLDR 页面（Too Long; Don't Read）通过简洁的 Markdown 格式，为命令行工具提供常用示例和说明。创建自定义页面可以帮助团队或个人记录私有脚本、内部工具或特定环境下的常用操作。

2. 核心文件格式 (Markdown)

TLDR 页面遵循严格的 Markdown 结构：

• 标题: # 命令名称 (每个文件仅限一个)
• 描述: > 命令的简要说明。
• 链接: > 更多信息：<https://example.com>. (建议提供官方文档或 GitHub 链接)
• 示例描述: - 示例场景的中文描述：
• 代码块: `命令内容 {{参数占位符}}`

示例格式

# mycommand

> 我的自定义工具描述。
> 更多信息：<https://github.com/user/repo>.

- 执行基础操作：

`mycommand run --input {{path/to/file}}`

3. 存储路径规范

TLDR 客户端通常在本地缓存目录中查找页面。通用的目录结构如下：

• 根目录: ~/.tldr/cache/ (或类似路径，视客户端而定)
• 语言子目录:
• 英文: pages/
• 中文: pages.zh/
• 平台子目录:
• common/: 跨平台命令（最常用）
• linux/, osx/, windows/, android/: 平台特定命令

最佳实践: 建议将自定义命令放在 common/ 目录下，除非该命令确实仅限特定系统。

4. 创建步骤

1. 确认路径: 查找当前 tldr 客户端的缓存路径（如 ~/.tldr/cache/）。
2. 选择语言与平台: 进入对应的子目录，例如 pages.zh/common/。
3. 新建文件: 文件名必须是 命令名.md（全小写，且与调用命令一致）。
4. 编写内容: 按照上述核心格式要求填充内容。
5. 验证显示: 运行 tldr 命令名。如果无法直接显示，可能需要检查缓存刷新策略。

6. 注意事项

• 占位符: 使用双大括号 {{ }} 包裹参数，这有助于客户端高亮显示并方便用户快速替换。
• 冒号: 示例描述建议以冒号 ： 结尾，保持风格统一。
• 换行: 每个示例（描述+代码块）之间应保留一个空行，以提高可读性。
• 自动覆盖: 请注意，手动在 cache/ 目录下创建的文件在执行 tldr --update 时可能会被覆盖。部分高级客户端支持自定义路径环境变量（如 TLDR_PAGES_PATH），建议长期保留的自定义页面通过此类配置进行管理。

---

生成的报告日期: 2026年3月9日