# Understanding the tldr-pages Repository Directory Structure and Organization

> Explore the tldr-pages repository directory structure. Understand how pages, translations, and scripts are organized by language and OS for efficient access and contributions.

- Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr)
- Tags: internals
- Published: 2026-03-05

---

**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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/set-alias-page.py)** – Creates or updates alias pages (e.g., linking `ll` to `ls -l`).
- **[`set-more-info-link.py`](https://github.com/tldr-pages/tldr/blob/main/set-more-info-link.py)** – Inserts or replaces the "More information" URL in existing pages.
- **[`set-page-title.py`](https://github.com/tldr-pages/tldr/blob/main/set-page-title.py)** – Ensures the markdown title matches the filename.
- **[`wrong-filename.py`](https://github.com/tldr-pages/tldr/blob/main/wrong-filename.py)** – Detects pages stored under an incorrect platform folder.
- **[`update-command.py`](https://github.com/tldr-pages/tldr/blob/main/update-command.py)** – Batch-updates command examples after flag changes.
- **[`send-to-bot.py`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/.github/workflows/ci.yml).

### Documentation and Assets

- **`contributing-guides/`** – Contains [`style-guide.md`](https://github.com/tldr-pages/tldr/blob/main/style-guide.md) and maintainer instructions.
- **`images/`** – Stores logos and screenshots referenced by [`README.md`](https://github.com/tldr-pages/tldr/blob/main/README.md).
- **`.github/`** – Issue templates, pull request templates, and CI configuration.
- **[`package.json`](https://github.com/tldr-pages/tldr/blob/main/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:

```bash
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:

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

```

This writes [`pages/common/ll.md`](https://github.com/tldr-pages/tldr/blob/main/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:

```bash
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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/pages/linux/yourcmd.md) for Linux-only tools or [`pages/common/yourcmd.md`](https://github.com/tldr-pages/tldr/blob/main/pages/common/yourcmd.md) for cross-platform utilities). The file must follow the format defined in [`contributing-guides/style-guide.md`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/set-alias-page.py)** creates alias redirects; **[`set-more-info-link.py`](https://github.com/tldr-pages/tldr/blob/main/set-more-info-link.py)** manages documentation URLs; **[`set-page-title.py`](https://github.com/tldr-pages/tldr/blob/main/set-page-title.py)** syncs titles with filenames; **[`wrong-filename.py`](https://github.com/tldr-pages/tldr/blob/main/wrong-filename.py)** detects misplaced pages; **[`update-command.py`](https://github.com/tldr-pages/tldr/blob/main/update-command.py)** performs bulk edits across multiple files; and **[`send-to-bot.py`](https://github.com/tldr-pages/tldr/blob/main/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.