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) ```markdown # Awesome Topic [](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) ```markdown ## 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) ```markdown ## 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: ```markdown ## 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 ```markdown [](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: ```markdown > Mobile operating system for Apple phones and tablets. > Prototyping interactive UI designs. ``` ❌ Bad: ```markdown > 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: ```markdown ## 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 ```markdown ## 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 ```markdown > 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 ```markdown ## 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: ```markdown - [RxSwift](https://github.com/ReactiveX/RxSwift#readme) - Reactive programming in Swift. - [Alamofire](https://github.com/Alamofire/Alamofire#readme) - Elegant HTTP networking. ``` ❌ Bad: ```markdown - [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: ```markdown - [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:** ```bash 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** ```markdown - The best library for X - An amazing tool - Revolutionary framework ``` Use objective descriptions instead. ❌ **Missing #readme** ```markdown - [Project](https://github.com/user/project) - Description. ``` Include `#readme` in GitHub URLs. ❌ **Wrong License** ```markdown MIT License ``` Use CC0 or Creative Commons, not code licenses. ❌ **Self-Referential** ```markdown > Resources and tools for X development ``` Describe the topic itself, not the list. ❌ **CI Badges** ```markdown [](https://github.com/user/actions) ``` Don't include CI badges in Awesome lists. ❌ **Hard-Wrapping** ```markdown - [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](https://github.com/sindresorhus/awesome/blob/main/awesome.md) - [Create List Guide](https://github.com/sindresorhus/awesome/blob/main/create-list.md) - [awesome.re](https://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.