# How to Use awesome-lint to Validate Your Awesome List

> Learn how to use awesome-lint to validate your awesome list automatically. Ensure correct formatting, fix broken links, and check metadata with this essential tool.

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

---

**TLDR:** Run `npx awesome-lint` inside your awesome list repository to check for formatting errors, broken links, and missing metadata. The official sindresorhus/awesome repository uses this tool in its GitHub Actions workflow to validate every contribution automatically.

The **awesome-lint** CLI tool enforces the strict quality standards expected of curated awesome lists. Whether you are maintaining your own list or submitting a pull request to the main repository, running this linter ensures your markdown meets community guidelines and all links resolve correctly.

## Installing awesome-lint

You can install the linter globally or run it on demand without installation.

**Global installation:**

```bash
npm install -g awesome-lint

```

**On-demand usage (recommended):**

```bash
npx awesome-lint

```

Both methods require Node.js installed on your system. Once available, the command validates the [`README.md`](https://github.com/sindresorhus/awesome/blob/main/README.md) file in your current working directory.

## Local Validation Workflow

To validate your awesome list locally, follow these steps:

1. **Navigate to your list directory:**

   ```bash
   cd awesome-my-topic
   ```

2. **Run the linter:**

   ```bash
   npx awesome-lint
   ```

3. **Review the output** and fix any reported warnings or errors.

The tool checks for missing link titles, malformed markdown, duplicate entries, and broken URLs. Resolve all issues before committing changes to ensure your list passes automated CI checks.

## How the Official Repository Validates Lists

The **sindresorhus/awesome** repository automates linting through a GitHub Actions workflow defined in [`.github/workflows/main.yml`](https://github.com/sindresorhus/awesome/blob/main/.github/workflows/main.yml). This workflow triggers a bash script at [`.github/workflows/repo_linter.sh`](https://github.com/sindresorhus/awesome/blob/main/.github/workflows/repo_linter.sh) that performs the following steps:

- Extracts the repository URL from new entries in [`readme.md`](https://github.com/sindresorhus/awesome/blob/main/readme.md) (specifically looking for URLs ending with `#readme`)
- Clones the target repository into a temporary directory
- Executes `npx awesome-lint` inside the cloned repository

Here is the exact script logic used in the CI pipeline:

```bash
#!/bin/bash
set -eo pipefail

# Extract the newly added repo URL ending with #readme from the diff

REPO_TO_LINT=$(
  git diff origin/main -- readme.md |
  grep ^+ |
  grep -Eo 'https.*#readme' |
  sed 's/#readme//'
)

if [ -z "$REPO_TO_LINT" ]; then
  echo "No new link found in the format:  https://....#readme"
else
  echo "Cloning $REPO_TO_LINT"
  mkdir -p cloned && cd cloned
  git clone "$REPO_TO_LINT" .
  npx awesome-lint
fi

```

When you submit a pull request adding a new entry to the main awesome list, this script automatically validates your repository against the linting rules.

## What awesome-lint Checks For

The validator performs comprehensive checks on your awesome list, including:

- **Link integrity** – Verifies that all URLs resolve correctly and are not returning 404 errors
- **Formatting standards** – Ensures consistent markdown syntax and proper list structure
- **Metadata requirements** – Confirms that entries include proper titles and descriptions
- **Duplicate detection** – Identifies repeated entries that may have been added multiple times
- **Repository standards** – Validates that the repository meets the awesome list criteria (description, license, etc.)

## Summary

- **awesome-lint** is the official CLI validation tool for awesome lists, distributed via npm.
- Run `npx awesome-lint` in any directory containing a [`README.md`](https://github.com/sindresorhus/awesome/blob/main/README.md) to validate the file locally.
- The **sindresorhus/awesome** repository uses [`.github/workflows/repo_linter.sh`](https://github.com/sindresorhus/awesome/blob/main/.github/workflows/repo_linter.sh) to automatically lint contributions by cloning the submitted repository and running the tool inside it.
- The CI script specifically looks for URLs ending with `#readme` to identify which repository to validate.
- Fix all reported formatting issues, broken links, and metadata errors before submitting your list to ensure it passes automated checks.

## Frequently Asked Questions

### Do I need to install Node.js to use awesome-lint?

Yes, awesome-lint is distributed as an npm package, so you must have Node.js and npm installed on your system. You can verify your installation by running `node --version` and `npm --version` before attempting to install or run the linter.

### Why does the CI script look for `#readme` in URLs?

The `#readme` anchor is a required format for entries in the official awesome list. The extraction logic in [`.github/workflows/repo_linter.sh`](https://github.com/sindresorhus/awesome/blob/main/.github/workflows/repo_linter.sh) uses this pattern to identify which repository URL was added in a pull request. The script strips the `#readme` anchor and clones the base repository to run validation checks against the actual list content.

### Can I use awesome-lint on lists not hosted on GitHub?

Yes, awesome-lint works with any awesome list regardless of hosting platform. As long as you have a local directory containing a [`README.md`](https://github.com/sindresorhus/awesome/blob/main/README.md) file formatted according to awesome list standards, you can run `npx awesome-lint` inside that directory to validate the content.

### What should I do if the linter reports false positives?

First, verify that your list actually conforms to the awesome list guidelines, as the linter enforces strict standards. If you encounter legitimate false positives, check the awesome-lint documentation for configuration options or consider opening an issue in the awesome-lint repository. Most validation errors, however, indicate actual formatting or content issues that should be addressed before submission.