从 0 到 1 上手项目式学习资源库3 步跑通本地校验并贡献第一条教程【免费下载链接】project-based-learningCurated list of project-based tutorials项目地址: https://gitcode.com/GitHub_Trending/pr/project-based-learningproject-based-learning 仓库收录了 400 多个项目式学习教程每条都指向一个从零构建应用的教程按 C/C、Python、JavaScript 等语言分节组织。这篇文章不讲教程本身而是讲如何使用和贡献这个仓库——你能在本地跑通 README 校验、加上一条合格的教程条目并看懂它的 CI 如何守护链接质量。你将获得的清单一条可直接运行的本地校验命令以及通过的判定标准新增教程条目的唯一语法格式、缩进、放置位置链接失效link rot自动巡检的完整链路周扫、两击制、自动修复 PR环境与前置准备这个仓库只有 Markdown 加一个 Python 脚本零第三方依赖先跑起来再理解文件作用README.md教程列表本体仓库里唯一的业务内容CONTRIBUTING.md贡献规则条目格式、放置位置、PR 要求scripts/check_readme.py校验器 链接检查器提供 lint / check-diff / check-links / report / prune 五个子命令scripts/linkcheck-domains.txt已知会屏蔽自动化访问的域名清单scripts/lint-allow-duplicates.txt允许重复出现的 URL 白名单.github/workflows/validate-pr.yml提交 PR 后的自动校验流程环境要求只有两样Python 3仅标准库无需 pip install和 git 客户端。下面是获取仓库并立即跑通一次完整校验的命令git clone https://gitcode.com/GitHub_Trending/pr/project-based-learning cd project-based-learning python3 scripts/check_readme.py lint退出码为 0 即代表当前 README 完全合格最后一行会打印stats: entries… urls… sections… errors…这样的统计。最小可运行链路这个仓库的设计核心是README 即数据教程列表不是自由文本而是结构化数据一行一条。校验器逐行解析用同一套正则语法把每行归类再汇总做交叉检查README.md 逐行 → classify_line 分类(entry/series/header/toc) → parse_readme 汇总条目、目录、重复 URL → 输出诊断(E00x) stats 统计行 → 退出码 0/1lint 的成功判定是固定的诊断中无 error 级别条目、退出码 0。PR 校验、每周链接巡检、自动修复 PR全部建在这一次解析之上——读懂这一条链路后面都是它的复用。关键模块拆解条目语法两空格缩进定层级classify_line() 负责判断这一行是什么。关键参数是每两级 2 空格的缩进单条教程直接挂链接系列教程多部分是纯文本标题加缩进子条目格式如下- Title # 单条教程 - Series Title # 系列标题无链接 - Part 1 # 缩进 2 空格 - Part 2放置规则写在 CONTRIBUTING.md条目放进对应语言分节语言分节不存在时允许新建但必须同步加进目录。lint 规则集错误码即文档parse_readme() 对解析结果做交叉检查输出带错误码的诊断对照这张表就能自助排错错误码含义修法指向E001无法解析的行 / 目录行出现在目录块之外修正 README.md 对应行的格式E002系列标题下没有更深一级的子条目补缩进子条目或改为直链条目E003 / E004目录锚点与 ## 标题互相缺失补目录项或改标题使锚点对上E005重复 URL确属有意交叉引用时加入白名单E102使用了短链域名bit.ly 等换回原始链接链接活性检查两击制避免误杀check-links 子命令真实访问每个 URL先 HEAD 请求失败自动降级 GET跟随重定向、对 429/5xx 重试然后把结果判为 OK / HARD_DEAD / SUSPECT / BLOCKED 四类。两个设计细节值得注意scripts/linkcheck-domains.txt 里列出的域名medium.com、reddit.com 等会屏蔽自动化访问统一判 BLOCKED绝不当成死链状态存在.github/link-rot-state.json采用两击制URL 必须连续两次周扫失败才算死避免网络抖动误伤之后 prune 命令才会基于它自动生成修复 PR把模块拼成完整功能贡献一条新教程完整闭环共五步。第 1 步查重在 README.md 里按标题和 URL 确认条目不存在这是 CONTRIBUTING.md 的第一条规则。第 2 步按上面的格式在对应语言分节加入条目若新建了语言分节同时补上标题和目录项。第 3 步整体验证命令见环境准备一节判定标准是退出码 0。第 4 步模拟 CI只校验你新加的行比 lint 更严新增 http:// 链接、youtu.be 短域都会报错git diff --unified0 HEAD -- README.md | python3 scripts/check_readme.py check-diff判定标准同样是输出 stats 行里errors0。第 5 步可选提前试一下新链接的活性python3 scripts/check_readme.py check-links --urls-from added.json --dry-run其中 added.json 是包含新 URL 的 JSON。以上全绿后再 fork 提 PR服务端 validate-pr.yml 会自动重跑这同一组检查。常见坑与排查⚠️ 以下五条覆盖绝大多数提交被拦的原因现象lint 报E004: ## header … is missing from the Table of Contents→原因新增分节标题但没进目录 →解法在目录块加- [标题](#锚点)锚点按小写、空格转连字符的规则生成现象E005: duplicate URL→原因同一 URL 出现在两个语言分节 →解法确属有意交叉引用如 Crafting Interpreters 同时列在 C/C 和 Java 下就把规范化 URL 加注释写入 scripts/lint-allow-duplicates.txt否则删掉一处现象本地 lint 通过CI 的 check-diff 却报错 →原因check-diff 只查新增行且更严格http://直接判 E101 错误 →解法换成 https://youtube 短链换完整 URL现象check-links 输出 BLOCKED 或 could not verify →原因该域名屏蔽自动化检查被域名策略覆盖 →解法这不是死链浏览器手动确认可达即可不要试图修它现象E002: series title has no deeper child entry→原因系列标题行之后没有更深一级的子条目 →解法补齐缩进子条目或把系列降级为带链接的单条条目继续深入仓库内最值得通读的三处材料CONTRIBUTING.md 的 PR 三条约定每个教程单独一个 PR、标题要有描述性、与作者或站点有关联须声明scripts/check_readme.py 顶部的 docstring 与 classify_line()能解释为什么 lint、PR diff、周巡检永不漂移.github/workflows/link-rot.yml 里周扫 → 提交状态 → prune 自动开 PR → 汇总 issue的完整链路。下一步建议按顺序执行本地跑一次python3 scripts/check_readme.py check-links --all --dry-run亲眼看一遍全库链接健康度从 README 挑一门你熟悉语言的分节实际做完其中一条从零构建教程按本文闭环提交一条真实教程条目走完 fork → 修改 → lint → PR 全流程【免费下载链接】project-based-learningCurated list of project-based tutorials项目地址: https://gitcode.com/GitHub_Trending/pr/project-based-learning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从 0 到 1 上手项目式学习资源库：3 步跑通本地校验并贡献第一条教程
从 0 到 1 上手项目式学习资源库3 步跑通本地校验并贡献第一条教程【免费下载链接】project-based-learningCurated list of project-based tutorials项目地址: https://gitcode.com/GitHub_Trending/pr/project-based-learningproject-based-learning 仓库收录了 400 多个项目式学习教程每条都指向一个从零构建应用的教程按 C/C、Python、JavaScript 等语言分节组织。这篇文章不讲教程本身而是讲如何使用和贡献这个仓库——你能在本地跑通 README 校验、加上一条合格的教程条目并看懂它的 CI 如何守护链接质量。你将获得的清单一条可直接运行的本地校验命令以及通过的判定标准新增教程条目的唯一语法格式、缩进、放置位置链接失效link rot自动巡检的完整链路周扫、两击制、自动修复 PR环境与前置准备这个仓库只有 Markdown 加一个 Python 脚本零第三方依赖先跑起来再理解文件作用README.md教程列表本体仓库里唯一的业务内容CONTRIBUTING.md贡献规则条目格式、放置位置、PR 要求scripts/check_readme.py校验器 链接检查器提供 lint / check-diff / check-links / report / prune 五个子命令scripts/linkcheck-domains.txt已知会屏蔽自动化访问的域名清单scripts/lint-allow-duplicates.txt允许重复出现的 URL 白名单.github/workflows/validate-pr.yml提交 PR 后的自动校验流程环境要求只有两样Python 3仅标准库无需 pip install和 git 客户端。下面是获取仓库并立即跑通一次完整校验的命令git clone https://gitcode.com/GitHub_Trending/pr/project-based-learning cd project-based-learning python3 scripts/check_readme.py lint退出码为 0 即代表当前 README 完全合格最后一行会打印stats: entries… urls… sections… errors…这样的统计。最小可运行链路这个仓库的设计核心是README 即数据教程列表不是自由文本而是结构化数据一行一条。校验器逐行解析用同一套正则语法把每行归类再汇总做交叉检查README.md 逐行 → classify_line 分类(entry/series/header/toc) → parse_readme 汇总条目、目录、重复 URL → 输出诊断(E00x) stats 统计行 → 退出码 0/1lint 的成功判定是固定的诊断中无 error 级别条目、退出码 0。PR 校验、每周链接巡检、自动修复 PR全部建在这一次解析之上——读懂这一条链路后面都是它的复用。关键模块拆解条目语法两空格缩进定层级classify_line() 负责判断这一行是什么。关键参数是每两级 2 空格的缩进单条教程直接挂链接系列教程多部分是纯文本标题加缩进子条目格式如下- Title # 单条教程 - Series Title # 系列标题无链接 - Part 1 # 缩进 2 空格 - Part 2放置规则写在 CONTRIBUTING.md条目放进对应语言分节语言分节不存在时允许新建但必须同步加进目录。lint 规则集错误码即文档parse_readme() 对解析结果做交叉检查输出带错误码的诊断对照这张表就能自助排错错误码含义修法指向E001无法解析的行 / 目录行出现在目录块之外修正 README.md 对应行的格式E002系列标题下没有更深一级的子条目补缩进子条目或改为直链条目E003 / E004目录锚点与 ## 标题互相缺失补目录项或改标题使锚点对上E005重复 URL确属有意交叉引用时加入白名单E102使用了短链域名bit.ly 等换回原始链接链接活性检查两击制避免误杀check-links 子命令真实访问每个 URL先 HEAD 请求失败自动降级 GET跟随重定向、对 429/5xx 重试然后把结果判为 OK / HARD_DEAD / SUSPECT / BLOCKED 四类。两个设计细节值得注意scripts/linkcheck-domains.txt 里列出的域名medium.com、reddit.com 等会屏蔽自动化访问统一判 BLOCKED绝不当成死链状态存在.github/link-rot-state.json采用两击制URL 必须连续两次周扫失败才算死避免网络抖动误伤之后 prune 命令才会基于它自动生成修复 PR把模块拼成完整功能贡献一条新教程完整闭环共五步。第 1 步查重在 README.md 里按标题和 URL 确认条目不存在这是 CONTRIBUTING.md 的第一条规则。第 2 步按上面的格式在对应语言分节加入条目若新建了语言分节同时补上标题和目录项。第 3 步整体验证命令见环境准备一节判定标准是退出码 0。第 4 步模拟 CI只校验你新加的行比 lint 更严新增 http:// 链接、youtu.be 短域都会报错git diff --unified0 HEAD -- README.md | python3 scripts/check_readme.py check-diff判定标准同样是输出 stats 行里errors0。第 5 步可选提前试一下新链接的活性python3 scripts/check_readme.py check-links --urls-from added.json --dry-run其中 added.json 是包含新 URL 的 JSON。以上全绿后再 fork 提 PR服务端 validate-pr.yml 会自动重跑这同一组检查。常见坑与排查⚠️ 以下五条覆盖绝大多数提交被拦的原因现象lint 报E004: ## header … is missing from the Table of Contents→原因新增分节标题但没进目录 →解法在目录块加- [标题](#锚点)锚点按小写、空格转连字符的规则生成现象E005: duplicate URL→原因同一 URL 出现在两个语言分节 →解法确属有意交叉引用如 Crafting Interpreters 同时列在 C/C 和 Java 下就把规范化 URL 加注释写入 scripts/lint-allow-duplicates.txt否则删掉一处现象本地 lint 通过CI 的 check-diff 却报错 →原因check-diff 只查新增行且更严格http://直接判 E101 错误 →解法换成 https://youtube 短链换完整 URL现象check-links 输出 BLOCKED 或 could not verify →原因该域名屏蔽自动化检查被域名策略覆盖 →解法这不是死链浏览器手动确认可达即可不要试图修它现象E002: series title has no deeper child entry→原因系列标题行之后没有更深一级的子条目 →解法补齐缩进子条目或把系列降级为带链接的单条条目继续深入仓库内最值得通读的三处材料CONTRIBUTING.md 的 PR 三条约定每个教程单独一个 PR、标题要有描述性、与作者或站点有关联须声明scripts/check_readme.py 顶部的 docstring 与 classify_line()能解释为什么 lint、PR diff、周巡检永不漂移.github/workflows/link-rot.yml 里周扫 → 提交状态 → prune 自动开 PR → 汇总 issue的完整链路。下一步建议按顺序执行本地跑一次python3 scripts/check_readme.py check-links --all --dry-run亲眼看一遍全库链接健康度从 README 挑一门你熟悉语言的分节实际做完其中一条从零构建教程按本文闭环提交一条真实教程条目走完 fork → 修改 → lint → PR 全流程【免费下载链接】project-based-learningCurated list of project-based tutorials项目地址: https://gitcode.com/GitHub_Trending/pr/project-based-learning创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考