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

> Master tldr pages Markdown syntax with this complete style guide. Learn the standard format including H1 titles blockquotes and command examples for clear documentation.

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

---

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

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

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

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

```markdown

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