Understanding the tldr-pages Repository Directory Structure and Organization

The tldr-pages repository is a self-contained monorepo organized by language and operating system, with English pages stored in pages/ (subdivided by platform), translations in pages.<locale>/, automation utilities in scripts/, and contribution guidelines in contributing-guides/.

The tldr-pages repository serves as a centralized monorepo housing thousands of TL;DR manual pages, maintenance tooling, and contributor documentation. Its flat, predictable layout enables contributors to locate specific command examples quickly and allows automated tools to validate formatting against the style guide defined in contributing-guides/style-guide.md.

Core Directory Layout

At the repository root, content is organized into distinct functional zones without hidden sub-modules or external data sources. This self-contained design makes the project trivial to clone, edit, and lint locally.

English Pages (pages/)

The pages/ directory contains the primary English-language command references. Inside this folder, pages are grouped by target operating system:

• common/ – Commands that work identically on two or more platforms (e.g., tar, grep). According to the source, this directory holds commands with identical syntax across OS boundaries.
• linux/ – Linux-exclusive commands or syntax variants.
• osx/ – macOS-specific commands.
• windows/ – Windows-only commands using PowerShell or cmd syntax.
• android/, freebsd/, etc. – Additional platform-specific subdirectories.

Each page follows a strict markdown format: a title, description, "More information" link, and example commands. The folder name matches the command’s platform, enabling tools like tldr-lint to locate pages quickly.

Translations (pages.<locale>/)

Localized versions mirror the English hierarchy exactly. For example, French translations live under pages.fr/, German under pages.de/, and each contains the same platform subdirectories (common/, linux/, windows/, etc.).

This one-to-one mapping guarantees that a French page for tar lives at pages.fr/common/tar.md, making it trivial to locate the source of any translation and ensuring consistency across languages.

Automation (scripts/)

The scripts/ directory houses pure Python utilities that require no external dependencies beyond the standard library. These tools manage page creation, validation, and bulk updates:

• set-alias-page.py – Creates or updates alias pages (e.g., linking ll to ls -l).
• set-more-info-link.py – Inserts or replaces the "More information" URL in existing pages.
• set-page-title.py – Ensures the markdown title matches the filename.
• wrong-filename.py – Detects pages stored under an incorrect platform folder.
• update-command.py – Batch-updates command examples after flag changes.
• send-to-bot.py – Dispatches pull requests to the automation bot.

These scripts are referenced directly from the CI workflow defined in .github/workflows/ci.yml.

Documentation and Assets

• contributing-guides/ – Contains style-guide.md and maintainer instructions.
• images/ – Stores logos and screenshots referenced by README.md.
• .github/ – Issue templates, pull request templates, and CI configuration.
• package.json – Declares metadata for the Node.js client and lists dev-dependencies used by CI tooling.

Platform-Specific Organization

The distinction between common/ and platform-specific folders is strict:

• Common (pages/common/) – Reserved for commands that behave identically across multiple operating systems. If a command works on both Linux and macOS with the same syntax and options, it belongs here.
• Platform-specific (pages/linux/, pages/osx/, etc.) – Reserved for commands unique to a single platform, or when syntax differs significantly between OSes (e.g., Windows PowerShell vs. Bash).

This separation allows client applications to fetch the correct page for the user’s operating system while avoiding duplication of truly cross-platform utilities.

Practical Workflow Examples

Adding a New Linux Command

To add a page for a Linux-specific command, create the file under pages/linux/ and validate it with the linter:

git clone https://github.com/tldr-pages/tldr.git
cd tldr

cat > pages/linux/mycmd.md <<'EOF'

# mycmd

> Short description of mycmd.
> More information: <https://example.com/mycmd>.

- Example 1:
  `mycmd -a {{path/to/file}}`

- Display help:
  `mycmd {{[-h|--help]}}`
EOF

npx tldr-lint pages/linux/mycmd.md
git add pages/linux/mycmd.md
git commit -m "mycmd: add page"

Creating an Alias Page

Use the provided script to generate an alias that points to an existing command:

python scripts/set-alias-page.py -p common/ll -l en

This writes pages/common/ll.md and automatically adds the appropriate "More information" link pointing to the target command.

Running Local Validation

Install dependencies and run the full linting suite to verify all pages against the style guide:

npm install
npm run lint-tldr-pages

This executes tldr-lint against the ./pages directory and all translation folders, ensuring every file conforms to the formatting rules specified in contributing-guides/style-guide.md.

Summary

• The tldr-pages repository uses a flat monorepo structure with no external sub-modules.
• English content resides in pages/, split by platform (common/, linux/, osx/, windows/, etc.).
• Translations follow an identical hierarchy under pages.<locale>/ (e.g., pages.fr/common/).
• Python automation scripts in scripts/ handle aliases, link insertion, and filename validation without external dependencies.
• The style guide at contributing-guides/style-guide.md defines the exact markup format enforced by CI.

Frequently Asked Questions

Where are translated pages stored in the tldr-pages repository?

Translated pages live in top-level directories named pages.<locale>/, such as pages.fr/ for French or pages.de/ for German. Each translation folder mirrors the English pages/ structure exactly, containing subdirectories like common/ and linux/. This parallel organization allows tools and contributors to locate translated versions of commands by simply swapping the language prefix in the path.

What is the difference between the common/ and platform-specific directories?

The common/ directory stores commands that function identically across two or more platforms (e.g., tar or git). Platform-specific directories (linux/, osx/, windows/, android/, freebsd/, etc.) contain commands that are exclusive to a single operating system or use syntax that differs significantly between platforms. If a command works on both Linux and macOS with identical flags, it belongs in common/; if it uses GNU-specific options only available on Linux, it belongs in linux/.

How do I add a new command page to the tldr-pages repository?

Create a new markdown file under the appropriate platform subdirectory (e.g., pages/linux/yourcmd.md for Linux-only tools or pages/common/yourcmd.md for cross-platform utilities). The file must follow the format defined in contributing-guides/style-guide.md: an H1 title matching the command name, a description, a "More information" URL, and example code blocks. Before submitting, run npx tldr-lint <filepath> locally to catch formatting errors.

Which Python scripts are available for maintaining pages?

The scripts/ directory contains several maintenance utilities: set-alias-page.py creates alias redirects; set-more-info-link.py manages documentation URLs; set-page-title.py syncs titles with filenames; wrong-filename.py detects misplaced pages; update-command.py performs bulk edits across multiple files; and send-to-bot.py interfaces with the repository’s automation bot. All scripts use only the Python standard library and can be executed directly without virtual environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}