How to Start Contributing to the tldr-pages Project: A Complete Workflow Guide

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 file in the repository root, which defines the project philosophy, style rules, and submission workflow. Second, sign the Contributor License Agreement (CLA) at https://cla-assistant.io/tldr-pages/tldr; 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.<locale>/ directories. Tooling changes modify helper scripts located in the scripts/ directory, such as 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. 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

# command-name

> Short, snappy description.
> More information: <https://example.com>.

- Simple usage example:

`command --option {{path/to/file}}`

- Display help:

`command {{[-h|--help]}}`

For a fully rendered reference, examine 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.<locale>/<platform>/, 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.

# 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.

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/<platform>/ 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 https://cla-assistant.io/tldr-pages/tldr. 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 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.<locale>/, 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.

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