Awesome 清单宣言解读：遵循 awesome 社区标准打造高质量精选资源列表的完整指南

导读：Awesome 是 GitHub 上最知名的精选资源列表集合，而 awesome.md 正是定义「什么才算真正的 Awesome 清单」的官方宣言。本文将以该宣言为主体，结合仓库中的 create-list.md、contributing.md、pull_request_template.md 等配套文档，系统讲解清单入选门槛、Awesome 徽章与 Mentioned 徽章的正确用法、许可证选择、贡献指南等规范，读完即可掌握创建并提交一份符合社区标准的高质量 Awesome 清单的完整方法。

一、宣言在仓库中的定位

本仓库以 readme.md 为总入口，其页眉以 What is an awesome list? 链接到 awesome.md，即本文所依据的核心文档；同时以 Contribution guide、Creating a list 分别链接到 contributing.md 与 create-list.md。可见该仓库的分工是：

• awesome.md（宣言）：定义「Awesome 清单」的价值观与质量底线，是评审清单的哲学依据；
• pull_request_template.md（清单指南）：将宣言落到可勾选的硬性条目，是提交新清单前的检查清单；
• create-list.md（建清单）：给出从创建到提交流程的四步操作指引；
• contributing.md（贡献指南）：面向向已有清单添加条目的人。

宣言开篇就点明了核心立场："It's a curation, not a collection"（这是策展，不是收集）。也就是说，Awesome 清单的价值在于筛选，而非堆砌。

二、核心准则：Only awesome is awesome

宣言第一条准则强调：只有真正 Awesome 的东西才配进入清单。具体要求是：

• 纳入清单前先做调研（Research），确认条目确实够得上「Awesome」；
• 只有你本人或另一位贡献者可以亲自背书推荐的条目才有资格入选；
• 宁可少收录，也不要滥竽充数（"You should rather leave stuff out than include too much"）。

这一准则在 pull_request_template.md 中被固化为硬性条款：「Only has awesome items. Awesome lists are curations of the best, not everything.」且明确要求清单不得包含已停止维护、已归档、已废弃或缺少文档的条目，若确有需要，应单独放入另一个 Markdown 文件而非主清单。同时，仓库当前也明确「Fully AI-generated pull requests are not accepted」（不接受完全由 AI 生成的清单提交），目的是确保每条内容都有真实的人工判断与维护。

三、Awesome 徽章（Awesome badge）：清单的官方身份标识

宣言规定，Awesome 徽章是专属于 Awesome 清单的标识，应放置在清单标题右侧（若清单采用居中图形页眉，则可居中放置），并链接回本仓库。仓库 media 目录下即存放了徽章的源文件与设计规范，包括 media/badge.svg、media/badge-flat.svg、media/badge-flat2.svg 及设计源文件 media/badge.ai；配色等规范记录在 media/readme.md（主色 #fc60a8、辅色 #494368、字体 Orbitron）。

在清单 readme 顶部添加徽章的标准 Markdown 写法如下（常规版与扁平版任选其一）：

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

使用徽章的两个边界条件必须牢记：

1. 允许范围广：不仅收录于 Awesome 的清单可以用，未被收录的清单、甚至私有清单也允许使用；
2. 不可修改：The badges should not be modified in any way. ——徽章不得以任何方式被改动（例如改配色、换文字）。相应的禁止行为也体现在清单指南中：清单 readme 顶部不得再添加 "Inspired by awesome-foo" 之类的致敬链接，因为「Awesome 徽章已经足够说明一切」。

四、Mentioned in Awesome 徽章：给被收录项目的荣誉标识

与清单徽章不同，Mentioned 徽章是面向「被 Awesome 清单收录的项目」设计的（而非清单本身）。宣言给出的经典例子是 Chalk 项目——因为它被 Awesome Node.js 收录，所以可以在自己的仓库里挂这枚徽章。这枚徽章对项目而言完全自愿（totally optional），却是展示「本作品已被 Awesome 社区收录」的体面方式。仓库中对应的素材为 media/mentioned-badge.svg 与 media/mentioned-badge-flat.svg，以及设计源文件 media/mentioned-badge.sketch。

使用时需要手动填充两个占位符：清单名称（INSERT LIST NAME）与清单地址（INSERT LIST URL）：

[![Mentioned in Awesome <INSERT LIST NAME>](https://awesome.re/mentioned-badge.svg)](https://github.com/<INSERT LIST URL>)
[![Mentioned in Awesome <INSERT LIST NAME>](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/<INSERT LIST URL>)

填充后的示例：

[![Mentioned in Awesome Node.js](https://awesome.re/mentioned-badge.svg)](https://github.com/sindresorhus/awesome-nodejs)

同样地，徽章不得以任何方式修改。宣言还建议：作为清单维护者，可以主动鼓励清单中的项目挂上这枚徽章，形成生态内的互认。

五、逐条说明「为什么 Awesome」：评论而非罗列

宣言要求：除了给出条目链接，还必须告诉读者它为什么值得上榜、读者能从中获得什么（why it's on the list and how they will benefit from it）。换句话说，每条条目都是一条「带论据的推荐」，而不是一个孤立链接。

这一要求在 pull_request_template.md 中被细化成可验证的格式规则，例如：

• 条目格式为 - 名称 - 描述，链接与描述之间以连字符分隔；
• 描述首字母大写、以句号结尾，例如 - iOS - Mobile operating system for Apple phones and tablets.；
• 描述应当是对主题的客观陈述，不得是营销口号、不得是"Resources and tools for iOS development"这类描述清单自身的说法、也不得包含清单名称本身；
• 标题采用 Title Case（如 Awesome Swift），URL 以 #readme 结尾。

六、明确清单主题：范围清楚，宁缺毋滥

宣言要求清单「Make it clear what the list is about」：readme 顶部要有简洁的清单描述，清单必须只覆盖某一确定范围（covers a certain scope and nothing else）；如果某一主题已有其他 Awesome 清单覆盖得很好，应直接链接到那张清单，而不是另起炉灶做重复工作。

仓库 readme.md 本身就是最佳范例：它按 Platforms（平台）、Programming Languages（编程语言）、Front-End Development、Back-End Development、Computer Science、Big Data、Databases、Security 等 26 个分类组织，并在条目后附带一句话客观描述。而 create-list.md 则给出对应操作指引：创建新清单前先搜索本仓库，若发现已有同类清单，优先去贡献最优秀的那一张，而不是再造一张重复的。与此同时，pull_request_template.md 也把「Not a duplicate」列为硬性勾选项，并建议用 awesome-list、awesome 作为仓库 GitHub topics 便于检索。

七、语法与格式：对细节零容忍

宣言明确要求清单做到：

• 语法正确、无拼写错误、无 Markdown 格式错误；
• 以上标准同样适用于提交的 Pull Request；
• 命名保持一致且正确（例如写 Node.js，而不是 NodeJS 或 node.js）。

pull_request_template.md 进一步补充了可操作细节：描述以大写开头、以句号结尾；条目间格式统一（所有条目描述都以 . 结尾）；不使用 hard-wrapping 硬换行；readme 中不得添加 CI 徽章（如 GitHub Actions 徽章，CI 仅可用于内部 lint）；并强调合并前的审查者对格式问题有义务指出。

八、选择许可证：强烈推荐 CC0

宣言给出了明确的许可证策略：若仓库不选许可证，法律上等于禁止他人复制、分发与二次创作；因此必须显式选择许可证。对 Awesome 清单而言：

• Creative Commons 系列许可证是首选，其中官方强烈推荐 CC0（公有领域贡献，见仓库根目录的 license 全文，其声明允许任何人不受限制地复制、修改、再分发，包括商业用途）；
• MIT、BSD、GPL 等代码许可证不被推荐，因为它们面向代码而非内容。

pull_request_template.md 将这一条细化到操作层面：许可证文件应命名为 license 或 LICENSE 置于仓库根目录；不要在 readme 中再加许可证名称、文本或 Licence 小节（GitHub 会在仓库页自动展示）；WTFPL 与 Unlicense 同样不被接受。该清单指南还提示，可通过 https://github.com/<user>/<repo>/community/license/new?branch=main&template=cc0-1.0 一键为仓库添加 CC0 模板。

九、提供贡献指南：让协作有章可循

宣言要求每个清单都让贡献者清楚明白该如何贡献；若不想从零撰写，可以直接基于本仓库的 contributing.md 修改使用。配套硬性规则（来自 pull_request_template.md）包括：

• 贡献指南文件应命名为 contributing.md（大小写不限）；
• 可在 readme 中设 Contributing 小节（置于内容顶部或底部）链接它，但该小节不得出现在目录（Contents）中；
• 其他非核心但必要的内容（版权声明、来源链接、扩展内容指针等）应统一收进 readme 底部的 Footnotes 小节，同样不进目录。

十、清单排版：目录、分类与一致性

宣言给出的排版三要素：

1. 创建目录（Table of Contents）——本仓库 readme.md 的 ## Contents 即是模板；
2. 按类别组织内容——同一主题下的子清单用缩进嵌套表示（如 Node.js 下嵌套 Cross-Platform）；
3. 合适时使用图片——如项目 logo 或插图。

pull_request_template.md 对这些要求做了非常具体的量化：目录应命名为 Contents 而非 Table of Contents，必须是清单的第一个章节，嵌套层级尽量为一层或不要嵌套，且不得包含 Contributing 或 Footnotes 小节；条目追加到对应分类的底部。关于图片：清单应尽量包含项目 logo/插图，图片居中、通栏或置于 readme 右上角，使用高 DPI 图片（宽度不超过原图一半），且不要在标题和 logo 中重复出现 "Awesome X"（可将页眉图放进 # 或 <h1> 中）。

十一、尊重他人意见：维护者的开放心态

宣言最后一条准则指向清单所有者：要尊重其他贡献者的意见；当大量用户不认可你的某项决策时，应当重新思考（give it a second thought）。结合 contributing.md 与 code-of-conduct.md（本仓库以 Contributor Covenant 1.4 为行为准则），整个生态的运行逻辑是：筛选标准由宣言定义，协作氛围由行为准则保障，维护者决策接受社区反馈，从而让策展质量在开放讨论中持续提升。

十二、从宣言到落地：创建并提交清单的完整流程

将宣言落到行动，create-list.md 给出了四步法：

1. 阅读 awesome.md 宣言与 pull_request_template.md 清单指南，确保清单合规；
2. 先在本仓库搜索，避免创建重复清单；若已存在，去为最佳的那张贡献；
3. 创建清单后至少等待 30 天再提交，给清单留出成熟（mature）的时间——对应 pull_request_template.md 中「Has been around for at least 30 days」的硬性条件（从首个真实 commit 或开源之日起算）；
4. 提交 Pull Request 前再次通读清单指南。

提交时的关键要求还包括：PR 标题格式为 Add Name of List（不得含 "Awesome" 字样，如 Add Swift ✅、Add Awesome Swift ❌）；提交者需至少评审 4 个其他开放的 PR（且须给出实质性的改进意见，"looks good" 之类的空评论不算）；清单需通过 awesome-lint 检查并修复报告的问题；默认分支应命名为 main；最后在 PR 中留言 unicorn 以示已通读全部指南。

至此，从「什么才算 Awesome」的价值判断，到徽章、许可证、格式、贡献与提交流程的每个细节，宣言与其配套文档共同构成了一套可执行、可校验、可复用的完整规范——这正是全球数千张 Awesome 清单得以长期保持高质量的根本原因。

延伸阅读：继续查阅本仓库内的 readme.md（清单分类总索引）、pull_request_template.md（提交自检清单全文）、contributing.md（向已有清单添加条目的 GitHub 操作步骤）与 code-of-conduct.md（社区行为准则），可进一步掌握从「建清单」到「维护清单」的完整生态流程。