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

> Follow this guide to add an awesome list to sindresorhus/awesome. Create a compliant repo, submit a PR to the main README, and meet the 30-item checklist for community review.

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

---

**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`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md), [`awesome.md`](https://github.com/sindresorhus/awesome/blob/main/awesome.md), and [`create-list.md`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) lines 60-62.

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

```markdown
[![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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) lines 21-28).

In the main repository's [`README.md`](https://github.com/sindresorhus/awesome/blob/main/README.md), add a single line entry at the **bottom** of the appropriate category using this exact format:

```markdown
- [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`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) lines 36-39).

### Complete the Mandatory Checklist

The [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md) lines 102-103)
- Confirming you've run `awesome-lint` on your repository and fixed any issues ([`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/README.md).

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

```markdown
[![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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/README.md) using the format `- [Title](URL#readme) - Description`
- **Verify** completion of the 30-item checklist in [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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.