How to Create an Alias Page for an Existing Command in tldr-pages

Use the scripts/set-alias-page.py helper script to interactively generate standardized alias pages that reference existing commands, automatically applying translation templates and optionally syncing across all supported languages.

The tldr-pages project maintains community-driven simplified manual pages for thousands of command-line tools. When a command functions as an alias of another—such as gsum being an alias for gnumfmt—the project uses lightweight alias pages rather than duplicating content. This guide explains how to create an alias page for an existing command in tldr-pages using the official maintainer scripts and repository structure.

Understanding the Alias Page Architecture

Alias pages in tldr-pages are minimal Markdown files stored alongside regular command pages. Each alias page indicates that one command name redirects to another, containing a standardized message that directs users to the original command's documentation. The repository organizes these files into platform-specific subdirectories within language folders: pages/ for English, pages.fr/ for French, pages.pt_BR/ for Brazilian Portuguese, and over 30 other locales.

The set-alias-page.py Script

The tldr-pages repository provides a dedicated automation tool at scripts/set-alias-page.py that handles the entire alias creation workflow. This script implements an interactive wizard for metadata collection, template rendering, file writing, and cross-language synchronization. It depends on shared utilities in scripts/_common.py, including the create_argument_parser function for CLI flag handling and the stage helper for git operations.

Interactive Metadata Collection

When you execute the script with a target path, the prompt_alias_page_info function (lines 44-80 in scripts/set-alias-page.py) initiates an interactive session to collect three essential fields:

• Page title: The display name for the command (defaults to the filename)
• Original command: The target command that this alias references
• Documentation command: The command users should look up for help (defaults to the original command)

Template Generation and File Writing

After collecting metadata, the generate_alias_page_content function (lines 20-41) loads the language-specific template from contributing-guides/translation-templates/alias-pages.md and substitutes the collected values. The set_alias_page function (lines 45-61) then writes the generated Markdown to the appropriate location—such as pages/osx/gsum.md—and reports whether the operation added a new file or updated an existing one.

Cross-Language Synchronization

To maintain consistency across the project's internationalization efforts, the sync_alias_page_to_locale function (lines 85-103) propagates alias pages from the English pages/ directory to all translated locales. This ensures that when you create an alias in English, corresponding files automatically appear in pages.fr/, pages.de/, pages.zh/, and other language folders with appropriate template localization.

Step-by-Step Workflow Examples

Creating a New Alias Page Interactively

To create an alias page for gsum that points to gnumfmt on the macOS platform:

python3 scripts/set-alias-page.py -p osx/gsum

The script prompts you for metadata:

1. Title: Press Enter to accept gsum or type a custom title
2. Original command: Type gnumfmt
3. Documentation command: Press Enter to use gnumfmt (or specify if documentation lives under a different name)
4. Confirmation: Type Y to proceed

The resulting file at pages/osx/gsum.md contains:

# gsum

> This command is an alias of `gnumfmt`.

- View documentation for the original command:

`tldr gnumfmt`

Synchronizing Across All Translations

After creating the English alias page, propagate it to all supported languages:

python3 scripts/set-alias-page.py -S

This executes the sync_alias_page_to_locale function, creating matching files in pages.fr/, pages.pt_BR/, and other locale directories while preserving existing translations.

Dry-Run and Staging Options

Verify changes before writing to disk:

python3 scripts/set-alias-page.py -p osx/gsum -n

The -n flag triggers a dry-run, displaying "page would be added" or "page would be updated" messages without modifying files.

To automatically stage created files for git commit:

python3 scripts/set-alias-page.py -p osx/gsum -s

The -s flag invokes the stage helper from scripts/_common.py (lines 24-33) to execute git add on the generated files.

Key Files and Components

Understanding the repository structure helps when debugging or manually editing alias pages:

• scripts/set-alias-page.py: The main CLI tool containing prompt_alias_page_info, generate_alias_page_content, set_alias_page, and sync_alias_page_to_locale
• scripts/_common.py: Shared utilities including create_argument_parser for CLI handling and stage for git operations
• contributing-guides/translation-templates/alias-pages.md: The template file used to render localized alias page content
• pages/: English language directory where alias pages are stored (e.g., pages/osx/gsum.md)
• pages.<locale>/: Translated versions (e.g., pages.fr/, pages.pt_BR/) that receive synchronized alias pages

Summary

Creating an alias page for an existing command in tldr-pages involves:

• Using the scripts/set-alias-page.py helper to generate standardized alias pages through an interactive wizard
• Providing three metadata points: the page title, original command, and documentation command
• Leveraging templates from contributing-guides/translation-templates/alias-pages.md to ensure consistent formatting across languages
• Synchronizing across all language translations using the -S flag to maintain consistency in pages.<locale>/ directories
• Utilizing dry-run (-n) and staging (-s) options to verify and prepare changes before committing

Frequently Asked Questions

What is the difference between an alias page and a regular tldr page?

A regular tldr page contains detailed examples, descriptions, and usage instructions for a specific command. An alias page is a lightweight placeholder that indicates one command name is an alias of another, containing only a reference to the original command's documentation rather than duplicated content. This prevents maintenance overhead when the original command's examples are updated.

Can I create an alias page manually without using the set-alias-page.py script?

Yes, you can manually create an alias page by copying the template from contributing-guides/translation-templates/alias-pages.md and placing it in the appropriate pages/ subdirectory with the correct filename. However, using the script is strongly recommended because it validates metadata, ensures correct formatting, and can automatically synchronize the page across all language translations via the sync_alias_page_to_locale function.

How do I update an existing alias page when the original command changes?

If the original command name changes or the documentation reference needs updating, run scripts/set-alias-page.py with the -p flag pointing to the existing alias page path. The interactive wizard will prompt you for the new metadata, and the set_alias_page function will update the existing file. Afterward, use the -S flag to propagate these changes to all translated versions in other locale directories.

Does the script support creating alias pages for all operating system platforms?

Yes, the script supports all platform-specific directories within the pages/ structure, including common/, linux/, osx/, windows/, android/, and sunos/. When specifying the path with the -p argument, include the platform directory (for example, linux/gsum or common/gnumfmt) to ensure the alias page is created in the correct location according to the command's platform availability.

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