USACO Guide is a Next.js site with MDX content and a lot of automation

The site is Next.js with MDX as the content format

The USACO Guide describes itself as a free collection of curated, high quality resources to take you from Bronze to Platinum and beyond. Bronze, Silver, Gold and Platinum are the division levels of the USACO contest, so the guide is organised as a ladder of competition skills rather than as a general programming course.

The implementation is a modern Next.js application. The front end is built with React, Next.js, TypeScript and Tailwind CSS, with Storybook and Chromatic for component work, MDX through the `@mdx-js/mdx` compiler so that JSX can live inside Markdown, and Firebase for the backend. The manifest pins Next at version 16, Firebase at 12, and the MDX compiler at 3.1.

The content lives in the `content/` directory, and solutions live in `solutions/`. The presence of a `solutions/` directory as a first class top level folder tells you something about the project's design: the guide ships code for the problems it discusses, not just explanations. The `src/` directory holds the application code, `scripts/` holds the tooling that turns content into data, `docs/` holds project documentation, and `public/` holds static assets including the images in the repository.

A `py/` directory sits alongside the JavaScript tooling, which suggests some of the content processing is done in Python rather than in the TypeScript scripts.

The project is run by the Competitive Programming Initiative, and the repository is looking for content authors, not only engineers. The contribution path is to pick an issue from the tracker, comment on it, and open a pull request.

Content is compiled into data before the page renders

The scripts in `package.json` show the shape of the build, and it is not the simple one. The content is not imported directly by the pages; it is processed into a data layer first.

"dev": "yarn tsx scripts/watch-content.ts",
"dev:no-watch": "yarn tsx scripts/load-content.ts && next dev --webpack",
"prebuild": "yarn clean && yarn tsx scripts/index-content.ts",
"build": "next build --webpack && yarn tsx scripts/algolia-index.ts",

The development command runs a watcher, `watch-content.ts`, which picks up changes to the content files. The no-watch variant loads the content once and then starts the Next.js dev server. The prebuild step cleans and then runs `index-content.ts`, which is the step that turns the content into the indexed data the site reads, and the build step finishes by running `algolia-index.ts`, which pushes that data into an Algolia search index.

The clean script shows what the data layer consists of. It removes `dist`, `.next` and `data`, along with two generated JSON files, `public/usaco-divisions.json` and `public/problem-tags.json`. So the divisions and the problem tags are derived artefacts, produced from the content, and they are published into `public/` as static files that the client can fetch.

This design is the reason the content is MDX rather than plain Markdown. A problem page needs a title, a difficulty, a set of tags, a statement, some examples and a solution, and those are structured data as well as prose. The MDX compiler lets a page be a React component that also carries a metadata object, and the indexing script can walk those objects to build the tag and division tables.

Snippet checking and type checking are separate commands

A guide full of code has a specific failure mode. A solution that no longer compiles, or an explanation that references a variable that does not exist, is a documentation bug that no linter on the application code would catch.

The manifest has a dedicated script for it, `check-code-snippets`, which runs `scripts/check-code-snippets.ts` through tsx. It is not wired into the `build` script, which means it runs as a separate step in the contributor workflow rather than as part of a deploy, and it is a good example of the kind of check that a project with this much embedded code needs.

Type checking is separate again, with `check-ts-errors` running `tsc --noEmit`. Linting is split into two: `lint` runs `next lint`, and `eslint` runs the flat config eslint with `--fix` across `src` for the `.jsx`, `.js`, `.ts` and `.tsx` extensions, using a cache. Formatting is `prettier --write .` with a `.prettierrc` and a `.prettierignore` at the root, and there is a `.pre-commit-config.yaml` for the pieces that are checked before a commit.

The component work has its own toolchain. `storybook` serves on port 6006, `build-storybook` produces a static build, and `chromatic` publishes visual changes with a project token and the `--exit-zero-on-changes` flag, so a pull request with visual differences is reported rather than blocked. There is also a `lighthouserc.cjs`, which is the configuration for a Lighthouse run, used to watch the performance of the site itself.

Firebase carries the hosting and the server side pieces

The backend story is Firebase, and the manifest shows which parts of it the project actually uses.

There is a `functions:deploy` script that runs `firebase deploy --only functions`, so there is a Firebase Functions component, and the configuration lives in `firebase.json` at the root with `.firebaserc` alongside it. The dependency list includes the `firebase` package at version 12.

Most of the other dependencies are for the interactive parts of the site rather than for the backend. `@monaco-editor/react` provides the code editor component, which is what a page with a solution needs in order to show code with syntax highlighting and let the reader edit it. `easymde` is a markdown editor, `dayjs` handles dates, `@dnd-kit` provides the drag and drop used for reordering, `github-slugger` generates the URL slugs, and `algoliasearch` is the client for the search index that the build step populates.

Two entries are worth reading for what they imply. `better-sqlite3` at version 12 is a native SQLite binding, which is a sign that some of the tooling reads structured problem metadata from a local database rather than from JSON. And `bad-words` is a dependency for filtering, which in a site with community content and user submitted material is a moderation measure.

The `axios` dependency covers the outbound HTTP calls the site makes to fetch problem statements and metadata from other services.

ShareAlike and NonCommercial are the licence terms that matter

The README states that the work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The repository metadata classifies the licence as custom, so the LICENSE file in the repository root is the authoritative text, but the README badge and statement are unambiguous about which licence applies.

Three obligations come out of that name, and they matter more for an organisation than for an individual reader. Attribution means you must credit the work and indicate whether you made changes. NonCommercial means you cannot use the material for commercial purposes. ShareAlike means that if you remix or build upon the material, you must distribute your contribution under the same licence.

For a student learning from the guide, none of this is a burden. For a company that wants to republish the explanations, the NonCommercial clause is a prohibition, and for a company that wants to adapt a chapter into internal training material, the ShareAlike clause propagates into what you publish. The guide is free to read and to use as a learning resource, and the terms are what keeps it that way.

The project is also organised as a community effort. The repository carries a `CODE_OF_CONDUCT.md`, a `CODEOWNERS` file, a `CONTRIBUTING.md`, and both an `AGENTS.md` and a `CLAUDE.md`, which are the instruction files that tell automated coding assistants how to work in the repository. There is no GitHub release history, and the last push was on 2026-10-19, so the work is continuous and lands as ordinary commits rather than as tagged versions.

Where a curated guide is the wrong tool

Two limits are worth being honest about, and one is the licence rather than the content.

The first is that a guide is a curated path, and a curated path is someone else's judgement about the order things should be learned in. The description says the resources are curated and high quality, which is a claim about a selection process, and the selection reflects what the authors think a competitor should learn. A reader whose goal is a specific technique, for example a data structure they need at work on Monday, will find the material arranged for a curriculum rather than for a lookup, and the site is not a reference manual.

The second is that the explanations assume a level of context. A page that teaches a technique typically builds on several earlier ideas, and a reader who arrives mid-path has to backfill. This is a property of guided material generally, and it is the trade the guide makes deliberately: structure in exchange for flexibility.

The alternative is a flat problem archive with no narrative, where you read a statement, try it, and read a solution afterwards. That path is faster for someone who already knows the technique and wants breadth, and it gives no explanation of why the solution works. The guide is the opposite end of that trade, and the reason to use it is precisely the narrative and the worked solutions.

For a developer looking at the project as a codebase rather than as a learning resource, the more interesting comparison is with a plain static site. The guide is an application with a build pipeline, a content compiler, a search index, component tests and a Firebase deployment, which is a lot of machinery for text, and it is machinery that exists because the content is structured, searchable and interactive rather than a set of pages.

Editorial conclusion

The USACO Guide suits a student or competitive programmer who wants a curated path through algorithms with explanations and solutions, and it suits a developer who wants a well built example of an MDX driven Next.js site with content indexing in the build. It is the wrong resource for a company that intends to republish the content commercially, because the NonCommercial clause of the licence forbids that, and the wrong tool for someone who wants raw practice problems without the narrative. Check the licence in the repository root before you fork anything, then read the contributing module on the site, since the content format is defined there rather than in the repository.

Frequently asked questions

Official sources

1. cpinitiative/usaco-guide on GitHub
2. Issues
3. Project website
4. README