Contributing to tldr-pages: Guidelines and Pull Request Process Explained

TLDR: Fork the repository, create a branch from main, write pages with 5–8 examples using {{placeholder}} syntax, validate with tldr-lint, commit using the <command>: <change> format, and open a GitHub PR targeting tldr-pages/tldr:main with maintainer edits enabled.

The tldr-pages repository hosts a community-driven collection of simplified command-line cheat sheets. Following the official contributing guidelines and pull request process for tldr-pages ensures that new pages, translations, and script changes meet the project's formatting standards and pass automated checks.

Forking and Setting Up Your Local Environment

Start by forking the repository on GitHub and cloning your fork locally. Add the upstream remote to keep your branch synchronized with the main project.

# Clone your fork

git clone https://github.com/<YOUR_USERNAME>/tldr.git
cd tldr

# Add upstream and create a feature branch based on main

git remote add upstream https://github.com/tldr-pages/tldr.git
git fetch upstream
git checkout -b my-feature-branch upstream/main

All contributions must branch from upstream/main to maintain a clean history, as specified in CONTRIBUTING.md (lines 190–225).

Writing Content According to Project Standards

Adding or Modifying Command Pages

Before editing, review the requirements in CONTRIBUTING.md (lines 39–78) and the detailed rules in contributing-guides/style-guide.md. Pages must follow a strict structure defined in the Guidelines section (lines 41–55):

• 5 examples maximum 8: Each page should contain around 5 command examples, never exceeding 8.
• Imperative descriptions: All descriptions must use imperative mood.
• Standard placeholders: Use {{path/to/file}} or {{arg}} for user-supplied values.
• More information link: Include a link to the official command documentation.

Create new pages in the appropriate platform directory:

• pages/common/<command>.md for cross-platform commands
• pages.<locale>/<platform>/<command>.md for translations

Example minimal page structure (pages/common/hello.md):

# hello

> Print a friendly greeting.
> More information: <https://example.com/hello>.

- Display a simple greeting:

`echo "Hello, world!"`

- Show help for the command:

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

Contributing Script Changes

For modifications to helper utilities or automation, edit files within the scripts/ directory. These changes follow the same fork-branch-PR workflow but modify the tooling rather than command documentation.

Validating Your Changes Locally

Run the tldr-lint tool to catch formatting errors before submitting. As documented in CONTRIBUTING.md (lines 221–236), the linter checks markdown syntax, placeholder usage, and example counts.

Install and execute the linter:

npm install --global tldr-lint
tldr-lint pages/common/hello.md

Fix any reported violations to ensure CI checks pass.

Commit Standards and Pull Request Workflow

tldr-pages requires conventional commit messages following the <command>: <type of change> pattern (see CONTRIBUTING.md lines 71–88). Examples include pwd: add page or ls: update description.

git add pages/common/hello.md
git commit -m "hello: add page"

If you encounter pre-commit hook failures during development, you can bypass them temporarily with git commit --no-verify, though this is not recommended for final submissions (referenced in CONTRIBUTING.md lines 39–42).

Push your branch and open a pull request targeting tldr-pages/tldr:main:

git push origin my-feature-branch

On GitHub, enable "Allow edits by maintainers" (documented in CONTRIBUTING.md lines 53–57) so project maintainers can make minor fixes directly to your branch. Use the commit message as your PR title and include any relevant context in the description.

Summary

• Repository setup: Fork tldr-pages/tldr, clone locally, and branch from upstream/main.
• Content standards: Write 5–8 examples with imperative descriptions and {{placeholder}} syntax, following contributing-guides/style-guide.md.
• Local validation: Run tldr-lint on all modified pages to verify formatting.
• Commit format: Use <command>: <description> for all commit messages.
• Pull request: Target main, enable maintainer edits, and ensure CI passes.

Frequently Asked Questions

What file format do tldr-pages contributions use?

All pages are written in Markdown with a specific structure: an H1 command name, a description block starting with >, and bullet points with example descriptions followed by fenced code examples. The full specification is defined in contributing-guides/style-guide.md.

How many examples should a tldr page contain?

According to CONTRIBUTING.md (lines 41–55), each page should contain around 5 examples and must never exceed 8. This limit keeps the cheat sheets concise and scannable.

Can I contribute translations to existing pages?

Yes. Add translated files under pages.<locale>/ using the same directory structure as pages/. For example, a Spanish translation of pages/common/ls.md belongs in pages.es/common/ls.md. All translation pages must follow the same formatting and linting requirements as English originals.

What should I do if the linter reports errors I don't understand?

The tldr-lint tool validates markdown structure, placeholder formatting, and example counts. Check the error message against the rules in contributing-guides/style-guide.md. Common issues include incorrect placeholder syntax (missing curly braces) or having more than 8 examples.

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