栏目怎么运转,出题怎么参与

往 documents/weekly-problems/ 放一个 week-02.md,再往 code/volumn_codes/weekly-problems/ 放一个同名的 week-02/ 目录,刷新浏览器,新的一周就上站了。不用改 sidebar,不用登记,不用碰任何站点配置。这份手册要讲的,就是这两步之间的全部细节,以及几个您不提前知道会白白折腾一下午的静默陷阱。

栏目长什么样

顶栏"工程实践"分组里那项"每周一些题"就是这个栏目。它有三个页面:栏目首页列出各期周题,最新在最前;每个周页面挂几张题卡,学员在卡里写代码、提交判题;还有一个题解页,聚合所有已投稿的题解。这三个页面没有一个是手写列表,内容全部来自构建期扫描生成的一份 manifest(周列表数据)。您往目录里加文件,manifest 重新生成,页面就变了,这就是"加目录即上站"的全部原理。

内容放在两个地方

一个期次的内容,咱们把它拆在两处。周页面是 documents/weekly-problems/week-NN.md,写这一期的引言、挂题卡、给出处致谢,怎么写见下一篇。题目本体在 code/volumn_codes/weekly-problems/week-NN/ 下面,一道题一个子目录,题面、判题配置、初始代码、题解全在里面,结构见第三篇。

code/volumn_codes/weekly-problems/examples/ 是另一个目录,六种题型各放了一道示范题,永远不会出现在周列表里。它的作用就是给出题人当参照:您想看某类题长什么样,直接翻它。

manifest 怎么发现内容

扫描规则不复杂,咱们看一遍:凡是在 documents/weekly-problems/ 下、文件名形如 week-数字开头.md 的都算一期,按文件名排序,最新的排最前。每期的周号取自文件名(去掉 .md),然后拿着这个名字去 code/volumn_codes/weekly-problems/ 找同名目录,目录下每个带 quiz.json 的子目录算一道题,题按目录名排序。

规则简单,坑也就藏在这里。有三种失败方式不会报任何错,页面安安静静就是不对,咱们挨个认一遍脸:

周号和代码目录不同名。 周页面叫 week-02.md,题目目录却叫 week-2/ 或 week2/,manifest 找不到同名目录,这一期照样出现在列表里,只是零道题。没有警告,没有日志,只有空页面。您复制模板时两边同时改名,就不会踩这条。

周号没补足两位。 week-1.md 和 week-10.md 同时存在时,按文件名排序,week-1 会排在 week-10 后面,栏目的"最新在前"就乱了。周号永远写两位,week-01 到 week-99,对咱们来说这个量级够用很久。

题与题的顺序不是您排的。 题按目录名字典序排,所以三道题想按难度递进,目录名就得是 01-xxx、02-xxx、03-xxx 这样带数字前缀,顺序由前缀决定。

会让构建直接失败的三种情况

上面那些坑是静默的,咱们接下来碰到的正好相反,动静很大,构建当场报错:

quiz.json 配置不合法。每个被扫描到的 quiz.json 都会过一遍解析校验,题型不认识、判题类缺 tests、选择类缺答案,都会抛错,构建失败。您排错要用的报错原文和修法,集中在第四篇。

题解缺 answer.md。题目目录里 solution/ 下每个投稿人子文件夹都必须有 answer.md(思路说明),您要是少了它,构建报 题解缺 answer.md(说明),直接失败。

weeklyThanks 写坏了。这个字段是数组,每项的 github 要符合 GitHub 用户名规则(1 到 39 个字符,字母数字加连字符,连字符不放开头结尾),role 要是非空字符串,不满足就报错,构建失败,您照着用户名规则填就好。

还有一种情况值得您知道:配置坏得连 manifest 都没扫到时,页面上会渲染一张"坏卡"提示。那是运行时的兜底,别指望它,本地把构建跑过才是正经验收。

三种参与方式

对咱们来说,不是只有"完整出一期题"才算参与,门槛分三档:

只想提个选题,开个 issue 或者在群里说一句就行。写清题目来源(哪门课、哪本书)、大致难度、为什么觉得值得练,维护者评估后落地,您的名字进这一期的 weeklyThanks 致谢。栏目第一期的题目就是这么来的。

您愿意完整出题,就复制 code/volumn_codes/weekly-problems/_template/ 模板包照注释填空,然后提 PR。填空时要动笔的每一处,手册第二到第四篇逐个讲。

只想写题解也欢迎,往任意题目目录的 solution/ 下加一个以您 GitHub 用户名命名的文件夹就行,这是门槛最低的参与方式,见第五篇。

您要是拿不定主意,或者手头只有题面文本和一份参考答案,直接把材料发到 issue 或群里也行。谁动手落地都可以,署名照给。

本地预览与学员看到的

pnpm dev 起本地服务后,周目录的任何改动刷新浏览器即生效,不用重启 dev。这期内容长什么样,您本地看到的和学员线上看到的是同一套渲染。

出题时,还有几个学员侧的机制值得咱们记着:题卡进入视口才加载,一页挂很多题不会拖慢首屏;判题走的在线编译服务,环境是 gcc -O2 -std=c++23,提交有 3 秒冷却;学员的代码草稿和做题进度存在浏览器本地,换设备不会同步。出题时把这三件事记在心里,题面和判题数据就不容易写出歧义。