How the Column Works — and How to Take Part

Drop a week-02.md into documents/weekly-problems/, drop a same-named week-02/ directory into code/volumn_codes/weekly-problems/, refresh your browser, and a new week is live on the site. No sidebar edits, no registration, no touching any site configuration. What this handbook covers is every detail between those two steps, plus a few silent traps that will cost you a wasted afternoon if you don't know about them in advance.

What the Column Looks Like

The "Weekly Problems" entry in the "Engineering Practice" group of the top nav is this column. It has three pages: the column home page lists every weekly issue, newest first; each week page carries a few problem cards where learners write code and submit it for judging; and there is a solutions page that aggregates all submitted solutions. Not one of these three pages is a hand-written list — all of their content comes from a manifest (the week-list data) generated by a build-time scan. Add files to the directory, the manifest regenerates, the pages change: that is the entire mechanism behind "add a directory and it's on the site".

Content Lives in Two Places

We split one issue's content across two places. The week page is documents/weekly-problems/week-NN.md, where you write the issue's introduction, attach the problem cards, and give source acknowledgments — how to write it is covered in the next article. The problems themselves live under code/volumn_codes/weekly-problems/week-NN/, one subdirectory per problem, with the problem statement, judging configuration, starter code, and solutions all inside — the structure is covered in the third article.

code/volumn_codes/weekly-problems/examples/ is a separate directory holding one sample problem for each of the six problem types, and it never appears in the week list. Its role is a reference for problem setters: when you want to see what a given type of problem looks like, just browse it.

How the Manifest Discovers Content

The scanning rules aren't complicated; let's walk through them once: every file under documents/weekly-problems/ whose name looks like week-NN.md counts as one issue, and issues are sorted by filename with the newest first. Each issue's week number is taken from the filename (minus the .md), and that name is then used to look for a directory of the same name under code/volumn_codes/weekly-problems/; every subdirectory under it that contains a quiz.json counts as one problem, and problems are sorted by directory name.

The rules are simple, and that is exactly where the traps hide. There are three failure modes that raise no error at all — the page just quietly looks wrong. Let's learn to recognize each of them on sight:

The week number and the code directory don't share the same name. The week page is called week-02.md, but the problem directory is called week-2/ or week2/; the manifest can't find a same-named directory, and the issue still shows up in the list — just with zero problems. No warning, no log, only an empty page. Rename both sides at the same time when you copy the template, and you won't step on this one.

The week number isn't padded to two digits. When week-1.md and week-10.md both exist, filename sorting puts week-1 after week-10, and the column's "newest first" ordering breaks. Always write the week number with two digits, week-01 through week-99 — a range that will serve us a long time at this scale.

The order of the problems isn't the one you set. Problems are sorted lexicographically by directory name, so if you want three problems to ramp up in difficulty, the directory names need numeric prefixes like 01-xxx, 02-xxx, 03-xxx — the prefixes decide the order.

Three Cases That Fail the Build Outright

The traps above are silent; the ones we run into next are exactly the opposite — very loud, with the build erroring out on the spot:

An invalid quiz.json. Every quiz.json picked up by the scan goes through parsing and validation: an unrecognized problem type, a judge-type problem missing tests, or a choice-type problem missing its answer all throw, and the build fails. The exact error messages you'll want when debugging, together with the fixes, are collected in the fourth article.

A solution missing answer.md. Under solution/ in a problem directory, every submitter's subfolder must contain an answer.md (the explanation of the approach); if it's missing, the build reports 题解缺 answer.md(说明) and fails outright.

A broken weeklyThanks. This field is an array; in each entry, github must follow the GitHub username rules (1 to 39 characters, alphanumeric plus hyphens, with no hyphen at the start or end), and role must be a non-empty string — anything else errors and fails the build. Just fill it in according to the username rules and you're set.

One more case is worth knowing: when the configuration is broken so badly that the manifest scan doesn't even pick it up, the page renders a "bad card" notice. That's a runtime fallback — don't count on it; passing the build locally is the real acceptance check.

Three Ways to Take Part

For our purposes, "authoring a full issue of problems" is not the only way to take part — the barrier comes in three tiers:

If you just want to propose a problem, opening an issue or saying a word in the group chat is enough. Write down the problem's source (which course, which book), its rough difficulty, and why you think it's worth practicing; the maintainers evaluate it and land it, and your name goes into that issue's weeklyThanks acknowledgments. The first issue's problems came about exactly this way.

If you're willing to author problems in full, copy the template kit at code/volumn_codes/weekly-problems/_template/, fill in the blanks following the comments, and open a PR. Every spot you'll need to write in is walked through, one by one, in the second through fourth articles of this handbook.

Writing solutions only is welcome too: just add a folder named after your GitHub username under any problem's solution/ directory. This is the lowest-barrier way to take part — see the fifth article.

And if you can't make up your mind, or all you have is a problem statement and a reference answer, posting the materials to an issue or the group works too. Whoever does the hands-on landing, the credit is still given.

Local Preview and What Learners See

Once pnpm dev has the local server up, any change to the week directories takes effect on a browser refresh — no dev restart needed. What the issue looks like locally and what learners see online are the same rendering.

When setting problems, a few learner-side mechanisms are worth keeping in mind: problem cards load only when they enter the viewport, so a page carrying many problems won't slow down the first screen; judging goes through an online compilation service whose environment is gcc -O2 -std=c++23, with a 3-second cooldown on submissions; learners' code drafts and solving progress are stored in the browser locally and do not sync across devices. Keep these three things in mind while authoring, and your problem statements and judging data are much less likely to come out ambiguous.