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

> Learn how tldr pages use {{ }} placeholder syntax to represent variables like file paths and arguments. Easily copy and adapt command examples by substituting your own values.

- Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr)
- Tags: deep-dive
- Published: 2026-03-05

---

**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`](https://github.com/tldr-pages/tldr/blob/main/AGENTS.md) and concrete command pages such as [`pages/common/tar.md`](https://github.com/tldr-pages/tldr/blob/main/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)](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)](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

```markdown
- [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

```markdown
`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

```markdown
`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

```markdown
`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`](https://github.com/tldr-pages/tldr/blob/main/AGENTS.md).

### Script Integration

Maintenance scripts such as [[`scripts/update-command.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/update-command.py)](https://github.com/tldr-pages/tldr/blob/main/scripts/update-command.py) and [`scripts/set-more-info-link.py`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/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`](https://github.com/tldr-pages/tldr/blob/main/AGENTS.md). Additionally, repository maintenance scripts like [`scripts/update-command.py`](https://github.com/tldr-pages/tldr/blob/main/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.