How to Create Your Own Awesome List from Scratch: A Complete Guide

To create your own awesome list from scratch, create a GitHub repository named awesome-<topic>, populate it with a README following the official layout including the Awesome badge, validate it with awesome-lint, wait 30 days, and submit a pull request to sindresorhus/awesome.

The sindresorhus/awesome repository serves as the central index for curated collections of high-quality resources across every technology domain. Creating your own awesome list from scratch involves a strict three-phase workflow defined in create-list.md and enforced by the pull_request_template.md checklist to ensure consistency and quality across the ecosystem.

Preparation Phase

Before writing any code, validate your idea against the existing index and plan your list structure according to the requirements in create-list.md. This preparation ensures your topic is original and aligns with the Awesome project's quality standards.

Verify Originality and Scope

Search the existing collection in [readme.md](https://github.com/sindresorhus/awesome/blob/main/readme.md) using GitHub search to ensure no similar list already exists. Read the Awesome manifesto to confirm your topic merits curation—the goal is to gather the best of the best resources, not exhaustive directories.

Establish Naming Conventions

Your repository name must be lowercase, hyphenated, and prefixed with awesome-. For example, awesome-machine-learning or awesome-deno. This naming convention ensures discoverability and aligns with the existing ecosystem patterns documented in the contributing guidelines.

Implementation Phase

This phase transforms your concept into a compliant repository that passes automated validation.

Initialize the Repository

Create a new GitHub repository using the awesome-<slug> format, then clone it locally:

git clone https://github.com/<your-username>/awesome-<slug>.git
cd awesome-<slug>

Structure the README

Your README must follow a strict template to pass awesome-lint. Start with an H1 title containing the Awesome badge, followed by a one-sentence description, a Contents section, and categorized entries.

# Awesome Machine Learning <a href="https://github.com/sindresorhus/awesome"><img src="https://awesome.re/badge.svg" alt="Awesome"></a>

A curated list of awesome Machine Learning frameworks, libraries, and resources.

## Contents

- [Frameworks](#frameworks)
- [Datasets](#datasets)

## Frameworks

- [TensorFlow](https://github.com/tensorflow/tensorflow#readme) - An end-to-end open source platform for machine learning.
- [PyTorch](https://github.com/pytorch/pytorch#readme) - A flexible deep learning framework.

## Datasets

- [ImageNet](http://www.image-net.org) - Large visual database for image classification research.

Critical formatting rules from pull_request_template.md define how entries must be structured to pass automated validation. Each entry must follow these standards:

• Entry descriptions must start with a capital letter and end with a period.
• Resource links should end with #readme where applicable.
• The Table of Contents must only link to content sections, excluding meta sections like "Contributing" or "License".

Validate with awesome-lint

Run the official linter to catch formatting violations before submission:

npx awesome-lint .

Fix any errors regarding punctuation, capitalization, or link formatting to ensure compliance with the strict parsing rules.

Configure Repository Metadata

Navigate to your repository settings and add the topics awesome-list and awesome. Include a LICENSE file containing a Creative Commons license, preferably CC0, to explicitly dedicate your list to the public domain.

Submission Phase

Once your repository meets all technical requirements documented in the source files, you initiate the formal review process through the main Awesome repository. This phase requires strict adherence to timeline and community participation rules.

Open the Pull Request

Create a new pull request against sindresorhus/awesome and complete the pull_request_template.md checklist. Include your repository URL and a concise rationale explaining your topic's scope and value.

Satisfy Waiting Period and Review Requirements

Your list must remain public for at least 30 days before eligibility for inclusion. Additionally, you must review at least four other open pull requests in the main repository to participate in the community quality control process. Address any feedback from maintainers by updating your README and pushing commits to the same PR branch.

Summary

• Preparation: Verify uniqueness in readme.md, choose the awesome-<slug> name format, and read the manifesto.
• Implementation: Create the repository, format the README with the badge and Contents section, run awesome-lint, add topics awesome-list and awesome, and include a CC0 license.
• Submission: Complete the pull_request_template.md, wait 30 days, review four other PRs, and respond to maintainer feedback.

Frequently Asked Questions

How long must I wait before my awesome list can be added to the main repository?

Your repository must be public for at least 30 days before it becomes eligible for inclusion in sindresorhus/awesome. This waiting period ensures the list is stable and actively maintained before joining the curated index.

What naming convention must I follow for my awesome list repository?

The repository must be lowercase, hyphen-separated, and prefixed with awesome- (e.g., awesome-python or awesome-react). This convention is enforced in create-list.md and helps maintain consistency across the ecosystem.

Why does my awesome list pull request require me to review other submissions?

The contributing.md guidelines require you to review at least four other open pull requests before your submission is accepted. This policy distributes the review workload and ensures contributors understand the quality standards before their own list is evaluated.

What license should I use for my awesome list repository?

You should include a LICENSE file with a Creative Commons license, preferably CC0. This dedicates your work to the public domain, allowing free redistribution and modification consistent with the open nature of the Awesome project.

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