How to Document Subcommands in tldr Pages: Standard Patterns and Examples

To document subcommands in tldr-pages/tldr, include a notice line mentioning specific subcommands with dedicated pages, use the {{subcommand}} placeholder in generic examples, and place a help-for-subcommand example as the second-to-last item followed by the version example.

The tldr-pages/tldr repository maintains thousands of concise command-line reference pages across multiple platforms. When documenting commands that support subcommands—such as git, docker, or xml—contributors must follow specific conventions defined in contributing-guides/style-guide.md to ensure consistency. This guide explains the exact syntax and ordering required to document subcommands correctly according to the source code.

Standard Pattern for Subcommand Documentation

The repository enforces a strict pattern for pages describing commands with subcommands. Following this structure ensures that tldr clients can parse and display subcommand information correctly.

1. Include a Subcommand Notice Line

Place a short notice immediately after the description and "More information" link, but before the "See also" section. This line informs readers that specific subcommands maintain their own dedicated pages.

According to the heading order rules in contributing-guides/style-guide.md, the correct sequence is:

> Short description
> More information: <URL>
> Some subcommands such as `commit`, `add`, `push` have their own usage documentation.
> See also: ...

2. Use the {{subcommand}} Placeholder

When writing generic examples that apply to any subcommand, use the literal placeholder {{subcommand}}. This token allows tldr clients to highlight the subcommand position while keeping the example applicable to all subcommands.

For example, in pages/common/xml.md, the page uses this pattern:

- Execute a subcommand with input from a file or URI, printing to `stdout`:

`xml {{subcommand}} {{options}} {{path/to/input.xml|URI}}`

3. Structure the Help and Version Examples

The final two examples on any tldr page must be the help and version entries. For commands with subcommands, the help example should demonstrate how to get help for a specific subcommand rather than general help:

- Display help for a specific subcommand:

`xml {{subcommand}} --help`

- Display version:

`xml --version`

If the command supports version flags at the subcommand level, you may optionally document the subcommand-specific version instead of the global version.

Complete Example: Documenting a Command with Subcommands

The following template demonstrates the full implementation of the subcommand documentation pattern as used in the repository:

# examplecmd

> Brief description of the command.
> More information: <https://example.com/examplecmd>.

> Some subcommands such as `list`, `add`, `remove` have their own usage documentation.

- List items (default subcommand):

  `examplecmd list {{options}}`

- Add an item (explicit subcommand):

  `examplecmd add {{path/to/item}}`

- Remove an item (explicit subcommand):

  `examplecmd remove {{identifier}}`

- Display help for a subcommand:

  `examplecmd {{subcommand}} --help`

- Display version:

  `examplecmd --version`

The {{subcommand}} placeholder in the help line allows the client to substitute specific subcommand names while maintaining the correct syntax structure.

Reference Files and Automation

The subcommand documentation standards are enforced through several key files in the repository:

• contributing-guides/style-guide.md: Defines the required heading order, the subcommand notice format, and the {{subcommand}} placeholder usage.
• pages/common/xml.md: Provides a concrete production example of subcommand documentation with proper placeholder usage.
• scripts/set-page-title.py: Helper scripts used by maintainers to create or update pages, ensuring the subcommand pattern is applied automatically when needed.

Summary

• Add a notice line immediately after the "More information" link to mention subcommands with dedicated pages, following the strict heading order in contributing-guides/style-guide.md.
• Use {{subcommand}} as a placeholder in generic examples to enable client-side syntax highlighting and flexibility.
• Place help-for-subcommand examples as the second-to-last item, followed by the version example as the absolute last item on the page.
• Reference actual subcommand names in specific examples when documenting unique options, but maintain the generic placeholder pattern for consistency.

Frequently Asked Questions

Where exactly should the subcommand notice appear in the page structure?

According to contributing-guides/style-guide.md, place the subcommand notice line immediately after the "More information" URL and before any "See also" references. This follows the mandatory heading order: description → more information → subcommand notice → see also.

What is the purpose of the {{subcommand}} placeholder?

The {{subcommand}} placeholder serves as a standardized token that tldr clients can recognize and highlight separately from the base command. Using this placeholder instead of literal subcommand names (in generic examples) allows the same example pattern to apply across all subcommands while maintaining proper syntax demonstration.

How should I document help for a command that has multiple subcommands?

Include a help example that targets a specific subcommand using the syntax command {{subcommand}} --help. This example must appear as the second-to-last item on the page, immediately before the version example. This pattern appears in files like pages/common/xml.md and follows the repository's footer convention.

Can I omit the subcommand notice if only some subcommands have separate pages?

No, the style guide requires the notice line whenever any subcommands maintain their own dedicated tldr pages. List the specific subcommands that have separate documentation (e.g., commit, add, push) to guide users to the appropriate detailed pages while keeping the main command page concise.

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