# Contributing to tldr-pages: Guidelines and Pull Request Process Explained > Learn how to contribute to tldr pages. This guide explains the pull request process and guidelines for submitting new pages to the tldr-pages repository. - Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr) - Tags: how-to-guide - Published: 2026-03-05 --- **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 `: ` 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. ```bash # Clone your fork git clone https://github.com//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`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md) (lines 190–225). ## Writing Content According to Project Standards ### Adding or Modifying Command Pages Before editing, review the requirements in [`CONTRIBUTING.md`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md) (lines 39–78) and the detailed rules in [`contributing-guides/style-guide.md`](https://github.com/tldr-pages/tldr/blob/main/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/.md` for cross-platform commands - `pages.//.md` for translations Example minimal page structure ([`pages/common/hello.md`](https://github.com/tldr-pages/tldr/blob/main/pages/common/hello.md)): ```markdown # hello > Print a friendly greeting. > More information: . - 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`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md) (lines 221–236), the linter checks markdown syntax, placeholder usage, and example counts. Install and execute the linter: ```bash 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 `: ` pattern (see [`CONTRIBUTING.md`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md) lines 71–88). Examples include `pwd: add page` or `ls: update description`. ```bash 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`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md) lines 39–42). Push your branch and open a pull request targeting `tldr-pages/tldr:main`: ```bash git push origin my-feature-branch ``` On GitHub, enable **"Allow edits by maintainers"** (documented in [`CONTRIBUTING.md`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md). - **Local validation**: Run `tldr-lint` on all modified pages to verify formatting. - **Commit format**: Use `: ` 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`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md). ### How many examples should a tldr page contain? According to [`CONTRIBUTING.md`](https://github.com/tldr-pages/tldr/blob/main/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./` using the same directory structure as `pages/`. For example, a Spanish translation of [`pages/common/ls.md`](https://github.com/tldr-pages/tldr/blob/main/pages/common/ls.md) belongs in [`pages.es/common/ls.md`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md). Common issues include incorrect placeholder syntax (missing curly braces) or having more than 8 examples.