如何在 free-programming-books 中编写符合格式规范的资源条目（顺序、空行与格式标注）？-二趣网

如何在 free-programming-books 中编写符合格式规范的资源条目（顺序、空行与格式标注）？

【免费下载链接】free-programming-books:books: Freely available programming books项目地址: https://gitcode.com/GitHub_Trending/fr/free-programming-books

如果你要向 free-programming-books 仓库贡献一个免费资源条目，最容易被打回的原因不是内容本身，而是格式：条目没有按字母顺序插入、空行数量不对、作者名或格式标注的写法不符合规范。docs/CONTRIBUTING.md 定义了完整的格式规则，且仓库的 CI（.github/workflows/fpb-lint.yml）会在每个 Pull Request 上运行 fpb-lint 测试，专门校验列表的字母顺序和格式规则。本文按“定位文件 → 写条目 → 处理空行 → 加标注 → 过自动化检查”的顺序说明如何写出能通过校验的条目。

先确定条目应该放进哪个文件

所有列表都是.md文件，按内容类型分目录存放。先按 docs/CONTRIBUTING.md 的“In a nutshell”一节判断类型，选对清单：

Books：PDF、HTML、ePub、gitbook.io 站点、Git 仓库等；
Courses：不是书的教材，例如 MIT OpenCourseWare 的课程页面；
Interactive Tutorials：可以输入代码或命令并即时求结果的交互式网站；
Playgrounds：在线或本地的写代码、运行、分享代码片段的工具；
Podcasts and Screencasts：播客与屏幕录像；
Problem Sets & Competitive Programming：通过解题来评估编程能力的网站或软件。

仓库中对应的目录分别为books/、courses/、more/（交互式教程、playground）、casts/、more/（竞赛题集）。列表文件内以语言区分，例如英文书目录在 books/free-programming-books-en.md。

选对文件后还要遵守两条内容前提：

只贡献免费内容，且不要提交需要工作邮箱才能获取书籍的链接（但允许提交“索要邮箱、但不强制”的条目）；
不接受 Google Drive、Dropbox、Mega、Scribd、Issuu 等文件托管平台的链接。

链接来源的选择规则在 docs/CONTRIBUTING.md 的 Guidelines 一节：

优先使用最权威来源的链接（作者官网 > 出版社官网 > 第三方网站）；
同域同内容时，https链接优先于http；
根域名去掉结尾斜杠：写http://example.com而不是http://example.com/；
永远选最短链接：http://example.com/dir/优于http://example.com/dir/index.html；
不用 URL 短链服务，不保留 tracking 参数；
证书过期/自签证书等 SSL 问题：能换http就换，换不了但https仍可访问就保留，否则删除该链接。

条目的基本结构与顺序

一个标准的资源条目由这几部分组成（以文档中的 GOOD 示例为骨架）：

* [Another Awesome Book](http://example.com/book.html) - John Doe (HTML)

标题是 Markdown 链接，]和(之间不能有空格：

BAD : * [Another Awesome Book] (http://example.com/book.html) GOOD: * [Another Awesome Book](http://example.com/book.html)

作者名用-（两侧各一个空格的短横）与链接分隔：

BAD : * [Another Awesome Book](http://example.com/book.html)- John Doe GOOD: * [Another Awesome Book](http://example.com/book.html) - John Doe

格式标注（如(PDF)）紧跟在链接（或作者名）之后，中间一个空格：

BAD : * [A Very Awesome Book](https://example.org/book.pdf)(PDF) GOOD: * [A Very Awesome Book](https://example.org/book.pdf) (PDF)

作者名在格式标注之前，完整顺序是：链接 → 作者 → 格式 → 其他标注：

BAD : * [A Very Awesome Book](https://example.org/book.pdf)- (PDF) Jane Roe GOOD: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF)

多个作者用逗号,分隔，作者列表过长时可以缩写为et al.；不使用 "Prof."、"Dr." 等敬称；作者名不能带链接。

老书把出版年份放进标题括号里，而不是行尾：

BAD : * [A Very Awesome Book](https://example.org/book.html) - Jane Roe - 1970 GOOD: * [A Very Awesome Book (1970)](https://example.org/book.html) - Jane Roe

标题取自资源本身，不要自造标题或做编辑性改写；不用全大写标题，不用 emoji。

字母顺序

链接必须按字母顺序插入列表。规则来自 docs/CONTRIBUTING.md 的 “Alphabetical order” 一节：

多个标题以同一字母开头时，依次比较第二个字母及之后的部分，例如aa排在ab之前；
one two（带空格）排在onetwo之前。

如果发现某个链接放错了位置，文档给出的排查方法是：查看 linter 的错误信息，它会告诉你应该交换哪几行。CI 侧的对应机制是 docs/CONTRIBUTING.md Automation 一节所说：GitHub Actions 会运行测试来确保列表字母序和格式规则，必须确认你的改动能通过这些测试。

空行规则

docs/CONTRIBUTING.md 的 Formatting 一节对空行有明确数字要求：

章节用三级标题###，子章节用四级标题####；
所有列表文件都以 Index 开头，Index 里列出并链接所有章节与子章节，Index 本身也保持字母顺序；
最后一个链接与新章节之间留2个空行；
标题与其章节的第一个链接之间留1个空行；
两个链接之间0个空行（即相邻链接直接连写）；
每个.md文件末尾留1个空行。

文档给出的示例结构如下：

[...] * [An Awesome Book](http://example.com/example.html) (blank line) (blank line) ### Example (blank line) * [Another Awesome Book](http://example.com/book.html) * [Some Other Book](http://example.com/other.html)

即：上一条链接后空两行，接### Example标题；标题后空一行，接该章节的第一条链接；同章节内的链接之间不留空行。

格式标注：in process、archived 与许可证

三类标注有固定写法，均来自 docs/CONTRIBUTING.md：

未完成的资源（in process）：

GOOD: * [Will Be An Awesome Book Soon](http://example.com/book2.html) - John Doe (HTML) *( :construction: in process)*

通过 Wayback Machine 等存档服务恢复的链接（archived，优先选较新且完整的存档版本）：

GOOD: * [A Way-backed Interesting Book](https://web.archive.org/web/20211016123456/http://example.com/) - John Doe (HTML) *( :card_file_box: archived)*

仓库实际条目中可以看到同款写法，例如 books/free-programming-books-az.md 中的* C Proqramlaşdırma Dili ( :card_file_box: archived)。

需要邮箱/账号的访问说明：如果下载前被要求提供邮箱或注册账号，用当前语言列表对应的语言在括号内加说明，例如(email address *requested*, not required)。Leanpub 平台的条目可使用访问说明*(Leanpub account or valid email requested)*。

免费许可证标注：只允许标注支持的许可证短代码（不带版本号），列表为：CC BY、CC BY-NC、CC BY-SA、CC BY-NC-SA、CC BY-ND、CC BY-NC-ND、GFDL。标注放在格式标注之后、其他标注之前：

GOOD: * [A Very Awesome Book](https://example.org/book.pdf) - Jane Roe (PDF) (CC BY-SA)

文档给出的逐步操作是：先确认资源页脚、About 页或 LICENSE/Legal 部分的许可证；把许可证字符串归一化为上述短代码（如 “Creative Commons Attribution 4.0” →CC BY，“CC BY-SA 3.0” →CC BY-SA，“GNU Free Documentation License” →GFDL）；放在格式之后、其他标注（archived/in process）之前。不同版本或格式对应不同许可证时，拆成多条分别标注；不确定时，在 PR 描述中说明你判断该资源是免费许可的依据和信息来源。注意不要加 “All Rights Reserved” 这类说明。

多格式资源优先用一个链接；确需多链接时写法为：

GOOD: * [Another Awesome Book](http://example.com/) - John Doe (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)

处理 RTL 语言文件（可选分支）

如果你修改的是*-ar.md、*-he.md、*-fa.md、*-ur.md这类从右向左书写的语言文件，还需要通过仓库自带的 RTL/LTR 检查（.github/workflows/rtl-ltr-linter.yml，脚本为 scripts/rtl_ltr_linter.py，关键词配置见 scripts/rtl_ltr_linter_config.yml）。修复规则在 docs/CONTRIBUTING.md 的 “Fixing RTL/LTR linter errors” 一节：

RTL 文本中的LTR 单词（如 “HTML”、“JavaScript”）：在该 LTR 段落后立即追加&rlm;；
LTR 符号（如 “C#”、“C++”）：在符号后立即追加&lrm;。

文档示例：

* كتاب الأمثلة في R&rlm; - John Doe&rlm; (PDF)

* أساسيات C#&lrm;

该 workflow 只在 PR 带有RTL标签或改动了 ar/he/fa/ur 文件时运行，配置中的严重级别定义为：bidi_mismatch是 error，keyword与symbol是 warning，pure_ltr与author_meta是 notice。

通过自动化检查验证

提交前用仓库的 CI 行为来核对你的改动。两个与格式直接相关的 workflow：

fpb-lint（.github/workflows/fpb-lint.yml）：在每个pull_request上运行，安装free-programming-books-lint后执行：

fpb-lint books casts courses more

它校验的正是字母顺序与格式规则。日志中的错误行会指出应交换的链接，按提示调整顺序即可。

URL 检查（.github/workflows/check-urls.yml）：基于 awesome_bot 对改动文件做 URL 校验。按 docs/CONTRIBUTING.md 的 Automation 一节，要触发 URL 校验，需推送提交信息中包含check_urls=file_to_check的提交，例如：

check_urls=free-programming-books.md free-programming-books-en.md

可以指定多个文件，用单个空格分隔。注意文档明确警告：指定多个文件时，构建结果以最后一个被检查文件的结果为准——可能出现整体绿色但实际上前面的文件有问题的情况，所以要看 PR 底部 “Show all checks” → “Details” 里的构建日志逐文件确认。

此外，docs/CONTRIBUTING.md 还建议：优先原子提交（每次增删改一个 commit），无需在提交 PR 前 squash；贡献即表示同意仓库的 LICENSE 与 CODE_OF_CONDUCT.md。

限制与不适用的情况

以下类型不进列表：博客、博客文章、文章、普通网站（大量托管本仓库所列资源除外）、非课程/录像的视频、书的章节、试读样本、IRC/Telegram 频道、Slack 或邮件列表（竞赛题集列表对此限制较宽松）。
不列六个月后就需要删除的内容：有报名期限或时长的课程、限时免费的资源都不列。
单个讲座或单页 PowerPoint 不算课程；能打印出来且不丢失核心内容的东西不算 Interactive Tutorial。
书籍与课程的边界：单个讲座/视频不是课程；有 ISBN、目录、可下载版本（尤其 ePub）、版本区分、自成一体的资源更可能是书，但不是硬性标准。
翻译作品要署名原作者，译者建议用 MARC relator 代码标注，例如* [A Translated Book](http://example.com/book.html) - John Doe,trl.:Mike The Translator。

条目按上述顺序、空行与标注规则写入，并确认fpb-lint books casts courses more对应的 CI 检查通过、必要时在提交信息中带上check_urls=...触发 URL 校验，即完成了格式合规的贡献准备。

【免费下载链接】free-programming-books:books: Freely available programming books项目地址: https://gitcode.com/GitHub_Trending/fr/free-programming-books

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析