Understanding Placeholder Syntax in tldr Pages: How {{ }} Works

tldr pages use double-brace placeholder syntax ({{…}}) to mark variable parts of commands—such as file paths, options, and arguments—allowing users to copy examples and substitute their own values without hard-coding specific data.

The tldr-pages project provides simplified, community-driven command-line examples that prioritize readability and reusability. According to the tldr-pages/tldr source code, the {{ }} placeholder syntax serves as the core templating mechanism that keeps command examples platform-agnostic and easy to customize. These placeholders appear throughout the repository in files like AGENTS.md and concrete command pages such as pages/common/tar.md.

Placeholder Syntax Conventions

The placeholder conventions are formally documented in [AGENTS.md](https://github.com/tldr-pages/tldr/blob/main/AGENTS.md#placeholder-conventions) at the root of the tldr-pages/tldr repository. This file establishes the grammar that all contributors must follow when writing command examples, ensuring consistency across thousands of pages.

File Path Patterns

Standard path placeholders include:

• {{path/to/file}} for file paths
• {{path/to/directory}} for directory paths
• {{filename}} for filenames without directory components

Option and Argument Variations

Handle command-line flexibility with these patterns:

• {{option1|option2}} for mutually exclusive alternatives
• {{[-v|--verbose]}} for options offering both short and long forms
• {{[-it|--interactive --tty]}} for grouped flags
• {{file1 file2 …}} for multiple arguments

Numeric Ranges and Wildcards

Support quantitative inputs with:

• {{1..5}} for numeric ranges (expanding to 1 2 3 4 5)
• {{*.ext}} for wildcard patterns like file extensions

Real-World Examples in Source Code

Concrete implementations of these patterns appear in [pages/common/tar.md](https://github.com/tldr-pages/tldr/blob/main/pages/common/tar.md) and other command pages. These examples demonstrate how static command structures combine with variable placeholders to create reusable documentation.

Creating Archives with tar

- [c]reate an archive and write it to a [f]ile:

`tar cf {{path/to/target.tar}} {{path/to/file1 path/to/file2 ...}}`

In this example, {{path/to/target.tar}} represents the destination archive file, while {{path/to/file1 path/to/file2 ...}} indicates one or more source files. The double braces visually signal where substitution is required.

Using Alternative Options

`grep {{[-i|--ignore-case]}} "pattern" {{path/to/file}}`

The placeholder {{[-i|--ignore-case]}} specifies that either the short flag -i or the long form --ignore-case is valid, providing flexibility without cluttering the example.

Wildcard Extraction

`tar xf {{path/to/source.tar}} --wildcards "{{*.html}}"`

Here, {{*.html}} functions as a shell-style wildcard pattern, indicating that any HTML file within the archive matches this parameter.

Numeric Sequences

`seq {{1..5}}`

The {{1..5}} placeholder expands to the sequence 1 2 3 4 5, demonstrating how ranges simplify documentation for commands accepting multiple numeric inputs.

Automation and Validation Tools

The tldr-lint tool enforces placeholder conventions across the entire repository, preventing malformed syntax from entering production pages. This validation ensures that all {{ }} patterns follow the specifications defined in AGENTS.md.

Script Integration

Maintenance scripts such as [scripts/update-command.py](https://github.com/tldr-pages/tldr/blob/main/scripts/update-command.py) and scripts/set-more-info-link.py programmatically parse {{…}} patterns to update examples and manage cross-references. These automation tools rely on the strict, predictable syntax to manipulate command strings without breaking the surrounding markdown structure.

Localization Architecture

Because placeholders contain no language-specific text, they remain constant across translations while surrounding descriptions change. This language-neutral approach allows translators to preserve the exact {{ }} structure, ensuring that localized pages remain functionally identical to their English counterparts.

Summary

• Double-brace syntax ({{…}}) indicates variable content in command examples, keeping tldr pages generic and platform-independent.
• Path conventions like {{path/to/file}} and {{filename}} standardize how files and directories are referenced across all pages.
• Option patterns including {{[-a|--alternative]}} and {{opt1|opt2}} concisely represent mutually exclusive flags and grouped arguments.
• Automation support through tldr-lint and Python scripts like scripts/update-command.py validates and parses placeholders programmatically.
• Localization benefits arise from the language-neutral nature of placeholders, enabling consistent structure across all translated versions of the documentation.

Frequently Asked Questions

What do the curly braces {{ }} mean in tldr pages?

The {{ }} syntax marks a placeholder where users must insert their own values—such as specific file paths, options, or arguments—before executing the command. These markers are never rendered literally; they serve exclusively as visual cues indicating where substitution is required.

How should I format options that have both short and long forms?

Use the syntax {{[-s|--long-option]}} inside the double braces. For instance, {{[-i|--ignore-case]}} in a grep command communicates that either -i or --ignore-case is acceptable. This convention, defined in AGENTS.md, maintains brevity while preserving clarity about available alternatives.

Are there tools to validate placeholder syntax?

Yes. The tldr-lint tool automatically checks all pages for correct placeholder formatting, ensuring compliance with the conventions specified in AGENTS.md. Additionally, repository maintenance scripts like scripts/update-command.py depend on strict {{ }} syntax to parse and update command examples programmatically.

Can I use wildcards or numeric ranges inside placeholders?

Absolutely. Use {{*.ext}} for wildcard patterns (such as {{*.html}}) and {{1..5}} for numeric ranges. These patterns appear in commands like seq {{1..5}} or tar extraction examples, allowing users to understand expected input formats without listing every possible value.

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