• 文档
• 知识库

本文以 awesome 仓库官方文档 create-list.md 为主线，系统讲解"如何打造并提交一个能被官方收录的 Awesome 列表"：从阅读 Awesome 宣言 与 列表提交指南 起步，到查重、度过 30 天成熟期，再到逐条对照列表质量门槛与 Pull Request 提交规范。读完后，你将掌握一份可直接照做的创建清单，以及仓库源码层面的完整证据链，能够避开绝大多数新手踩过的坑，一次通过审核的概率大幅提升。

一、先建立正确认知：Awesome 列表是"策展"而非"收藏"

在动手之前，必须先理解 Awesome 生态的核心哲学。官方文档 awesome.md 开篇即点明：

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

这句话定义了整个审校体系的价值基准：列表是对"真正优秀"资源的策展（curation），而不是对一切资源的收藏（collection）。对应地，宣言第一条准则"Only awesome is awesome"要求：收录前先研究该项目是否真的出色，只放入你自己或他人能亲身推荐的条目，"宁可少收，不要滥收"（You should rather leave stuff out than include too much）。

这一认知直接决定了 create-list.md 中"确保你的列表合规"的前提——合规不是指格式，而是指内容经得起"是否真的 awesome"这一灵魂拷问。

二、创建前必读：两份决定成败的文档

create-list.md 给出的第一步是：

Read the Awesome manifesto and list guidelines and ensure your list complies.

即创建列表前必须先通读两份文档并保证自己的列表符合要求：

1. Awesome 宣言（awesome.md）：定义了"什么才算 awesome"的十条质量准则（详见本文第七节），包括徽章使用、内容描述、许可证选择、贡献指南、排版风格等；
2. 列表提交指南（pull_request_template.md）：既是提交 PR 时必须填写的模板，又是一份非常详尽的检查清单，分为"PR 的要求"与"列表的要求"两大块，其中列表要求部分逐条可达数十项。

注意，pull_request_template.md 开头有一句提醒：

Please read it multiple times. I spent a lot of time on these guidelines and most people miss a lot.

这并非客套——该模板中大量要求（如 PR 标题格式、unicorn验证词、评审他人 PR 的数量）都是新手最容易忽略的细节。因此 create-list.md 特意在最后一步再次强调：提交 PR 之前，请再读一遍列表指南（Make sure you read the list guidelines again before submitting a pull request）。

三、查重：避免重复造轮子

create-list.md 的第二个要求：

Search this list before making a new one, as yours may be a duplicate. If it is, try and contribute to the best one instead of making your own.

在创建新列表前，务必先在主列表中搜索是否已存在同类列表：

• 主列表 readme.md 按主题划分为 Platforms、Programming Languages、Front-End Development、Back-End Development、Computer Science、Big Data、Theory、Books、Editors、Gaming、Development Environment、Entertainment、Databases、Media、Learn、Security、Content Management Systems、Hardware、Business、Work、Networking、Decentralized Systems、Health and Social Science、Events、Testing、Miscellaneous、Related 等二十余个分类，覆盖面极广；
• 若发现已有列表覆盖你的主题，不要另起炉灶，而是应尽力为其中最好的那个做出贡献（contribute to the best one），这样既避免分裂社区，也符合"列表不重复"的收录底线（见 pull_request_template.md 的 "Not a duplicate. Please search for existing submissions."）。

四、30 天成熟期：为什么必须等待

create-list.md 中有一条加粗强调的硬性时间门槛：

Wait at least 30 days after creating a list before submitting it, to give it a chance to mature.

对应地，pull_request_template.md 对列表的要求中也明确写了判定口径：

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.

即：30 天从"第一次真实提交"或"开源发布"两者中较晚的时间点起算。这一机制的用意是给列表一个真实的生长周期——让内容在社区反馈中沉淀、去芜存菁，而不是发布当天就拿来投稿的"一次性产物"。提交时这一条会自动被审查，因此建议在创建仓库并完成首版内容后，为它预留至少一个月的持续维护期。

五、列表本身的硬性门槛：逐条对照自查

create-list.md 要求列表合规，而合规的完整定义就在 pull_request_template.md 的 "Requirements for your Awesome list" 一节。以下逐组拆解。

5.1 仓库形态与命名

• 不是 AI 生成的（Is not AI-generated）：列表必须是人工策展的产物，纯 AI 生成内容直接拒绝；
• 默认分支命名为main，而不是master；
• 仓库名必须是小写 slug 格式awesome-name-of-list：
  • 正确：awesome-swift、awesome-web-typography
  • 错误：awesome-Swift、AwesomeWebTypography
• 列表标题必须使用 title case，格式为# Awesome Name of List：
  • 正确：# Awesome Swift、# Awesome Web Typography
  • 错误：# awesome-swift、# AwesomeSwift
• 必须是 GitHub 仓库中一份非自动生成的 Markdown 文件；
• 仓库必须设置 GitHub topics，至少包含awesome-list与awesome两个主题，官方鼓励添加更多相关主题；
• 不是重复列表（见第三节）。

5.2 内容质量

• 只收录 awesome 条目：宣言中的 "Only awesome is awesome" 在此落地——"Awesome lists are curations of the best, not everything"；
• 不得包含未维护、已归档、已弃用或缺少文档的项目；若确实需要收录这类条目，必须单独放进另一个独立的 Markdown 文件，不能与精选内容混排；
• 每个条目都应带描述（除非标题本身就足够说明，但这种情况极少）：
  • 链接与描述之间用破折号（-）分隔，如- AVA - JavaScript test runner.
  • 描述以大写字母开头、以句号结尾；
  • 命名保持一致与正确，例如统一写Node.js，而不是NodeJS或node.js。

5.3 结构与格式

• README 顶部必须有一句简洁的主题描述（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.
• 尽量包含项目 Logo 或插画，条件包括：居中、通栏或置于 README 右上角；图片应链接到项目网站；必须是高 DPI 图片（设置为原图宽度的一半以内）；不要既在标题写Awesome X又在 Logo 里出现Awesome X；
• 必须包含 Awesome 徽章（详见第七节）：置于 README 标题的右侧；若列表采用居中图文头部，也可居中放置；徽章应链接回本列表；
• 必须有目录（Table of Contents），且：
  • 命名为Contents，而不是Table of Contents；
  • 必须是列表的第一个章节；
  • 嵌套列表最多一层，最好没有嵌套；
  • 目录中不得出现Contributing或Footnotes条目；
• 非重点但必要的内容（额外版权声明、来源链接、扩展内容入口等）应统一归入 README 底部的Footnotes章节，同样不得出现在目录中；
• 不使用硬换行（hard-wrapping）；
• 不添加 CI（如 GitHub Actions）徽章——可以用 CI 做 lint，但徽章对 README 没有价值；
• 不在 README 顶部添加Inspired by awesome-foo或Inspired by the Awesome project之类的链接，Awesome 徽章已经足够。

5.4 许可证与协作机制

• 许可证：pull_request_template.md 强烈推荐 CC0 协议，任何 Creative Commons 许可证均可；MIT、BSD、Apache、GPL 等代码许可证不可接受，WTFPL 与 Unlicense 同样不行；具体做法是在仓库根目录放置名为license或LICENSE的文件；不要把许可证名称、文本或Licence章节写进 README——GitHub 会在仓库顶部自动展示许可证信息；
• 贡献指南：列表必须有contributing.md（文件名大小写不限），可选地在 README 中用一个专门的Contributing章节链接它（置于正文顶部或底部），但该章节不得进入目录；
• 验证词unicorn：为确认你已经通读全部指南，官方要求在提交 PR 时于评论中只写一个词unicorn（这是模板中的硬性检查项，漏掉会直接暴露你没读文档）；
• 运行 awesome-lint：在提交前对自己的列表运行awesome-lint并修复其报告的所有问题；若存在误报或确实无法修复的项，应向工具仓库提交 issue 说明，而不是置之不理。

六、Pull Request 的提交规范

列表本身达标只是第一步，PR 的提交方式同样被严格审查。pull_request_template.md 的 "Requirements for your pull request" 一节规定了以下要点：

• 纯 AI 生成的 PR 不接受（Fully AI-generated pull requests are not accepted）；
• 不要以 Draft / WIP 状态提交 PR：PR 打开时必须 100% 完成并符合全部指南；需要孵化期可见性时，应利用官方的 incubation issue（编号 2242）来展示，而不是半成品 PR；
• 不要浪费维护者的时间：认真完成、遵守全部指南、对反馈保持响应；
• 必须至少评审 4 个其他开放的 PR（优先评审尚未被审过的 PR，也可以给已评审的 PR 补充意见），并在自己的 PR 中注明评审了哪些。评审必须认真：只评论 "looks good" 或仅标记为 approved 不算评审，必须真正指出错误或改进建议；指出 lint 违规的评论虽然允许，但也不计入评审次数。这一要求意在让 Awesome 项目自给自足（self-sustaining）；
• PR 标题格式必须为Add Name of List，且标题中不得包含Awesome一词：
  • 正确：Add Swift、Add Software Architecture
  • 错误：Update readme.md、Add Awesome Swift、add Swift、Adding Swift、Added Swift
• 主列表中的条目描述：写列表所覆盖的项目/主题的简短客观描述，不要描述列表本身，首字符大写、以句号结尾、不得含列表名：
  • 正确：- iOS - Mobile operating system for Apple phones and tablets.、- Framer - Prototyping interactive UI designs.
  • 错误：- iOS - Resources and tools for iOS development.、- Framer、- Framer - prototyping interactive UI designs
• 条目位置：添加到对应分类的底部；
• 标题与链接：条目名称使用 title case，URL 以#readme结尾，例如- [Software Architecture](https://github.com/simskij/awesome-software-architecture#readme) - The discipline of designing and building software.；
• 不接受区块链相关列表（No blockchain-related lists）。

七、Awesome 宣言的十条准则：逐条深度解读

awesome.md 中的十条准则构成了所有质量要求的思想源头，逐条展开如下。

7.1 Only awesome is awesome（只收录真正 awesome 的内容）

收录前先研究：该项目是否真的出色？只放入你能亲自推荐的条目。宁缺毋滥。

7.2 Awesome badge（Awesome 徽章）

徽章用于标识"这是一个 Awesome 列表"，应置于列表标题旁边。官方提供了三种样式（常规、扁平、扁平二号），用法如下：

[![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)

徽章允许用于未收录于此的项目，也允许用于私有列表；徽章不允许以任何方式修改（The badges should not be modified in any way.）。本仓库 media 目录中存放了对应的徽章资源文件（badge.svg、badge-flat.svg、badge-flat2.svg），可供参考其原始形态。

7.3 Awesome mentioned badge（被收录徽章）

该徽章供被收录进 Awesome 列表的项目使用（并非给列表本身使用）。例如某个项目因为出现在 Awesome Node.js 列表中，就可以在自身 README 中展示它。它是完全可选的，但能直观展示"本作品已被 Awesome 列表收录"：

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

使用时需填写占位符——列表名和列表 URL：

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

完整示例：

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

作为列表维护者，可以鼓励列表中的项目添加该徽章。本仓库 media 目录同样提供了这两种徽章的源文件（mentioned-badge.svg、mentioned-badge-flat.svg）。同样，徽章不得修改。

7.4 Comment on why something is awesome（解释为什么它 awesome）

除了列出条目，还要告诉读者它为什么值得上榜、读者能从中获得什么。主列表 readme.md 中大量条目都带一句描述，正是这一准则的体现。

7.5 Make it clear what the list is about（让列表主题清晰）

README 顶部要有简洁描述，列表必须覆盖明确的范围且不越界；如果某个主题已有列表覆盖得很好，就链接到那个列表而不是重复收录。

7.6 Pay attention to grammar（注意语法）

保证列表语法正确、零拼写错误、无 Markdown 格式错误——这条同样适用于提交的 PR。

7.7 Choose an appropriate license（选择合适的许可证）

若仓库没有选择许可证，实际上意味着他人不被允许复制、分发或创作衍生作品。Creative Commons 许可证非常适合此类内容列表，官方推荐 CC0；MIT、BSD、GPL 等代码许可证不推荐。这与第五节 5.4 中的硬性要求相互呼应。

7.8 Include contribution guidelines（包含贡献指南）

贡献者需要清楚知道如何为你的列表做贡献。如果不打算从零撰写，可以直接取用本仓库的 contributing.md 并按需修改——这也解释了为什么仓库会维护一份通用的贡献指南文件。

7.9 Stylize your list properly（规范排版）

创建目录（Table of Contents）、将内容按分类组织、合适时使用图片；保证所有条目风格一致（例如所有条目描述都以句号结尾）。

7.10 Accept other people's opinion（尊重他人意见）

作为列表所有者，要尊重他人的意见；当大量用户不同意你的决定时，应重新考虑。这是列表长期健康运营的协作准则。

八、网页端实操路径：如何一步步提交

contributing.md 给出了提交 PR 的完整网页操作流程，可作为投稿时的操作手册：

1. 打开目标 Awesome 列表的 GitHub 页面（例如本仓库主页）；
2. 点击readme.md文件；
3. 点击编辑图标，在浏览器内置编辑器中修改文本，遵循前述全部指南，可使用 GitHub Flavored Markdown；
4. 填写变更原因说明，点击 "Propose file change"；
5. 提交 Pull Request，并按照第六节要求填写标题与条目描述；
6. 如果维护者要求修改 PR（通常是拼写错误或不符合列表指南），参考官方提供的修改提交指南更新 PR 即可。

需要特别注意的是，本仓库同时附带 code-of-conduct.md（贡献者行为准则），contributing.md 明确声明参与该项目即表示同意遵守其条款——在投稿任何列表之前先阅读它，能避免在社区协作层面踩雷。

九、完整流程时间线

将以上全部内容收敛为一条可执行的时间线：

1. 读文档：通读 awesome.md 宣言与 pull_request_template.md 指南（多读几遍）；
2. 查重：在 readme.md 中搜索确认无同类列表；若有，改为贡献给最好的那个；
3. 创建列表：按第五节全部硬性门槛建设仓库（命名、标题、描述、目录、徽章、许可证、贡献指南、topics、main 分支）；
4. 持续打磨：运行awesome-lint并修复问题，用真实维护保证条目质量；
5. 等待 30 天：从第一次真实提交或开源发布（取较晚者）起算，让列表成熟；
6. 提交 PR 前复查：再次阅读列表指南；评审至少 4 个其他开放 PR（认真指出问题才算数）；按Add Name of List格式命名标题、在合适分类底部插入条目、描述首字母大写且以句号结尾、URL 以#readme结尾；评论中附上验证词unicorn；
7. 提交并保持响应：提交 PR 后对维护者的反馈及时响应、按需更新。

结语

创建并提交一个 Awesome 列表，本质上是一场"内容策展 + 工程规范"的双重考验：内容上要遵循 awesome.md 的"只有 awesome 才叫 awesome"，工程上要满足 pull_request_template.md 的每一项检查。本文以 create-list.md 为骨架，逐层展开了查重、30 天成熟期、列表硬性门槛、PR 提交规范与宣言十准则，并把仓库内的 contributing.md、code-of-conduct.md、readme.md 与 media 徽章资源全部串联起来——按这条路径走，你的列表才真正有资格被收录。Thanks for being awesome.

• 文档
• 知识库