# How to Create Your Own Awesome List from Scratch: A Complete Guide > Learn how to create your own awesome list from scratch. Follow this guide to structure your README, validate with awesome-lint, and submit to sindresorhus/awesome. - Repository: [Sindre Sorhus/awesome](https://github.com/sindresorhus/awesome) - Tags: how-to-guide - Published: 2026-07-07 --- **To create your own awesome list from scratch, create a GitHub repository named `awesome-`, 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`](https://github.com/sindresorhus/awesome/blob/main/create-list.md) and enforced by the [`pull_request_template.md`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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)](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-` format, then clone it locally: ```bash git clone https://github.com//awesome-.git cd awesome- ``` ### 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. ```markdown # Awesome Machine Learning Awesome 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`](https://github.com/sindresorhus/awesome/blob/main/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: ```bash 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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/readme.md), choose the `awesome-` 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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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`](https://github.com/sindresorhus/awesome/blob/main/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.