usaco-guide/docs/Content Documentation.md

Content Documentation

The following two modules are good to read:

1. https://usaco-guide.netlify.app/intro/modules
2. https://usaco-guide.netlify.app/intro/code-con

All modules are written in Markdown. There are special additions to the markdown that we have added to this site. If you are confused about something, or if there's a certain feature that you want to add, reach out to Nathan Wang.

1. Getting Started

Running Site Locally

It is highly recommended to run a local version of the site in order to view your changes.

Using Sublime Text with .mdx

1. Download here.
2. Open the command palette (Cmd-Shift-P) and install package control.
3. Open the command palette again, install package -> PackageResourceViewer
4. Extract the HTML package with PackageResourceViewer.
5. Now you can modify html_completions.py by adding to normal_tags (ex. spoiler)
   • actually, for some reason uppercase (CPPSection) doesn't work ...
6. 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.
7. Make snippets!

Other Tools

• You can use StackEdit to check that latex renders properly.
• Markdown Table Generator

2. Module Ordering

Organization

There are six sections in the guide: Intro, Bronze, Silver, Gold, Platinum, and Advanced. Each section is subdivided into categories, which is just a group of modules. Each module represents one "article" or "page" on the site.

ordering.ts

Located at content/ordering.ts, this file stores the ordering of the modules. Hopefully the format is self-explanatory (it matches based on "slug"). Let Nathan Wang know if you have questions.

3. Frontmatter

Frontmatter is the stuff in the beginning of each module that's surrounded by three dashes. Frontmatter is written in YAML. It stores the "metadata" for each module.

• ID: Required. The ID of the module. Ex: getting-started, or containers. This ID is used to identify the module, so make sure it is unique and all lowercase with dashes only. The URL will be generated based off this.
• Title: Required. The title of the module. Ex: Getting Started
• Author: Required. The author of the module. Ex: Unknown
• Description: Required. A short description of the module, similar to what codecademy has in their syllabus. Markdown/Latex does not work in the description field.
• Prerequisites: Optional. Any prerequisites for this module. If you want to reference a module as a prerequisite, list it as a module ID. A link will be auto-generated.
• Frequency: Optional. Takes a number 0-4 inclusive, where 0 = never shown up before and 4 = shows up ~once a contest. Leave this field out if you don't want to show the frequency.

Example Frontmatter

---
id: getting-started
title: Getting Started
description: Welcome to the guide! We'll introduce what programming competitions are and how this guide is organized.
author: Nathan Wang
order: 1
prerequisites:
 - Dummy prerequisite
 - running-cpp
---

# Getting Started
...

4. Table of Contents

A table of contents will be auto-generated based off of the headings in the Markdown. Keep this in mind when formatting your module.

5. MDX and Custom Components

We're using MDX, a superset of Markdown. HTML and React components are supported, so it is possible to add interactivity / custom components to each module.

Some components are globally available in every module (without having to be imported):

• <Spoiler>
• <Info>
• <Warning>
• <Optional>
• <Problems>
• <Resources>
• <Resource>
• <TextTooltip>
• <LanguageSection>
• <CPPSection>
• <JavaSection>
• <PySection>
• <IncompleteSection>
• <Asterisk>

These are all documented below.

Using Custom Components

Interleaving Markdown in JSX is currently a work-in-progress: https://github.com/mdx-js/mdx/issues/628. As such, in order to use markdown with custom components, we need to leave blank lines between the HTML tags and the markdown.

Good:

<Spoiler>

This is **bold**.

</Spoiler>

Bad:

<Spoiler>
This is NOT **bold**.
</Spoiler>

<Spoiler>This isn't **bold** either!</Spoiler>

Spoilers

Spoilers are collapsible elements that only show themselves when the user clicks on it. It's useful when writing solutions to problems.

<Spoiler title="Show Solution">

- Insert OP benq solution here

</Spoiler>

Info Block

<Info title="Insert Title Here">

**Markdown is Supported!!**

</Info>

Warning Block

<Warning title="Insert Title Here">

Fun fact: the title attribute is optional.

</Warning>

Optional Content

<Optional title="Insert Title Here">

Fun fact: the title attribute is optional.

</Optional>

Problem Lists

Problem constructor:

class Problem {
  constructor(
    public source: string,
    public name: string,
    public id: string,
    public difficulty?: 'Intro' | 'Easy' | 'Normal' | 'Hard' | 'Very Hard',
    public starred?: boolean,
    public tags?: string[],
    public sketch?: string,
  ) {}
}

Example usage:

---
id: ds
title: Data Structures
author: Nathan Wang, Darren Yao, Benjamin Qi
description: Introductory problems using sets and maps.
prerequisites:
  - Bronze - "Built-In C++ Containers" or "Built-In Java Collections"
---

import { Problem } from '../models';

export const problems = {
  standard: [
    new Problem('YS', 'Associative Array', 'associative_array', 'Intro'),
    new Problem('CSES', 'Distinct Numbers', '1621', 'Intro'),
    new Problem(
      'CSES',
      'Sum of Two Values',
      '1640',
      'Intro',
      false,
      [],
      'Can be solved without sets.'
    ),
    new Problem('CSES', 'Concert Tickets', '1091', 'Easy', false, [
      'iterators',
    ]),
    new Problem('CSES', 'Towers', '1073', 'Easy', false, [
      'multiset',
      'greedy',
    ]),
    new Problem('CSES', 'Traffic Lights', '1163', 'Normal', false, ['set']),
    new Problem('CSES', 'Room Allocation', '1164', 'Normal', false, [
      'multiset',
      'greedy',
    ]),
  ],
};

## Standard

Do roughly the first half of the Sorting and Searching section in the [CSES Problem Set](https://cses.fi/problemset/).

<Problems problems={problems.standard} />

Resource Lists

stub

Tooltips

stub

<TextTooltip>

stub

<Asterisk>

stub

Language-Specific Content

<LanguageSection>
<CPPSection>

# A heading that only appears in C++

CPP content goes here, note the newlines!

</CPPSection>
<JavaSection>

Java content goes here!

</JavaSection>
<PySection />
</LanguageSection>

In the example above, nothing will be rendered for Python.

Incomplete Section

<IncompleteSection>

- this list is optional and can be used to specify what is missing
- missing 32-bit integer explanation

</IncompleteSection>