Contributing

All modules are written in MDX (Markdown + JSX) with the XDM compiler. $\LaTeX$ is supported through KaTeX, and the Guide uses a number of custom MDX components. If you are confused about something, or if there's a certain feature that you want to add, reach out to Nathan Wang.

Quick Start

The USACO Guide has a public Github Repository.

• If you're looking to add/modify modules, refer to the content/ folder.
• If you're looking to add/modify problem solutions, refer to the solutions/ folder.
• (Almost) all the other files and folders are related to the front-end code.

If you have any questions about how to contribute, feel free to just open an issue or a pull request and a team member will be able to assist you. If you want, you can also join our Discord server

Using the Editor (recommended)

The easiest way to edit content is to use our live editor.

Running Site Locally

You can also run a local version of the site in order to view your changes. This is useful if you need to use Tailwind CSS classes, which don't work with /editor.

1. Set up your development environment.

   • Install Node.js

     • Gatsby docs
     • npm install -g yarn
2. Clone repo

   • Via command line: git clone https://github.com/cpinitiative/usaco-guide.git
   • Or use Github Desktop
3. Install Dependencies

   • yarn
4. Run development server

   • yarn develop

See the front end documentation for more information.

As a note, Gatsby typically supports Node.js versions in maintenance or long term support (LTS). You can find the status of each version here. It may be necessary to downgrade Node.js for this reason.

Ways to Contribute

Some examples:

Lesson

• Convert lists of resources to tables (Plat / Advanced).
• Add missing descriptions for sections, modules, or resources.

  • All resources should have descriptions.
• Improve explanations for sample problems.

  • If starred resource or editorial already has a good explanation, no need to repeat it.
• Improve implementations.

  • Make sure code compiles, remove excessive macros, add codesnips around templates.
  • Should be consistent across languages.
• Adding modules!
• If you add a substantial amount of text content to a module, add your name to the list of authors in the frontmatter.
• If you add code implementations or improve existing implementations in a more significant way than simply refactoring code, or if you add a short explanation, add your name to the list of contributors.

Problems

• Convert lists of problems to tables (Plat / Advanced).
• Fix problem difficulties and tags.
• Add problems that are good examples of the module topic (and remove those that are not).
• Adding official editorial links.
• Adding editorials.

  • If no editorial exists, or if existing editorial could be improved.
  • Or solution code in a different language, etc.

Markdown Resources

• Markdown Cheat Sheet
• Markdown Table Generator

Markdown Editors:

• Using our online editor is probably best.
• Visual Studio Code
• Sublime Text

  • .md syntax highlighting is fine, is also ok for .mdx
  • You can open a .mdx file and set syntax highlighting to be the same as .md with View -> Syntax -> Open all with current extension as ... -> Markdown -> Markdown.
• StackEdit

  • Automatically compiles $\LaTeX$ (doesn't require an installation)
• Obsidian

  • Automatically compiles $\LaTeX$ (doesn't require an installation)