tldr-maintenance

What the tool calculates

tldr-maintenance is a repository that runs a Bash script to calculate metrics about the current state of the tldr-pages repository. These metrics help contributors quickly spot whether there is still work to do to maintain and improve quality, and they also help detect issues in the tldr-pages repo itself. The README notes that running two upstream scripts, set-alias-page.py and wrong-filename.sh, generates false positives, so the results need to be checked by hand. The metrics can be used by code owners to watch their owned language and detect if changes are needed. The tool is part of the tldr-pages maintenance machinery rather than a user-facing command collection. For English pages the metrics cover malformed more-info link pages, missing tldr pages where one page references another that does not exist, misplaced pages that are not inside a supported platform folder, and linter errors from markdownlint and tldr-lint with specific checks enabled. Each metric maps to a known class of defect in the tldr format, so a contributor can read the summary and know which pages to open first. The script is small and utility minded, which matches the role of a maintenance helper in a large documentation project with many volunteer contributors. The false-positive note is important because it tells contributors not to trust the raw output without a human check of the pages that the script flags as problems.

Translations and coverage

For other languages the metric set is wider because translations can drift from the English source. The checks include malformed or outdated more-info link pages, where outdated means the link no longer matches the English page, missing tldr pages, misplaced pages, and outdated pages based on the number of commands differing from the English page. A deeper check compares the commands themselves by stripping template placeholders and quoted strings and comparing the remainder. The tool also flags missing English pages, where a filename cannot be found as an English page, and missing translated pages, where the English page has no translation. Linter errors run markdownlint and tldr-lint with language-specific checks. Several of these conditions can also be seen through an external translation tracker site referenced in the README. The design goal is to give each language's code owners a per-language view of drift and gaps, so translation effort can be targeted at the pages that are actually behind rather than scanned by hand across the whole tree. By reporting counts and percentages, the tool turns a vague sense of lag into a concrete backlog that a contributor can work down one language at a time. The percentage reporting turns a vague sense of translation lag into a concrete backlog a contributor can work down one language at a time with clear priorities.

Outputs and artifacts

At the end of a metrics run a summary is written to a metrics log file, and that summary is tracked in a GitHub issue along with the metrics per translation. Some numbers include a percentage calculated against a relevant total, such as total pages or total commands. The reported percentages cover malformed or outdated more-info links, missing alias pages, missing tldr commands, misplaced pages, outdated pages by command count, outdated pages by command content, missing English pages, missing translated pages, and total lint errors. After a workflow run an artifact is created that can be downloaded to see exact output per language per metric, so a contributor can find the specific page that needs attention. A summary is also downloadable from the latest GitHub release. The repository carries workflow badges for calculating metrics and for checking links with Lychee, which shows the metrics run on a schedule or on demand as part of tldr-pages upkeep. For maintainers the artifact and issue pair turn a raw script into a standing report that the community can watch over time, which is the difference between a one-off check and a maintained quality signal. The artifact and issue pair turn a one-off script into a standing report the community can watch, which is the real point of maintaining quality across many languages.

Editorial conclusion

tldr-maintenance is written in Python, lists no SPDX license in its metadata, and its repository was last updated on 2026-08-24.