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

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

Step 1: Determine the Platform Directory

The tldr-pages project organizes commands by platform compatibility. According to the Directory structure section in 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, not git_commit.md or Git-Commit.md. This rule is specified in the Title section of 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:

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

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:

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 to scaffold the file:

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, 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 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 CI pipeline.

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