tldr-pages/tldr

⭐ 57,667 🍴 4,629 Markdown📄 Creative Commons Attribution 4.0（ページ）/ MIT（スクリプト） GitHubで見る →

主な特徴

簡略化されたフォーマット：各ページは簡潔な説明と実用的な例を含む
マルチプラットフォーム対応：10の異なるプラットフォームに対応
幅広い翻訳：38言語に対応（アラビア語、中国語、日本語、韓国語、フランス語、ドイツ語、スペイン語等）
標準化された構造：すべてのページが一貫したMarkdownフォーマットに準拠
コミュニティ主導：明確なガイドラインとガバナンスを持つオープンな貢献モデル
クライアント仕様：互換性のあるクライアントを構築するための詳細な仕様（v2.3）
プレースホルダー構文：ユーザーが編集すべき値を`{{二重括弧}}`で表示
PDF版も利用可能：オフラインでの閲覧や印刷に対応

リポジトリ解析: tldr-pages/tldr

基本情報

リポジトリ名: tldr-pages/tldr
主要言語: Markdown
スター数: 57,667
フォーク数: 4,629
最終更新: 2025年7月時点でアクティブ
ライセンス: Creative Commons Attribution 4.0（ページ）/ MIT（スクリプト）
トピックス: command-line, help-pages, man-pages, documentation, examples, community-driven, multi-language, cross-platform

概要

一言で言うと

コンソールコマンドの実用的な例を提供するコミュニティ主導のチートシート集で、伝統的なmanページのより親しみやすい代替。

詳細説明

tldr-pagesは、「Too Long; Didn't Read（長すぎて読まなかった）」の略で、コマンドラインツールの簡略化されたヘルプページを提供するプロジェクトです。網羅的なドキュメントよりも実用的な例に焦点を当て、ユーザーが必要な情報を素早く得られるよう設計されています。

現在は22,400以上のドキュメントページが38言語で提供され、common（クロスプラットフォーム）、Linux、macOS、Windows、Androidなど10のプラットフォームをカバーしています。各ページは統一されたフォーマットに従い、簡潔な説明と最大8つの実用例を含んでいます。

主な特徴

簡略化されたフォーマット：各ページは簡潔な説明と実用的な例を含む
マルチプラットフォーム対応：10の異なるプラットフォームに対応
幅広い翻訳：38言語に対応（アラビア語、中国語、日本語、韓国語、フランス語、ドイツ語、スペイン語等）
標準化された構造：すべてのページが一貫したMarkdownフォーマットに準拠
コミュニティ主導：明確なガイドラインとガバナンスを持つオープンな貢献モデル
クライアント仕様：互換性のあるクライアントを構築するための詳細な仕様（v2.3）
プレースホルダー構文：ユーザーが編集すべき値を{{二重括弧}}で表示
PDF版も利用可能：オフラインでの閲覧や印刷に対応

使用方法

インストール

前提条件

各クライアントに依存（Python 3、Node.js、Rustなど）
インターネット接続（初回ダウンロード時）

インストール手順

# 方法1: Pythonクライアント（公式）
pip3 install tldr

# 方法2: Rustクライアント（公式、高速）
# macOSの場合
brew install tlrc
# または
cargo install tlrc

# 方法3: Node.jsクライアント
npm install -g tldr

# 方法4: Webクライアント
# https://tldr.inbrowser.app をブラウザで開く
# PWAとしてオフラインでも使用可能

# 方法5: その他のパッケージマネージャー
# macOS: brew install tldr
# Ubuntu/Debian: sudo apt install tldr
# Arch Linux: yay -S tldr

基本的な使い方

Hello World相当の例

# 基本的な使用法
tldr tar

# 結果例：
tar

Archiving utility.
Often combined with a compression method, such as gzip or bzip2.
More information: https://www.gnu.org/software/tar.

- Create an archive from files:
  tar cf {{path/to/target.tar}} {{path/to/file1 path/to/file2 ...}}

- Extract an archive into the current directory:
  tar xf {{path/to/source.tar}}

実践的な使用例

# サブコマンドのヘルプを表示
tldr git commit

# 特定のプラットフォーム用のコマンドを表示
tldr -p osx brew
tldr -p linux apt

# 日本語でヘルプを表示（クライアントが対応している場合）
tldr -L ja tar

# キャッシュを更新して最新のページを取得
tldr --update

高度な使い方

# ページフォーマットの例（pages/common/ls.md）
# ls

> List directory contents.
> More information: <https://www.gnu.org/software/coreutils/ls>.

- List files one per line:

`ls -1`

- List all files, including hidden files:

`ls -a`

- List all files, with trailing / added to directory names:

`ls -F`

# コントリビューション用のページ作成
# 1. リポジトリをフォーク
# 2. 新しいページを作成
mkdir -p pages/common
echo '# command-name

> Brief description.
> More information: <https://example.com>.

- Example description:

`command {{placeholder}}`' > pages/common/command-name.md

# 3. tldr-lintで検証
npm install -g tldr-lint
tldr-lint pages/common/command-name.md

ドキュメント・リソース

公式ドキュメント

README.md: プロジェクトの概要、インストール方法、使用法
CONTRIBUTING.md: 貢献者向けガイドライン
CLIENT-SPECIFICATION.md: tldrクライアント実装の仕様書（v2.3）
GOVERNANCE.md: コミュニティの統治構造と意思決定プロセス
COMMUNITY-ROLES.md: コミュニティ内の役割と責任
Webサイト: https://tldr.sh - プロジェクトの公式サイト

サンプル・デモ

pages/: 実際のコマンドページの例（全てのページがサンプル）
contributing-guides/style-guide.md: ページ作成のスタイルガイド
オンラインデモ: https://tldr.inbrowser.app

チュートリアル・ガイド

スタイルガイド: contributing-guides/style-guide.md - 英語版
翻訳版スタイルガイド:
- style-guide.zh.md（中国語）
- style-guide.ko.md（韓国語）
- style-guide.ar.md（アラビア語）
- style-guide.de.md（ドイツ語）
Gitの使い方: contributing-guides/git-terminal.md

技術的詳細

アーキテクチャ

全体構造

tldr-pagesはデータ中心のシンプルなアーキテクチャを採用しています。Markdownファイルをプラットフォームと言語別に整理し、クライアントはこれらのファイルを直接またはGitHubリリースからダウンロードして表示します。ビルドプロセスでは、各言語ごとにZIPアーカイブとJSONインデックスが生成されます。

ディレクトリ構成

tldr/
├── pages/                # 英語のページ
│   ├── common/           # クロスプラットフォームコマンド（3,831コマンド）
│   ├── linux/            # Linux専用コマンド
│   ├── osx/              # macOS専用コマンド
│   ├── windows/          # Windows専用コマンド
│   ├── android/          # Android専用コマンド
│   ├── cisco-ios/        # Cisco IOSコマンド
│   ├── freebsd/          # FreeBSDコマンド
│   ├── netbsd/           # NetBSDコマンド
│   ├── openbsd/          # OpenBSDコマンド
│   └── sunos/            # SunOSコマンド
├── pages.<lang>/         # 翻訳ページ（例: pages.ja, pages.fr, pages.zh）
├── scripts/              # ビルドとメンテナンスツール
├── contributing-guides/  # スタイルガイドとテンプレート
└── images/               # ロゴ、バナー等のリソース

主要コンポーネント

ページファイル: 各コマンドのドキュメント
- 場所: pages/[platform]/[command].md
- フォーマット: CommonMark + カスタムプレースホルダー構文
- サブコマンド: ダッシュ区切り（例: git-commit.md）
ビルドスクリプト: アーカイブとインデックスの生成
- 場所: scripts/build.sh
- 機能: ZIPアーカイブ作成、JSONインデックス生成
tldr-lint: ページ検証ツール
- 機能: フォーマットチェック、プレースホルダー検証
- CI/CDで自動実行

技術スタック

コア技術

言語: Markdown（CommonMark準拠）
フォーマット: カスタムプレースホルダー構文 {{二重括弧}}
主要ツール:
- Node.js: ビルドスクリプト、リントツール
- tldr-lint: ページ検証ツール
- markdownlint: Markdownフォーマットチェック
- Pythonスクリプト: ユーティリティツール

開発・運用ツール

ビルドツール: npmスクリプト、bashスクリプト
テスト: tldr-lintによるフォーマット検証、markdownlint
CI/CD: GitHub Actions
- PRごとの自動チェック
- リリースの自動作成
- アーカイブ生成
デプロイ: GitHub Releases経由でのアーカイブ配布

設計パターン・手法

データ中心設計: コードではなくデータ（Markdownファイル）が中心
モジュラー構造: プラットフォームと言語で分離
統一フォーマット: 全ページが同一の構造に従う
サブコマンド命名: ダッシュ区切り（git-commit.md）
プレースホルダーパターン: ユーザー入力部分を明示

データフロー・処理フロー

コントリビューションフロー:
- Fork & Clone
- ページの作成/編集
- tldr-lintでの検証
- Pull Requestの作成
- GitHub Actionsによる自動チェック
- レビューとマージ
ビルドプロセス:
- 各言語ディレクトリのスキャン
- JSONインデックスの生成
- ZIPアーカイブの作成
- GitHub Releasesへのアップロード
クライアントアクセス:
- アーカイブのダウンロード（初回/更新時）
- ローカルキャッシュの保存
- コマンドに基づくページ検索
- Markdownのパースと表示

API・インターフェース

公開API

クライアント仕様 (v2.3)

目的: tldrクライアントの実装ガイドライン
主要機能:
- キャッシュ管理（アーカイブのダウンロードと保存）
- プラットフォーム検出と優先順位
- 言語選択とフォールバック
- サブコマンドの処理

ページフォーマットAPI

# command-name

> 簡潔な説明。
> 詳細情報: <https://example.com>.

- 例の説明:

`command {{placeholder}} {{optional_placeholder}}`

- オプションの例:

`command {{[-o|--option]}} {{value}}`

設定・カスタマイズ

クライアント設定

// 一般的なクライアント設定例
{
  "language": "ja",              // 優先言語
  "platform": "osx",             // 優先プラットフォーム
  "cache_dir": "~/.tldr/cache",  // キャッシュディレクトリ
  "update_auto": true            // 自動更新
}

拡張・プラグイン開発

カスタムクライアント: CLIENT-SPECIFICATION.mdに準拠
テーマサポート: MarkdownのCSSスタイリング
エディタ統合: VSCode、Vim等のプラグインとして
API統合: アーカイブURLからの直接アクセス

パフォーマンス・スケーラビリティ

パフォーマンス特性

ファイルサイズ: 各ページは1-2KB程度
アーカイブサイズ: 各言語ごとに数MB
キャッシュ性能: ローカルキャッシュにより高速アクセス
最適化手法:
- シンプルなファイル構造
- 圧縮アーカイブの配布
- JSONインデックスによる高速検索

スケーラビリティ

ページ数: 22,400+ページが管理可能
言語数: 38言語の同時サポート
コントリビューター: 2,000+人のグローバルコミュニティ
Gitベース: 分散バージョン管理

制限事項

例の数: 各ページ最大8つまで
説明の長さ: 1-2行に制限
フォーマット: 厳格なMarkdownフォーマット準拠
プラットフォーム: 10プラットフォームに限定

評価・所感

技術的評価

強み

圧倒的なシンプルさと使いやすさ
実用例中心のアプローチが非常に効果的
多言語サポートによるグローバルなアクセシビリティ
活発なコミュニティと明確なガバナンス
豊富なクライアント実装の選択肢

改善の余地

より詳細な情報が必要な場合はmanページを参照する必要
一部の複雑なコマンドは8つの例では不十分
プラットフォーム間での翻訳カバレッジのバラつき

向いている用途

コマンドライン初心者の学習
日常的なコマンドのクイックリファレンス
特定のオプションや構文の確認
チーム内での知識共有
多言語環境でのドキュメントアクセス

向いていない用途

完全なコマンドリファレンスが必要な場合
システム管理の詳細な設定情報
APIドキュメントやプログラミングリファレンス
リアルタイム更新が必要な情報

総評

tldr-pagesは、伝統的なmanページの複雑さと実用性のギャップを見事に埋めるプロジェクトです。シンプルなフォーマット、実用例中心のアプローチ、グローバルなコミュニティの組み合わせにより、コマンドラインツールのドキュメントに革命をもたらしました。特に初学者や日常的にコマンドを使う開発者にとって、なくてはならないツールとなっています。GitHubの57,000以上のスターが、その価値を証明しています。