# How to Test TLDR Pages Locally Using tldr-lint: Complete Validation Guide

> Easily test tldr pages locally with tldr-lint. Validate your TLDR pages against the style guide using this npm package. Run tldr-lint ./pages or target specific files for complete validation.

- Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr)
- Tags: how-to-guide
- Published: 2026-03-05

---

**To test TLDR pages locally, install the `tldr-lint` npm package and run `tldr-lint ./pages` to validate the entire repository against the style guide, or target individual files with `tldr-lint path/to/page.md`.**

The `tldr-pages/tldr` repository maintains thousands of command-line cheat sheets across multiple languages, all adhering to a strict markdown style guide. When contributing new pages or editing existing ones, you must validate your changes locally using **tldr-lint**, the official CLI utility that checks for violations like incorrect formatting or missing placeholders. This tool reports errors using specific codes (e.g., **TLDR001**, **TLDR104**) and can automatically fix many formatting issues before you submit a pull request.

## Installing tldr-lint for Local Development

Before testing pages, install the validation tool globally via npm as listed in the repository’s [`package.json`](https://github.com/tldr-pages/tldr/blob/main/package.json) dev dependencies.

```bash
npm install -g tldr-lint

```

Alternatively, run `npm install` from the repository root to install the specific version locked for the project.

## Testing Individual TLDR Pages

### Validating a Specific File

To check a single page for style guide compliance, pass the file path directly to the linter. This validates the markdown structure, placeholder syntax, and page metadata.

```bash
tldr-lint pages/common/tar.md

```

### Auto-formatting with the -f Flag

The tool can print a formatted version to stdout or rewrite the file in place. Use `-f` to preview changes and `-f -i` to apply them directly.

```bash

# Preview formatted output

tldr-lint -f pages/common/ls.md

# Rewrite the file with proper spacing and alignment

tldr-lint -f -i pages/common/ls.md

```

## Testing the Entire Repository Locally

To validate all English pages at once, run the linter against the `pages` directory. This mirrors the primary check performed in continuous integration.

```bash
tldr-lint ./pages

```

For the exact commands used in CI, reference the `run_tests` function in **[`scripts/test.sh`](https://github.com/tldr-pages/tldr/blob/main/scripts/test.sh)**. This script orchestrates the full validation pipeline, first running `markdownlint` on all files, then executing `tldr-lint` with locale-specific ignore patterns.

```bash

# Run the repository's official test harness

./scripts/test.sh

```

The script performs the following linting sequence:

```bash

# 1. Validate markdown syntax across all locales

find pages* -name '*.md' -exec markdownlint {} +

# 2. Lint English pages (strictest rules)

tldr-lint ./pages

# 3. Lint locale-specific directories with tailored ignore lists

for f in ./pages.*; do
  checks="TLDR104"
  case $f in
    *ar*|*bn*|*fa*|*hi*|*ja*|*ko*|*lo*|*ml*|*ne*|*ta*|*th*|*tr*)
      checks+=",TLDR003,TLDR004,TLDR015"
      ;;
    *zh*)
      checks+=",TLDR003,TLDR004,TLDR005,TLDR015"
      ;;
  esac
  tldr-lint --ignore "$checks" "$f"
done

```

## Handling Locale-Specific Validation Rules

Different language locales have unique formatting requirements that may trigger false positives under standard English rules. Use the `--ignore` (or `-I`) flag with comma-separated error codes to suppress these warnings when testing non-English pages.

For example, when validating the Arabic locale (`pages.ar`), the CI script ignores placeholder and title-related checks that do not apply to right-to-left languages:

```bash
tldr-lint --ignore TLDR104,TLDR003,TLDR004,TLDR015 pages.ar

```

Similarly, Chinese locales (`pages.zh`) require ignoring **TLDR005** in addition to the standard set:

```bash
tldr-lint --ignore TLDR104,TLDR003,TLDR004,TLDR005,TLDR015 pages.zh

```

These patterns are documented in [`scripts/test.sh`](https://github.com/tldr-pages/tldr/blob/main/scripts/test.sh) and should be copied when testing corresponding locales locally.

## Summary

- **Install** `tldr-lint` via `npm install -g tldr-lint` to obtain the official validation tool documented in [`pages/common/tldr-lint.md`](https://github.com/tldr-pages/tldr/blob/main/pages/common/tldr-lint.md).
- **Validate single pages** by passing the file path directly to catch specific errors like **TLDR001** (page title format) or **TLDR104** (missing more information link).
- **Format automatically** using `tldr-lint -f -i path/to/page.md` to fix spacing and placeholder issues before committing.
- **Test full repositories** with `tldr-lint ./pages` or execute [`./scripts/test.sh`](https://github.com/tldr-pages/tldr/blob/main/./scripts/test.sh) to run the exact CI pipeline including markdownlint.
- **Suppress locale-specific errors** with `--ignore TLDR003,TLDR004` when testing languages like Arabic, Japanese, or Chinese that have different title and placeholder conventions.

## Frequently Asked Questions

### What is tldr-lint and where is it documented?

**tldr-lint** is the official command-line validator for the tldr-pages project, installed as a dev dependency in [`package.json`](https://github.com/tldr-pages/tldr/blob/main/package.json). It checks markdown files against the TLDR style guide and outputs error codes like **TLDR001** for formatting violations. Complete usage instructions are available in the repository at [`pages/common/tldr-lint.md`](https://github.com/tldr-pages/tldr/blob/main/pages/common/tldr-lint.md).

### How do I automatically fix formatting errors in a TLDR page?

Run `tldr-lint -f -i path/to/page.md` to rewrite the file in place with correct spacing, indentation, and placeholder syntax. The `-f` flag outputs the formatted content, while `-i` applies the changes directly to the source file, ensuring compliance with rules like **TLDR003** (improper example formatting).

### Can I ignore specific error codes when testing locally?

Yes, use the `--ignore` flag followed by a comma-separated list of error codes. For example, `tldr-lint --ignore TLDR104,TLDR015 ./pages` skips the "missing more information link" and "improper page description" checks. This is essential when testing locale-specific directories like `pages.ar` or `pages.zh` that have different linguistic requirements.

### How does the [`scripts/test.sh`](https://github.com/tldr-pages/tldr/blob/main/scripts/test.sh) file differ from running tldr-lint manually?

The **[`scripts/test.sh`](https://github.com/tldr-pages/tldr/blob/main/scripts/test.sh)** script is the comprehensive CI harness used by GitHub Actions. It runs `markdownlint` first for general markdown syntax, then executes `tldr-lint ./pages` for English content, and finally loops through all `pages.*` directories with tailored `--ignore` lists for each language. Running this script locally ensures your changes pass the exact same validation pipeline as the official repository.