# How to Start Contributing to the tldr-pages Project: A Complete Workflow Guide > Learn how to contribute to the tldr-pages project. Follow our guide to sign the CLA, create pages, validate, and submit your pull request for the tldr-pages repo. - Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr) - Tags: how-to-guide - Published: 2026-03-05 --- **TLDR:** Contributing to the tldr-pages project requires signing the Contributor License Agreement via cla-assistant.io, creating Markdown pages following the template in CONTRIBUTING.md, validating with the tldr-lint npm package, and submitting a pull request with a conventional commit message against the main branch. Contributing to the tldr-pages project is the primary way to expand this community-driven collection of simplified command-line help pages. The repository at tldr-pages/tldr uses a structured workflow to ensure every new command page, translation, or script modification meets quality standards and legal requirements. This guide walks through the exact steps derived from the source code, from initial setup to final merge. ## Prerequisites: Legal and Setup Requirements Before writing any code, you must complete two mandatory steps. First, read the [CONTRIBUTING.md](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md) file in the repository root, which defines the project philosophy, style rules, and submission workflow. Second, sign the **Contributor License Agreement (CLA)** at ; the pull request cannot merge until this check passes. ## Selecting Your Contribution Type The tldr-pages repository accepts three primary contribution categories. **New command pages** add documentation for tools missing from the `pages/` directory tree. **Translations** localize existing English pages into other languages under `pages./` directories. **Tooling changes** modify helper scripts located in the `scripts/` directory, such as [`scripts/set-page-title.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-page-title.py) for programmatic title updates. ## Crafting the Markdown Page Every tldr page follows a strict template defined in [`contributing-guides/style-guide.md`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md). The file must use **token syntax** like `{{path/to/file}}` for user-provided values and `{{[-v|--verbose]}}` for optional arguments. Maintain an example count between **5 and 8** entries; fewer lacks utility, while more becomes overwhelming. The description line should start with `> Short, snappy description` followed by a `More information` link. ### Page Template Skeleton ```markdown # command-name > Short, snappy description. > More information: . - Simple usage example: `command --option {{path/to/file}}` - Display help: `command {{[-h|--help]}}` ``` For a fully rendered reference, examine [`pages/common/pwd.md`](https://github.com/tldr-pages/tldr/blob/main/pages/common/pwd.md). ## Directory Placement Rules File location determines platform visibility. If a command works on **two or more platforms**, place it in `pages/common/`. For **platform-specific** tools, use the corresponding subdirectory: `pages/linux/`, `pages/windows/`, `pages/macos/`, or `pages/android/`. Translations follow the pattern `pages.//`, such as `pages.fr/common/` for French versions of cross-platform commands. ## Local Validation with tldr-lint Before committing, validate your Markdown against the project's linter. Install the tool globally via npm, then execute it against your new file path. ```bash # Install the linter (one-time setup) npm install --global tldr-lint # Validate your contribution tldr-lint pages/common/your-command.md ``` Fix any reported formatting errors to prevent automated check failures. ## Commit Standards and Pull Request Workflow The repository enforces **conventional commit messages** using the format `command: type of change`. For example, use `ls: add page` when introducing a new command or `git: update Spanish translation` for localization work. ```bash git add pages/common/your-command.md git commit -m "your-command: add page" git push origin your-branch ``` After pushing, open a pull request against the `main` branch. Enable **"Allow edits by maintainers"** in the GitHub UI so reviewers can apply direct fixes. The repository's `.husky/pre-commit` hook automatically runs `tldr-lint` and the test suite on every commit, providing immediate quality feedback. ## Summary - Sign the CLA at cla-assistant.io/tldr-pages/tldr before submitting any pull request. - Place cross-platform commands in `pages/common/` and platform-specific tools in their respective `pages//` directories. - Follow the Markdown template from CONTRIBUTING.md, using `{{placeholder}}` syntax and limiting examples to 5-8 entries. - Validate locally using `tldr-lint` to catch formatting errors before review. - Use conventional commit messages like `command: add page` and target the `main` branch for all pull requests. ## Frequently Asked Questions ### Do I need to sign a legal agreement before contributing to the tldr-pages project? Yes. All contributors must sign the Contributor License Agreement (CLA) via . The pull request status check will block merging until this step is completed, ensuring the project maintains proper licensing for all distributed content. ### How many examples should a tldr page contain? A tldr page must contain between **5 and 8 examples**. This range balances comprehensiveness with brevity, keeping the command reference concise yet useful. The style guide in [`contributing-guides/style-guide.md`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md) explicitly defines this constraint to maintain consistency across the entire documentation set. ### Where do I place a command that works on multiple operating systems? Place cross-platform commands in `pages/common/`. If the tool is specific to a single platform, such as a Linux-only utility, store it in the appropriate platform directory like `pages/linux/`. For translations, mirror the English structure under `pages./`, such as `pages.fr/common/` for French versions of cross-platform commands. ### What automated checks run when I submit a pull request? The repository runs the `tldr-lint` validator and test suite automatically via the `.husky/pre-commit` hook on every commit. Additionally, the CLA assistant verifies your legal signature. If these checks fail, review the error logs, fix the issues locally, and push the corrections to your branch.