# How to Add a New Command Page to the tldr-pages Project

> Learn how to add a new command page to the tldr-pages project by formatting Markdown, validating with tldr-lint, and submitting a pull request. Contribute to your favorite command-line tool documentation.

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

---

**To add a new command page to tldr-pages, create a Markdown file in the appropriate platform directory (pages/common/ for cross-platform tools or pages/linux/, pages/windows/, etc. for platform-specific commands), format it according to the style guide using double curly braces for placeholders, validate it with tldr-lint, and submit a pull request using the conventional commit format `<command>: add page`.**

Adding a new command page to the **tldr-pages/tldr** repository follows a standardized workflow defined in [`CONTRIBUTING.md`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md) and the project style guide. This process ensures every page maintains consistent formatting, valid Markdown structure, and proper placeholder conventions that pass the automated CI checks in [`.github/workflows/lint.yml`](https://github.com/tldr-pages/tldr/blob/main/.github/workflows/lint.yml).

## Step 1: Determine the Platform Directory

The tldr-pages project organizes commands by platform compatibility. According to the *Directory structure* section in [`CONTRIBUTING.md`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md), you must place your file in the correct subdirectory under `pages/`:

- **pages/common/** – Use this for commands that work on **two or more platforms** (e.g., Linux, macOS, and Windows).
- **pages/linux/**, **pages/macos/**, **pages/windows/**, **pages/android/**, **pages/sunos/** – Use these for platform-specific commands that only function on that particular operating system.

## Step 2: Choose the Correct File Name

The filename must exactly match the command name in lower-case with a `.md` extension. For example, if you are documenting the `git-commit` command, the file must be named [`git-commit.md`](https://github.com/tldr-pages/tldr/blob/main/git-commit.md), not [`git_commit.md`](https://github.com/tldr-pages/tldr/blob/main/git_commit.md) or [`Git-Commit.md`](https://github.com/tldr-pages/tldr/blob/main/Git-Commit.md). This rule is specified in the *Title* section of [`contributing-guides/style-guide.md`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/style-guide.md).

## Step 3: Create the Markdown Content

Every tldr page must follow a strict structure defined in `contributing-guides/style-guide.md#markdown-format`.

### Required Page Structure

A minimal valid page contains a level-1 heading, a short description, a "More information" link, and example entries:

```markdown

# command-name

> Short, snappy description.
> More information: <https://upstream-doc.example/>

- Example description:

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

- Another example:

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

```

### Placeholder and Link Conventions

- **Placeholders** must always be wrapped in **double curly braces** (`{{ }}`) as detailed in `contributing-guides/style-guide.md#placeholders`.
- The **"More information"** line must contain a reachable URL enclosed in angle brackets. The CI pipeline automatically checks that this URL resolves.

## Step 4: Validate with tldr-lint Locally

Before committing, validate your page using the official linter. The `CONTRIBUTING.md#testing-pages-locally` section specifies how to install and run `tldr-lint`:

```bash
npm install --global tldr-lint
tldr-lint pages/common/your-command.md

```

Running this locally catches formatting errors before the repository's GitHub Actions workflow runs the same checks on your pull request.

## Step 5: Commit and Submit a Pull Request

Once your file passes linting, commit it using the conventional format specified in `CONTRIBUTING.md#commit-message-and-pr-title`:

```bash
git add pages/common/htop.md
git commit -m "htop: add page"
git push origin your-branch-name

```

Open a pull request against the `main` branch. The commit message must follow the pattern `<command>: add page` (e.g., `htop: add page` or `git-commit: add page`).

## Optional: Generate Alias Pages

If you are adding a page that is an alias for an existing command, use the helper script located at [`scripts/set-alias-page.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-alias-page.py) to scaffold the file:

```bash
python scripts/set-alias-page.py -p common/vi -s

```

This ensures alias pages follow the correct symlink or redirection format required by the project.

## Summary

- Place files in **pages/common/** for multi-platform commands or in platform-specific directories (e.g., **pages/linux/**) for OS-specific tools.
- Name files using the exact lower-case command name with a **.md** extension.
- Follow the strict Markdown template with **double curly braces** for placeholders and a valid **More information** URL.
- Validate all changes locally using **`tldr-lint`** to avoid CI failures.
- Submit pull requests to the **`main`** branch using the commit format **`<command>: add page`**.

## Frequently Asked Questions

### What directory should I use for a command that works on both Linux and macOS?

Place it in **pages/common/**. According to the directory structure rules in [`CONTRIBUTING.md`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md), any command that functions on two or more platforms belongs in the common directory rather than a platform-specific folder.

### How do I format variable placeholders in example commands?

Wrap all placeholders in **double curly braces** like `{{file}}` or `{{[-h|--help]}}`. This convention is strictly enforced by the linter and defined in `contributing-guides/style-guide.md#placeholders`.

### What commit message format does tldr-pages require?

Use the conventional format **`<command>: add page`** (e.g., `htop: add page` or `docker-compose: add page`). This format is required by [`CONTRIBUTING.md`](https://github.com/tldr-pages/tldr/blob/main/CONTRIBUTING.md) for all new page submissions.

### How do I check my page formatting before submitting a pull request?

Install **tldr-lint** via npm (`npm install --global tldr-lint`) and run it against your file path (e.g., `tldr-lint pages/common/command.md`). This performs the same validation as the repository's automated [`.github/workflows/lint.yml`](https://github.com/tldr-pages/tldr/blob/main/.github/workflows/lint.yml) CI pipeline.