Standard Markdown Syntax and Format for tldr Pages: The Complete Style Guide

The standard Markdown format for tldr pages requires a strict template consisting of an H1 command title, blockquote descriptions ending with a "More information" link, and 1-8 example blocks that each pair a hyphenated description with a fenced command.

The tldr-pages project maintains a lightweight yet rigid Markdown structure defined in contributing-guides/style-guide.md and enforced by the tldr-lint tool. This format ensures that command-line cheat sheets render consistently across all tldr clients, from terminal applications to web interfaces.

Page Structure

Every tldr page follows a top-to-bottom template with four required elements, each on its own line.

The mandatory components are:

• Title: # command-name — An H1 heading that ideally matches the filename (lowercase)

• Short description: > Short, snappy description. — A one-line imperative summary inside a blockquote

• More-information link: > More information: <https://example.com/command> — A blockquote line with the URL wrapped in angle brackets

• Example blocks: 1-8 pairs of description and command lines

An optional second description line may follow the first blockquote, but no additional styling like bold or italics is permitted.

Heading Requirements

The page must begin with a single ATX-style H1 heading.

In contributing-guides/style-guide.md, the specification states that the heading line starts with # followed by the command name. While the displayed heading may use any casing, the corresponding filename in pages/common/ or pages/os/ must be the lowercase version (e.g., pages/common/ls.md for the # ls command).

Description Lines

Descriptions use imperative mood and avoid formatting markup.

The primary description and optional secondary description both use blockquote syntax (>). Placeholders mentioned in descriptions must use backticks (e.g., `ls`) rather than bold or italic styling. The text should be concise, describing what the command does rather than what the user should do with it.

Example Blocks

Each example follows a strict two-line pattern separated by blank lines.

The structure is:

- Description of what the command does:

`command {{placeholder}} [options]`

Key formatting rules:

• The description starts with - and ends with a colon (:)
• The command line is wrapped in backticks on its own line
• A blank line must separate each example block from the next

Placeholder Syntax

User-supplied values use double-brace notation: {{placeholder}}.

According to the style guide, multi-word placeholders use snake_case (e.g., {{path/to/file}}). File extensions appear inside the placeholder only when optional.

Option Syntax

When documenting flags that have both short and long forms, use the compact syntax: {{[-o|--output]}}.

If only one form exists, document it directly without the braces.

Help and Version Examples

The final two examples of every page must follow exact wording:

- Display help:

`command --help`

- Display version:

`command --version`

These entries are mandatory and must use the precise phrasing "Display help" and "Display version" as defined in the style guide's Help and version commands section.

Linting and Validation

The repository provides the tldr-lint CLI tool to enforce these rules automatically.

Install it via npm:

npm install -g tldr-lint

Running tldr-lint path/to/page.md validates:

• Correct example count (minimum 1, maximum 8)
• Proper blank line separation between examples
• Valid placeholder syntax
• Required "More information" link format

The linter checks against the specifications in .markdownlint.json and is integrated into the CI pipeline for all pull requests.

Complete Example

Below is a fully compliant page structure for the fictional krita command, as shown in the official style guide:

# krita

> A sketching and painting program designed for digital artists.
> More information: <https://docs.krita.org/en/reference_manual/linux_command_line.html>.

- Start Krita:

`krita`

- Open specific files:

`krita {{path/to/image1 path/to/image2 ...}}`

- Start without a splash screen:

`krita --nosplash`

- Start with a specific workspace:

`krita --workspace {{Animation}}`

- Display help:

`krita --help`

- Display version:

`krita --version`

Summary

• Template structure: H1 title → blockquote description → "More information" link → 1-8 example blocks
• Example format: Hyphenated description ending with colon, followed by fenced command on next line, separated by blank lines
• Placeholders: Use {{snake_case}} syntax; optional flags use {{[-s|--long]}} format
• Mandatory endings: Last two examples must be "Display help" and "Display version"
• Validation: Use tldr-lint from npm to check compliance before submitting

Frequently Asked Questions

What is the maximum number of examples allowed in a tldr page?

Pages must contain between 1 and 8 example blocks. The tldr-lint tool will fail validation if a page contains zero examples or more than eight, as this restriction ensures tldr pages remain concise quick-reference guides rather than comprehensive manuals.

How should I format optional command-line flags in tldr pages?

When a command accepts both short and long flag variants, use the compact placeholder syntax {{[-o|--output]}}. If only one variant exists, document it directly without braces. This convention saves space while maintaining clarity about available options.

Where is the official tldr Markdown style guide located?

The canonical reference resides at contributing-guides/style-guide.md in the tldr-pages/tldr repository. This document defines the heading rules, example formatting, placeholder conventions, and the required "More information" link structure that all pages must follow.

What tool checks tldr pages for formatting errors?

The tldr-lint npm package enforces the standard Markdown syntax. Install it globally with npm install -g tldr-lint and run it against any .md file to verify example counts, blank line placement, and placeholder syntax before submitting pull requests.

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