# How to Handle False Positives Detected by awesome-lint

> Learn how to handle false positives in awesome-lint. Suppress errors with inline comments, configure global ignores, or report issues to improve the linter.

- Repository: [Sindre Sorhus/awesome](https://github.com/sindresorhus/awesome)
- Tags: how-to-guide
- Published: 2026-07-07

---

**You can suppress false positives in awesome-lint using inline HTML comments for single-line exemptions, creating a [`.awesome-lint.json`](https://github.com/sindresorhus/awesome/blob/main/.awesome-lint.json) configuration file to ignore specific rules globally, or reporting the issue upstream to the linter maintainers.**

The `awesome-lint` tool is the automated linter that validates Awesome lists against the strict formatting rules defined in the `sindresorhus/awesome` repository. When the linter flags valid entries as errors, you need specific mechanisms to maintain a clean CI pipeline while preserving correct content. Here are the three supported methods to handle these false positives without compromising your list's integrity.

## Suppress a Single Line with Inline Comments

For isolated false positives affecting specific entries, insert an HTML comment immediately before the offending line. This tells `awesome-lint` to skip validation for the next line only.

Use this syntax in your [`readme.md`](https://github.com/sindresorhus/awesome/blob/main/readme.md) or list file:

```markdown
<!-- awesome-lint-ignore-next-line -->
- [My Awesome Tool](https://github.com/me/awesome-tool) – A description that might trigger a false positive.

```

This approach is ideal when a rule incorrectly flags a single legitimate entry but you want the rest of the list validated normally.

## Ignore Rules Globally with Configuration File

When a specific rule consistently produces false positives for your entire list, create a [`.awesome-lint.json`](https://github.com/sindresorhus/awesome/blob/main/.awesome-lint.json) file in the root of your repository. This configuration file allows you to disable specific rule IDs project-wide.

Create [`.awesome-lint.json`](https://github.com/sindresorhus/awesome/blob/main/.awesome-lint.json) with the following structure:

```json
{
  "ignore": [
    "no-missing-description",
    "duplicate-name"
  ]
}

```

Place this file in your repository root, and `awesome-lint` will skip all occurrences of the specified rules during validation. This method is preferred when you have multiple entries that legitimately violate a rule that doesn't apply to your specific use case.

## Report the Issue Upstream

If you believe the linter rule is overly strict or contains a bug, you should report it to the `awesome-lint` maintainers. The [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) in the `sindresorhus/awesome` repository explicitly encourages this: *"If there are false-positives or things that cannot/shouldn't be fixed, please report it."*

Open an issue at the official repository:

```text
https://github.com/sindresorhus/awesome-lint/issues/new

```

Reporting upstream helps improve the linter for the entire community and may result in rule adjustments that eliminate the false positive for everyone.

## Why These Mechanisms Exist

`awesome-lint` runs as part of the continuous integration workflow defined in [`.github/workflows/repo_linter.sh`](https://github.com/sindresorhus/awesome/blob/main/.github/workflows/repo_linter.sh) within the `sindresorhus/awesome` repository. The script invokes the linter via `npx awesome-lint`, treating your Awesome list as a static markdown document that must conform to strict structural standards.

Because the linter cannot distinguish between intentional formatting and actual errors, these suppression mechanisms allow you to explicitly mark exceptions as intentional. This keeps your CI green while preserving the integrity of your list content.

## Summary

- **Use inline HTML comments** (`<!-- awesome-lint-ignore-next-line -->`) to suppress single-line false positives without affecting other validations.
- **Create a [`.awesome-lint.json`](https://github.com/sindresorhus/awesome/blob/main/.awesome-lint.json) file** with an `"ignore"` array to disable specific rules globally for your repository.
- **Report upstream** to `github.com/sindresorhus/awesome-lint` when rules are too strict or buggy, helping improve the tool for the community.
- All three methods are officially supported by the CI workflow in `sindresorhus/awesome` and documented in the pull request template.

## Frequently Asked Questions

### How do I suppress a single false positive without disabling the rule entirely?

Insert an HTML comment with the text `awesome-lint-ignore-next-line` immediately before the line that triggers the false positive. This tells the linter to skip validation for that specific line while continuing to check the rest of your document against the rule.

### Where should I place the [`.awesome-lint.json`](https://github.com/sindresorhus/awesome/blob/main/.awesome-lint.json) configuration file?

Place the [`.awesome-lint.json`](https://github.com/sindresorhus/awesome/blob/main/.awesome-lint.json) file in the root directory of your repository. The linter automatically detects this file and applies the ignored rules to all files in your project, ensuring consistent validation across your entire Awesome list.

### What should I do if awesome-lint keeps flagging correct entries?

First, verify that the entry actually complies with the Awesome list guidelines. If the entry is correct and the rule is misapplied, use the inline comment suppression for isolated cases or the configuration file for widespread issues. If you believe the rule itself is flawed, open an issue at `github.com/sindresorhus/awesome-lint` describing the false positive and providing examples.