解剖 freeCodeCamp 课程挑战定义文件：以首个 HTML 挑战为样本的前置元数据、五段式正文与校验链路

解剖 freeCodeCamp 课程挑战定义文件以首个 HTML 挑战为样本的前置元数据、五段式正文与校验链路【免费下载链接】freeCodeCampfreeCodeCamp.orgs open-source codebase and curriculum. Learn math, programming, and computer science for free.项目地址: https://gitcode.com/GitHub_Trending/fr/freeCodeCampfreeCodeCamp 的课程curriculum以大量 Markdown 挑战文件为核心资产curriculum/fixtures/combined.md 正是其中最典型的样本——它是「Say Hello to HTML Elements」向 HTML Elements 说你好这一 HTML 入门挑战的合并版夹具文件。本文以该文件为主体逐字段解析其前置元数据Front Matter与五段式正文结构并结合 curriculum 包的源码与测试说明这类挑战文件如何被校验、如何区分英文源与翻译合并版读完你可以完整读懂乃至亲手编写一个合法的课程挑战文件。样本文件在 curriculum 包中的位置测试夹具约定curriculum/__fixtures__/目录是 curriculum 包测试用的夹具fixture根目录其布局本身就携带了一条重要约定顶层的combined*.md文件是翻译/合并后的挑战版本english/子目录中存放对应的英文源文件。当前目录结构如下顶层合并版combined.md、combined-html-comments.md、combined-js-comments.md、combined-jsx-comments.md英文源english/challenge.md 及 english 目录下其余文件翻译词典夹具__fixtures__/dictionaries/与__fixtures__/incomplete-dicts/含 chinese / english / spanish 三种语言的 comments 词典这条约定直接对应 get-challenges.ts 中的hasEnglishSource函数它把英文源根目录解析为basePath/english再检查目标挑战文件是否存在返回布尔值。对应的测试 get-challenges.test.js 以basePath ../__fixtures__验证了两种情形challenge.md存在时返回trueno/challenge.md缺失时返回false。也就是说顶层combined.md中文版与english/challenge.md英文版构成了「非英文挑战文件 其英文源」的标准配对样本供翻译管线相关逻辑做测试。前置元数据Front Matter逐字段解析combined.md的 Front Matter 完整内容如下这是每个挑战文件的身份声明区--- id: bd7123c8c441eddfaeb5bdef originalTitle: Say Hello to HTML Elements challengeType: 0 videoUrl: https://scrimba.com/p/pVMPUv/cE8Gpt2 forumTopicId: 18276 title: 向HTML Elements说你好 ---各字段含义与约束如下字段取值说明idbd7123c8c441eddfaeb5bdef挑战的唯一标识24 位十六进制。中文版与英文版共用同一个id表示二者是同一挑战的不同语言版本originalTitleSay Hello to HTML Elements英文原标题。该字段仅出现在非英文翻译/合并版本中英文源文件里没有它challengeType0挑战类型编号0表示 HTML 挑战videoUrlScrimba 视频地址挑战配套视频可选字段允许为空字符串forumTopicId18276帮助论坛对应主题帖的编号类型为数字title向HTML Elements说你好面向学习者显示的标题这里已是中文challengeType: 0这一取值不是随意约定的它在共享包 challenge-types.ts 中被定义为const html 0;并且由此派生出两条关键行为视图类型viewTypes表中[html]: classic即 HTML 挑战使用经典编辑器视图渲染提交类型submitTypes表中[html]: tests即完成提交前必须通过该挑战声明的全部测试。此外hasNoSolution(0)返回false——HTML 类型不在「无解答」列表中从源码结构看这正对应了挑战文件中存在的## Solution小节这类挑战携带参考解答。这些字段的硬性约束由 challenge-schema.js 中的 Joi 校验表把关其中与本样本直接相关的条目包括id: Joi.objectId().required()——id必须是合法的 ObjectId 格式这与文件中 24 位十六进制取值的形态一致challengeType: Joi.number().min(0).max(33).required()——类型编号必须是 0 到 33 的整数title: Joi.string().required()——标题必填tests: Joi.array().items(...).required()——公开挑战的每条测试必须是{ id?, text必填, testString }结构videoUrl: Joi.string().allow()、forumTopicId: Joi.number()——分别对应上表中的可选与数字字段。校验入口为同文件导出的challengeSchemaValidator它对单个挑战对象执行schema.validate(challenge)。五段式正文从 Description 到 SolutionFront Matter 之后是固定骨架的五个小节## Description、## Instructions、## Tests、## Challenge Seed、## Solution每节用带id的section标签包裹。以下按原文件顺序逐节拆解。DescriptionHTML 元素与开闭标签Description 小节面向学习者讲解本章第一个概念原文核心内容如下欢迎来到 freeCodeCamp 的 HTML 编码挑战。这些挑战将逐步引导您完成 Web 开发。首先您将使用 HTML 构建一个简单的网页。您可以在嵌入到此网页中的代码编辑器code editor编辑代码。您是否在代码编辑器中看到了h1Hello/h1这是一个 HTML 元素element。大多数 HTML 元素都有一个开始标记opening tag和结束标记closing tag开始标记形如h1结束标记形如/h1。两者唯一的区别是结束标记左括号后面的那个正斜杠。每个挑战都有可以随时单击「运行测试」按钮运行的测试当您通过所有测试时系统会提示您提交解决方案并进入下一个编码挑战。注意原文中h1、code等尖括号内容是以 HTML 实体lt;/gt;转义后写在code标签里的——挑战正文允许内联 HTML而尖括号必须转义才能安全通过解析。对比英文源 english/challenge.md其 Description 使用的是#60;h1#62;这类十进制实体转义两个文件转义风格不同但语义等价从源码结构看这是翻译/合并环节产物与英文原件在文本细节上的正常差异。Instructions明确可执行的唯一指令要通过此挑战的测试请将h1元素的文本更改为 Hello World。Instructions 小节给出学习者需要做的唯一修改把h1里的文本从Hello改成Hello World。它与 Tests 小节的断言是一一对应的——这是该课程「指令-测试」配对的典型写法。Tests断言即文档Tests 小节以 YAML 代码块声明测试数组combined.md原文为tests: - text: 你的codeh1/code元素应该有“Hello World”文本。 testString: assert.isTrue((/hello(\s)world/gi).test($(h1).text()));这条testString值得逐段拆解$(h1)测试运行时提供 jQuery 风格的$选择器选中渲染结果里的h1元素.text()取其纯文本内容/hello(\s)world/gi正则表达式要求文本中hello与world之间有一个或多个空白字符\sg为全局匹配、i为忽略大小写因此Hello World、HELLO world都能通过而HelloWorld无空格会失败assert.isTrue(...)测试断言 API断言正则匹配结果为真断言失败时展示text字段作为提示文案。text字段是写给学习者看的中文提示testString是机器执行的断言。二者构成{ text, testString }结构正好匹配前文 Joi 校验中对公开挑战测试的定义。Challenge Seed练习的起点代码h1Hello/h1Challenge Seed 小节被div idhtml-seed包裹其代码块是编辑器中预置的起始代码一个写着Hello的h1元素。学习者需要在此种子代码基础上完成 Instructions 要求的修改。Solution参考解答h1Hello World/h1Solution 小节给出通过测试的参考解答——仅将文本补全为Hello World。由于challengeType: 0属于「有解答」类型见上文hasNoSolution分析这个小节在样本中是齐备的。英文版与合并版的差异翻译管线留下的痕迹将combined.md与英文源 english/challenge.md 并排对照可以得到一份清晰的「合并版改造清单」维度英文源english/challenge.md合并版combined.mdid/videoUrlbd7123c8c441eddfaeb5bdef/ 同一 Scrimba 地址完全相同同一挑战的身份与配套视频不随语言变化originalTitle无有记录英文原标题titleSay Hello to HTML Elements向HTML Elements说你好forumTopicId1234518276Description / Instructions / Teststext/ Seed / Solution英文中文代码本身保持英文如h1Hello/h1不变尖括号转义#60;h1#62;十进制实体lt;h1gt;命名实体testString与代码种子在两版中保持字节级一致——测试逻辑与代码不随语言翻译只有text提示与叙述性正文被替换这正是「合并版」文件的核心特征英文代码骨架 翻译后的说明文字 记录来处的originalTitle。姊妹夹具 combined-html-comments.md 还展示了合并版可能携带的另一类内容其 Challenge Seed 中出现了!-- (Chinese) Add your code below this line (Chinese) --这类中文专属代码注释标记说明合并环节会把语言特定的种子代码注释一并合入。从夹具到课程构建与校验链路理解了单个文件之后再看 curriculum 包如何消费这类文件语言校验与构建入口get-challenges.ts 的getChallengesForLang(lang, filters)先校验语言是否在availableLangs.curriculum中非法语言直接抛出 langis not an accepted language 错误再调用buildCurriculum构建整份课程。get-challenges.test.js 以getChallengesForLang(notlang)验证了该抛错分支。英文源存在性检查hasEnglishSource同文件解析basePath/english根目录并做文件系统访问检查是翻译流程判断「是否已有英文原文可对齐」的依据夹具中的english/子目录即为此服务的测试数据。翻译词典build-curriculum提供的createCommentMap用于从词典目录生成「英文注释 → 各语言译文」的映射其测试 build-curriculum.test.js 正是加载__fixtures__/dictionaries完整词典与__fixtures__/incomplete-dicts残缺词典验证两种行为——词典齐全时返回各语言译文词条缺失时回退为未翻译的原文To be translated two回退为自身。这解释了夹具中为什么同时备有两套词典数据。结构校验任何挑战文件在构建产物中都要通过 challenge-schema.js 的 Joi 校验id、challengeType0–33、title、tests数组等硬性要求challenge-schema.test.mjs 及其快照文件对校验器行为做了回归测试。小结combined.md虽然只是一个小型夹具却完整呈现了 freeCodeCamp 课程挑战定义文件的三要素以id为跨语言锚点的前置元数据、指令与断言一一配对的五段式正文、以及「英文源 合并版 翻译词典」三层夹具约定的翻译管线数据面。掌握这套格式后你可以对照 challenge-schema.js 的 Joi 约束自行书写挑战文件并用 get-challenges.test.js、build-curriculum.test.js 等测试了解每个环节被验证的具体行为。【免费下载链接】freeCodeCampfreeCodeCamp.orgs open-source codebase and curriculum. Learn math, programming, and computer science for free.项目地址: https://gitcode.com/GitHub_Trending/fr/freeCodeCamp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考