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

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 dev dependencies.

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.

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.

# 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.

tldr-lint ./pages

For the exact commands used in CI, reference the run_tests function in 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.

# Run the repository's official test harness

./scripts/test.sh

The script performs the following linting sequence:

# 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:

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

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

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

These patterns are documented in 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.
• 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 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. 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.

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 file differ from running tldr-lint manually?

The 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.

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