Awesome Creator

Awesome Creator

Expert guidance for creating Awesome lists that comply with official sindresorhus/awesome standards. Awesome lists are curated collections of the best resources on specific topics, maintained by the community.

When to use this skill:

• Creating a new Awesome list from scratch
• Validating an existing Awesome list for compliance
• Updating an Awesome list with new entries
• Submitting an Awesome list to the official awesome repository
• Reviewing Awesome list pull requests

---

Quick Start: Create Your Awesome List in 5 Minutes

Follow these steps to create a compliant Awesome list:

Step 1: Set Up Your Repository (1 minute)

Repository name: awesome-topic (lowercase slug)

• ✅ awesome-rust-gui
• ✅ awesome-python-testing
• ❌ awesome-RustGUI
• ❌ AwesomePythonTesting

Required files:

awesome-topic/
├── README.md           # Your Awesome list
├── CONTRIBUTING.md     # Contribution guidelines
└── LICENSE             # CC0 license

Step 2: Create the Header (30 seconds)

# Awesome Topic

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

> Brief description of what this list covers.

Key points:

• Title case in heading: # Awesome Topic
• Badge on right side or next to title
• Succinct, objective description
• No marketing language

Step 3: Add Table of Contents (1 minute)

## Contents

- [Category One](#category-one)
- [Category Two](#category-two)
- [Category Three](#category-three)

Requirements:

• Named "Contents" (not "Table of Contents")
• First section in README
• One level deep (no nested bullets)
• Exclude "Contributing" and "Footnotes"

Step 4: Add Your Entries (2 minutes)

## Category One

- [Project Name](https://github.com/user/project#readme) - Objective description.
- [Another Project](https://github.com/user/another#readme) - What it does.

Critical rules:

• All GitHub links end with #readme
• Descriptions start with uppercase
• Descriptions end with period
• No marketing words ("best", "amazing")
• Describe what it is, not how great it is

Step 5: Finalize (1 minute)

Add at the bottom:

## Contributing

Please see [contributing.md](contributing.md)

Create CONTRIBUTING.md and LICENSE files using the templates in templates/.

---

Awesome List Structure

Required Elements

Every Awesome list MUST include:

1. Awesome Badge

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

• Placed on right side of heading or centered at top
• Links to https://awesome.re
• Use the flat version if preferred: badge-flat.svg

2. Succinct Description

A brief, objective description at the top:

✅ Good:

> Mobile operating system for Apple phones and tablets.
> Prototyping interactive UI designs.

❌ Bad:

> Resources and tools for iOS development.
> The best collection of awesome Framer packages.

3. Table of Contents

• Named exactly "Contents"
• First section after description
• Links to all major categories
• Excludes "Contributing" and "Footnotes"
• Preferably one level deep

4. Categorized Entries

Organize entries into logical categories:

## Networking

- [Alamofire](https://github.com/Alamofire/Alamofire#readme) - Elegant HTTP networking in Swift.

## UI Components

- [SnapKit](https://github.com/SnapKit/SnapKit#readme) - A Swift Autolayout DSL.

5. Contributing Section

## Contributing

Please see [contributing.md](contributing.md)

• Links to separate CONTRIBUTING.md file
• Placed at top or bottom of content
• NOT in Table of Contents

6. LICENSE File

• Must use Creative Commons license (CC0 recommended)
• Code licenses (MIT, Apache, GPL) are NOT acceptable
• File named LICENSE or license in repo root
• Do NOT include license text in README

Optional Elements

Project Logo

> Description

<img src="logo.png" alt="Logo" width="400">

## Contents

• High-DPI image (max half original width)
• Links to project website
• Centered or right-aligned

Footnotes Section

## Footnotes

- Some entries may be archived but historically significant.
- Last updated: January 2025

• For ancillary information
• NOT in Table of Contents
• Placed at very bottom

---

Entry Quality Guidelines

Curation Principles

Core Philosophy: Awesome lists are curations of the best, not collections of everything.

Only Include Awesome Items

✅ Include:

• Projects you personally recommend
• Well-maintained, active projects
• Projects with clear documentation
• High-quality resources

❌ Exclude:

• Unmaintained or archived repos
• Projects without documentation
• Deprecated tools
• Everything you can find (be selective!)

Objective Descriptions

Describe what the project is, not how great it is:

✅ Good:

- [RxSwift](https://github.com/ReactiveX/RxSwift#readme) - Reactive programming in Swift.
- [Alamofire](https://github.com/Alamofire/Alamofire#readme) - Elegant HTTP networking.

❌ Bad:

- [RxSwift](https://github.com/ReactiveX/RxSwift#readme) - The best reactive programming library.
- [Alamofire](https://github.com/Alamofire/Alamofire#readme) - An amazing networking framework.

Entry Format

Standard format for all entries:

- [Project Name](https://github.com/user/project#readme) - Description ends with period.

Rules:

• Link text = project name (title case)
• GitHub URLs end with #readme
• Description starts with uppercase
• Description ends with period
• Separate link and description with dash
• One space on each side of dash

Consistent Naming

Use correct, consistent names:

• ✅ Node.js, ❌ NodeJS, ❌ node.js
• ✅ iOS, ❌ ios, ❌ IOS
• ✅ Swift, ❌ swift
• ✅ macOS, ❌ MacOS, ❌ Mac OS

---

Advanced Features

Progressive Disclosure

For detailed templates, examples, and official guidelines, see:

Templates:

• templates/awesome-readme-template.md - Base README structure
• templates/contributing-template.md - CONTRIBUTING.md template
• templates/license-template.txt - Full CC0 license text

References:

• references/awesome-manifesto.md - Official Awesome manifesto and philosophy
• references/awesome-guidelines.md - Complete submission requirements
• references/examples.md - Annotated examples from popular lists

Validation

Before submitting your list:

1. Run awesome-lint:

   npx awesome-lint

2. Check requirements:

• [ ] Repo name: awesome-topic (lowercase)
• [ ] Title: # Awesome Topic (title case)
• [ ] Awesome badge present
• [ ] Table of Contents named "Contents"
• [ ] All entries end with periods
• [ ] All GitHub links include #readme
• [ ] LICENSE file (CC0)
• [ ] CONTRIBUTING.md exists
• [ ] No marketing language
• [ ] No CI badges
• [ ] No hard-wrapping

3. Age requirement: List must be 30+ days old before submission

Common Pitfalls

Avoid these frequent mistakes:

❌ Marketing Language

- The best library for X
- An amazing tool
- Revolutionary framework

Use objective descriptions instead.

❌ Missing #readme

- [Project](https://github.com/user/project) - Description.

Include #readme in GitHub URLs.

❌ Wrong License

MIT License

Use CC0 or Creative Commons, not code licenses.

❌ Self-Referential

> Resources and tools for X development

Describe the topic itself, not the list.

❌ CI Badges

[![CI](https://github.com/user/workflow/badge.svg)](https://github.com/user/actions)

Don't include CI badges in Awesome lists.

❌ Hard-Wrapping

- [Project](https://github.com/user/project#readme) - This is a
  description that wraps to the next line.

Let lines flow naturally without hard wraps.

---

Progressive Disclosure

Quick Reference

For rapid validation, use the Quick Start section above.

Detailed Guidance

For comprehensive information, consult:

Templates:

• templates/awesome-readme-template.md - Full README template with structure
• templates/contributing-template.md - Complete CONTRIBUTING.md guide
• templates/license-template.txt - CC0 license full text

Reference Documentation:

• references/awesome-manifesto.md - Official Awesome manifesto
• references/awesome-guidelines.md - Complete PR submission guidelines
• references/examples.md - Annotated real-world examples

Official Resources

• Official Awesome Manifesto
• Create List Guide
• awesome.re - Official Awesome hub

---

Best Practices Summary

Content Quality

• Curate, don't collect
• Only include items you recommend
• Research before adding
• Remove unmaintained projects

Writing Style

• Be objective, not promotional
• Use consistent formatting
• Check spelling and grammar
• Keep descriptions concise

Technical Standards

• Use CC0 license
• Include CONTRIBUTING.md
• Add Awesome badge
• Name repo correctly
• Run awesome-lint

Community

• Accept constructive feedback
• Respect other opinions
• Review other PRs
• Contribute back

---

Remember: Awesome lists are curations of the best resources. Quality over quantity. When in doubt, leave it out.

Awesome List Submission Guidelines

Source: https://github.com/sindresorhus/awesome/blob/main/pull_request_template.md

Requirements for Your Pull Request

• Don't open a Draft / WIP pull request while you work on the guidelines. A pull request should be 100% ready and should adhere to all the guidelines when you open it.
• You have to review at least 2 other open pull requests. Try to prioritize unreviewed PRs. Just commenting "looks good" or simply marking the pull request as approved does not count. You have to actually point out mistakes or improvement suggestions.
• You have read and understood the instructions for creating a list.
• This pull request has a title in the format Add Name of List. It should not contain the word Awesome.
• ✅ Add Swift
• ✅ Add Software Architecture
• ❌ Update readme.md
• ❌ Add Awesome Swift
• Your entry here should include a short description of the project/theme of the list. It should not describe the list itself. The first character should be uppercase and the description should end in a dot. It should be an objective description and not a tagline or marketing blurb.
• ✅ - [iOS](…) - Mobile operating system for Apple phones and tablets.
• ✅ - [Framer](…) - Prototyping interactive UI designs.
• ❌ - [iOS](…) - Resources and tools for iOS development.
• ❌ - [Framer](…) - prototyping interactive UI designs (no period)
• Your entry should be added at the bottom of the appropriate category.
• The title of your entry should be title-cased and the URL to your list should end in #readme.
• Example: - [Software Architecture](https://github.com/simskij/awesome-software-architecture#readme) - The discipline of designing and building software.
• No blockchain-related lists.
• The suggested Awesome list complies with the below requirements.

Requirements for Your Awesome List

Age Requirement

Has been around for at least 30 days. That means 30 days from either the first real commit or when it was open-sourced. Whatever is most recent.

Quality Standards

• Run awesome-lint on your list and fix the reported issues.
• The default branch should be named main, not master.
• Includes a succinct description of the project/theme at the top of the readme.
• ✅ Mobile operating system for Apple phones and tablets.
• ✅ Prototyping interactive UI designs.
• ❌ Resources and tools for iOS development.
• ❌ Awesome Framer packages and tools.
• It's the result of hard work and the best you could possibly produce. If you have not put in considerable effort into your list, your pull request will be immediately closed.

Naming Conventions

• Repository: The repo name should be in lowercase slug format: awesome-name-of-list.
• ✅ awesome-swift
• ✅ awesome-web-typography
• ❌ awesome-Swift
• ❌ AwesomeWebTypography

• Heading: The heading title should be in title case format: # Awesome Name of List.
• ✅ # Awesome Swift
• ✅ # Awesome Web Typography
• ❌ # awesome-swift
• ❌ # AwesomeSwift

Repository Requirements

• Non-generated Markdown file in a GitHub repo.
• The repo should have awesome-list & awesome as GitHub topics. Add more relevant topics.
• Not a duplicate. Please search for existing submissions.
• Only has awesome items. Awesome lists are curations of the best, not everything.
• Does not contain items that are unmaintained, has archived repo, deprecated, or missing docs. If you really need to include such items, they should be in a separate Markdown file.

Visual Requirements

• Includes a project logo/illustration whenever possible.
• Either centered, fullwidth, or placed at the top-right of the readme.
• The image should link to the project website or any relevant website.
• The image should be high-DPI. Set it to a maximum of half the width of the original image.
• Don't include both a title saying Awesome X and a logo with Awesome X. You can put the header image in a # (Markdown header) or <h1>.

• Includes the Awesome badge.
• Should be placed on the right side of the readme heading.
• Can be placed centered if the list has a centered graphics header.
• Should link back to this list: https://awesome.re

Entry Requirements

• Entries have a description, unless the title is descriptive enough by itself.
• Descriptions are objective, not marketing copy.
• All entries end with periods.

Table of Contents

• Has a Table of Contents section.
• Should be named Contents, not Table of Contents.
• Should be the first section in the list.
• Should only have one level of nested lists, preferably none.
• Must not feature `Contributing` or `Footnotes` sections.

License Requirements

• Has an appropriate license.
• We strongly recommend the CC0 license, but any Creative Commons license will work.
• A code license like MIT, BSD, Apache, GPL, etc, is not acceptable. Neither are WTFPL and Unlicense.
• Place a file named license or LICENSE in the repo root with the license text.
• Do not add the license name, text, or a License section to the readme.

Contributing Guidelines

• Has contribution guidelines.
• The file should be named contributing.md. The casing is up to you.
• It can optionally be linked from the readme in a dedicated section titled Contributing, positioned at the top or bottom of the main content.
• The section should not appear in the Table of Contents.

Footnotes Section

• All non-important but necessary content (like extra copyright notices, hyperlinks to sources, pointers to expansive content, etc) should be grouped in a Footnotes section at the bottom of the readme.
• The section should not be present in the Table of Contents.

Formatting Standards

• Has consistent formatting and proper spelling/grammar.
• The link and description are separated by a dash.

Example: - [AVA](…) - JavaScript test runner.

• The description starts with an uppercase character and ends with a period.
• Consistent and correct naming. For example, Node.js, not NodeJS or node.js.
• Does not use hard-wrapping.
• Does not include a CI (e.g. GitHub Actions) badge. You can still use a CI for linting, but the badge has no value in the readme.
• Does not include an `Inspired by awesome-foo` or `Inspired by the Awesome project` link at the top of the readme. The Awesome badge is enough.

The Awesome Manifesto

Source: https://github.com/sindresorhus/awesome/blob/main/awesome.md

Core Philosophy

If you want your list to be included on awesome, try to only include actual awesome stuff in your list. After all, it's a curation, not a collection.

What is Awesome?

Only Awesome is Awesome

Research if the stuff you're including is actually awesome. Only put stuff on the list that you or another contributor can personally recommend. You should rather leave stuff out than include too much.

Awesome Badge

This badge is for Awesome lists.

Add an awesome badge to the top of your list, right next to the title. Example. You can choose either the regular badge or the flat one.

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

You are allowed to use the badge on lists not included here and also on private lists.

Important: The badges should not be modified in any way.

Content Guidelines

Comment on Why Something is Awesome

Apart from suggesting a particular item on your list, you should also inform your readers _why_ it's on the list and how they will benefit from it.

Make it Clear What the List is About

Have a succinct description at the top of your readme. Make sure your list covers a certain scope and nothing else. Link to other awesome lists if you think they already cover a certain subject well enough.

Pay Attention to Grammar

Ensure your list is grammatically correct, typo-free and has no Markdown formatting errors. This should also apply to pull requests.

Licensing

Choose an Appropriate License

Keep in mind that if you haven't selected a license, it basically means the people are _not_ allowed to reproduce, distribute or create derivative works.

Creative Commons licenses are perfect for this purpose. We would recommend `CC0`. Code licenses like MIT, BSD, GPL, and so forth are not recommended.

Contributing

Include Contribution Guidelines

People who are contributing to your list should have a clear understanding of how they should do so.

If you don't feel like writing one from scratch, feel free to take our contributing.md and modify it to your own needs.

Formatting

Stylize Your List Properly

Create a table of contents, organize the content into different categories, and use images if suitable. Ensure all entries are consistent (e.g. all entry descriptions end in a .).

Community

Accept Other People's Opinion

If you're an owner of the list, respect other people's opinions. If there are plenty of users not agreeing with your decision, give it a second thought.

Awesome List Examples

This document provides annotated examples from real Awesome lists to illustrate best practices.

Example 1: Proper Header and Badge Placement

Source: awesome-ios

# Awesome iOS

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

> A curated list of awesome iOS ecosystem, including Objective-C and Swift Projects

Key Points:

• Title is title case: # Awesome iOS
• Badge is on the right side of the heading
• Badge links to https://awesome.re
• Succinct, objective description of what the list covers

Example 2: Proper Entry Format

Good Examples:

- [Alamofire](https://github.com/Alamofire/Alamofire#readme) - Elegant HTTP Networking in Swift.
- [SwiftyJSON](https://github.com/SwiftyJSON/SwiftyJSON#readme) - The better way to deal with JSON data in Swift.
- [Kingfisher](https://github.com/onevcat/Kingfisher#readme) - A lightweight and pure Swift implemented library for downloading and caching images.

Key Points:

• All GitHub links end with #readme
• Descriptions start with uppercase
• All descriptions end with periods
• Objective descriptions (no "best", "amazing")
• Clear explanations of what the project does

Bad Examples:

❌ - [Alamofire](https://github.com/Alamofire/Alamofire) - best networking library
❌ - [SwiftyJSON](https://github.com/SwiftyJSON/SwiftyJSON#readme) - The best JSON handler
❌ - [Kingfisher](https://github.com/onevcat/Kingfisher#readme) - An amazing image library

Problems:

• Missing #readme in first example
• Marketing language: "best", "amazing"
• Missing period in first example
• Vague descriptions

Example 3: Table of Contents

Source: awesome-python

## Contents

- [Administration](#administration)
- [Asset Management](#asset-management)
- [Audio](#audio)
- [Authentication](#authentication)
- [Build Tools](#build-tools)
- [Caching](#caching)
- [ChatOps](#chatops)

Key Points:

• Section is named "Contents" (not "Table of Contents")
• Links are anchor links to section headers
• Typically one level (no nested bullets)
• First section in the README
• Excludes "Contributing" and "Footnotes"

Example 4: Category Organization

Source: awesome-swift

## Libraries

- [Alamofire](https://github.com/Alamofire/Alamofire#readme) - Elegant HTTP Networking.
- [Moya](https://github.com/Moya/Moya#readme) - Network abstraction layer.

## Tools

- [SwiftLint](https://github.com/realm/SwiftLint#readme) - A tool to enforce Swift style.
- [SwiftFormat](https://github.com/nicklockwood/SwiftFormat#readme) - Code formatting.

Key Points:

• Clear category names (title case)
• Related items grouped together
• Logical organization
• Consistent formatting within categories

Example 5: Description Styles

Project Type:

- [SnapKit](https://github.com/SnapKit/SnapKit#readme) - A Swift Autolayout DSL.

Library Type:

- [RxSwift](https://github.com/ReactiveX/RxSwift#readme) - Reactive Programming in Swift.

Tool Type:

- [SwiftGen](https://github.com/SwiftGen/SwiftGen#readme) - A code generator for assets.

Framework Type:

- [Vapor](https://github.com/vapor/vapor#readme) - A server-side Swift web framework.

Key Points:

• Noun-based descriptions
• Clear about project type
• Concise but informative
• Avoid "tool for X" pattern when possible

Example 6: Contributing Section

## Contributing

Please see [contributing.md](contributing.md)

Key Points:

• Links to separate contributing.md file
• Brief and to the point
• Placed at top or bottom of main content
• NOT included in Table of Contents

Example 7: Footnotes Section

## Footnotes

- The list is a curated selection of projects.
- Some entries may be archived but historically significant.

Key Points:

• Contains ancillary information
• NOT included in Table of Contents
• Placed at very bottom of README
• Used for non-essential but necessary information

Example 8: Repository Structure

awesome-topic/
├── README.md           # Main list
├── CONTRIBUTING.md     # Contribution guidelines
├── LICENSE             # CC0 license file
└── logo.png            # Optional project logo

Key Points:

• Simple structure
• LICENSE file in root (not LICENSE.md)
• Separate CONTRIBUTING.md
• Optional logo in root

Common Patterns to Follow

Badge Placement

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

OR

# Awesome Topic

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

Description Format

> Brief, objective description of what this list covers.

Entry Template

- [Project Name](https://github.com/user/project#readme) - What it does in one sentence.

Category Template

## Category Name

- [Project](https://github.com/user/project#readme) - Description.
- [Another Project](https://github.com/user/another#readme) - Description.

Anti-Patterns to Avoid

❌ Marketing Language

- Best framework for X
- Amazing library
- Revolutionary tool
- The ultimate solution

❌ Self-Referential

- Resources for X development
- Tools to help with X
- Collection of X projects

❌ Vague Descriptions

- A tool for X
- A library for X
- Something that does X

❌ Inconsistent Formatting

- [Project](https://github.com/user/project) - Description (no period)
- [Another Project](https://github.com/user/another#readme) - description (lowercase)
- [Third Project](https://github.com/user/third#readme) Description (no dash)

Quick Reference Checklist

For each entry, verify:

• [ ] GitHub link includes #readme
• [ ] Description ends with period
• [ ] Description starts with uppercase
• [ ] No marketing language
• [ ] Clear what the project does
• [ ] Active maintenance

For the overall list:

• [ ] Awesome badge present
• [ ] Title is title case
• [ ] Succinct description at top
• [ ] Contents section (named "Contents")
• [ ] CONTRIBUTING.md exists
• [ ] LICENSE file (CC0)
• [ ] No hard-wrapping
• [ ] Consistent formatting

Awesome {{TOPIC}}


{{DESCRIPTION}}

{{#if LOGO_URL}} <img src="{{LOGO_URL}}" alt="{{TOPIC}} logo" width="400"> {{/if}}

Contents

• {{CATEGORY_1}}
• {{CATEGORY_2}}
• {{CATEGORY_3}}

{{#if HAS_MORE_CATEGORIES}}

• {{CATEGORY_4}}

{{/if}}

{{#if SHOW_CONTRIBUTING_LINK}}

Contributing

Please see contributing.md {{/if}}

{{CATEGORY_1}}

• Project Name - Description of what makes this project awesome.
• Another Project - Clear, objective description that ends with a period.

{{CATEGORY_2}}

• Library Name - Short description explaining the purpose and key features.

{{CATEGORY_3}}

• Tool Name - Description.

{{#if HAS_FOOTNOTES}}

Footnotes

{{FOOTNOTES_CONTENT}} {{/if}}

{{#if SHOW_CONTRIBUTING_LINK_BOTTOM}}

Contributing

Please see contributing.md {{/if}}

{{#if SHOW_LICENSE_SECTION}}

License

CC0 {{/if}}

Contributing

Contributions are welcome! Please follow these guidelines when submitting pull requests.

Adding Items

• Only add items that you personally recommend or have thoroughly researched.
• Ensure all entries are objectively described without marketing language.
• Follow the existing format: - [Project Name](https://github.com/user/project#readme) - Description.
• All descriptions must end with a period.
• Add new entries to the bottom of the appropriate category.

Requirements

• Entries must be actively maintained.
• Projects must have documentation.
• No archived, deprecated, or unmaintained projects.
• Repositories must be public.

Formatting

• Use title case for project names.
• Include #readme at the end of GitHub links.
• Start descriptions with uppercase letters.
• Keep descriptions concise but informative.
• Avoid superlatives like "best", "amazing", "revolutionary".

Pull Request Process

1. Check if your contribution duplicates existing entries. 2. Ensure your entry follows the formatting guidelines. 3. Test that all links work correctly. 4. Submit a pull request with a clear title describing the change.

Style Guidelines

• Be objective: Describe what the project does, not how great it is.
• Be specific: "A CLI tool for X" is better than "A great tool".
• Be concise: One sentence per entry is usually sufficient.
• Be accurate: Verify claims about features and capabilities.

Thank you for contributing!