How to Add an Awesome List to sindresorhus/awesome: A Complete Guide

To add an awesome list to sindresorhus/awesome, create a compliant standalone repository following the Awesome manifesto, submit a pull request adding a single formatted entry to the main README.md, and satisfy the mandatory 30-item checklist including community review requirements.

The sindresorhus/awesome repository serves as the central index for curated "awesome" lists across the open-source ecosystem. Adding your own list requires strict adherence to formatting guidelines defined in the repository's documentation files. This guide walks through the three-stage submission process using the actual source requirements found in pull_request_template.md, awesome.md, and create-list.md.

Stage 1: Prepare Your Awesome List Repository

Before submitting to the main index, your list must exist as a standalone public repository that follows the Awesome manifesto standards.

Follow the Awesome Manifesto and Naming Conventions

According to create-list.md lines 3-6, your repository name must use a lower-case slug format like awesome-my-topic. The list itself must begin with a title-cased heading (e.g., # Awesome My Topic) as specified in pull_request_template.md lines 60-62.

Include the official Awesome badge by adding this markdown to your README:

[![Awesome](https://awesome.re/badge.svg)](https://awesome.re)

Required Content Structure

Your list must include specific structural elements enforced by the PR checklist in pull_request_template.md:

• A Table of Contents section named exactly Contents placed as the first section after the description (lines 80-83)
• A short description at the top in uppercase ending with a period (lines 30-33)
• No table of contents generated by automated tools; manual curation is required

License and Authenticity Requirements

The repository must use a CC0 or other Creative Commons license (pull_request_template.md lines 86-89). Additionally, the list must be public, non-AI-generated, and have existed for at least 30 days (pull_request_template.md lines 44-46).

Stage 2: Submit a Pull Request to sindresorhus/awesome

Once your list meets all preparation criteria, you submit it to the main repository by modifying README.md and completing the mandatory checklist.

Format the PR Title and Entry

The PR title must follow the exact format Add <Name of List> without including the word "Awesome" (pull_request_template.md lines 21-28).

In the main repository's README.md, add a single line entry at the bottom of the appropriate category using this exact format:

- [Awesome My Topic](https://github.com/yourname/awesome-my-topic#readme) - A curated collection of resources for My Topic.

The URL must end with #readme and match the title-cased name of your list (pull_request_template.md lines 36-39).

Complete the Mandatory Checklist

The pull_request_template.md contains a 30-item checklist that you must satisfy. Key requirements include:

• Verifying your list is not AI-generated
• Ensuring no CI badges appear in your list's README (pull_request_template.md lines 102-103)
• Confirming you've run awesome-lint on your repository and fixed any issues (pull_request_template.md lines 46-47)

Stage 3: Pass Review and Community Verification

After submission, your PR undergoes community review and automated checks before merge.

Participate in Community Review

You must comment on at least four other open PRs with substantive feedback (pull_request_template.md lines 18-20). This ensures contributors review each other's work for guideline compliance before requesting maintainer time.

Final Verification and Merge

Once all checklist items are complete and awesome-lint passes, you must comment the word unicorn on your PR (pull_request_template.md lines 91-92). This confirms you have read the guidelines thoroughly. If the maintainer approves and all checks pass, your entry merges into the central README.md.

You may also add a "mentioned" badge to projects listed in your curated collection:

[![Mentioned in Awesome My Topic](https://awesome.re/mentioned-badge.svg)](https://github.com/yourname/awesome-my-topic)

Summary

• Create a standalone repository following create-list.md guidelines with lower-case slug naming, CC0 licensing, the Awesome badge, and a Table of Contents named Contents
• Submit a PR to sindresorhus/awesome titled Add [List Name] and append your entry to the bottom of the appropriate category in README.md using the format - [Title](URL#readme) - Description
• Verify completion of the 30-item checklist in pull_request_template.md, review four other PRs with meaningful comments, run awesome-lint, and comment "unicorn" to signal readiness for final review

Frequently Asked Questions

How long must my list exist before submitting to sindresorhus/awesome?

Your awesome list must be publicly available for at least 30 days before submission. This requirement, specified in pull_request_template.md lines 44-46, ensures lists have matured content and stable URLs before joining the central index.

What license is required for an awesome list?

According to pull_request_template.md lines 86-89, all awesome lists must use a CC0 (Creative Commons Zero) or other Creative Commons license. This dedication to the public domain allows free copying, modification, and distribution of the curated content.

Why do I need to comment on other pull requests?

The requirement to comment substantively on at least four other open PRs (pull_request_template.md lines 18-20) ensures community-driven quality control. Contributors review each other's lists for guideline compliance before maintainers spend time on detailed reviews.

What is the purpose of the "unicorn" comment requirement?

After completing all checklist items, you must comment the word unicorn on your PR (pull_request_template.md lines 91-92). This serves as a final attestation that you have actually read the contribution guidelines rather than blindly checking boxes, reducing maintainer burden from incomplete submissions.

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