This repository has been archived on 2022-06-22. You can view files and clone it, but cannot push or open issues or pull requests.
usaco-guide/Content Documentation.md

157 lines
4.6 KiB
Markdown
Raw Normal View History

2020-06-15 23:19:07 +00:00
## Content Formatting Documentation
All modules are written in [Markdown](https://www.markdownguide.org/cheat-sheet/). There are special additions to the markdown that we have added to this site.
These special additions are still under development, so they may change frequently.
If you are confused about something, or if there's a certain feature that you want to add, reach out to Nathan Wang.
You can use [StackEdit](https://stackedit.io/) to check that latex renders properly.
2020-06-22 20:58:36 +00:00
### `ordering.ts`
2020-06-15 23:19:07 +00:00
2020-06-22 20:58:36 +00:00
Located at `content/ordering.ts`, this file stores the ordering of the modules. Hopefully the format is self-explanatory
2020-06-15 23:19:07 +00:00
(it matches based on "slug"). Let Nathan Wang know if you have questions.
### Frontmatter
2020-06-20 08:08:44 +00:00
[Frontmatter](https://jekyllrb.com/docs/front-matter/) is the stuff in the beginning of each module that's surrounded
2020-06-15 23:19:07 +00:00
by three dashes. Frontmatter is written in [YAML](https://yaml.org/). It stores the "metadata" for each module.
2020-06-22 20:58:36 +00:00
YAML formatting is _extremely strict_. Be careful about spaces. Additionally, escape special characters by wrapping the string with double quotes.
2020-06-15 23:19:07 +00:00
- **ID**: _Required_. The ID of the module. Ex: `getting-started`, or `containers`. This ID is used to identify
2020-06-20 08:08:44 +00:00
the module, so make sure it is **unique** and **all lowercase with dashes only**. The URL will be generated based off this.
2020-06-15 23:19:07 +00:00
- **Title**: _Required_. The title of the module. Ex: `Getting Started`
- **Author**: _Required_. The author of the module. Ex: `Unknown`
2020-06-22 20:58:36 +00:00
- **Description**: _Required_. A short description of the module, similar to what [codecademy](https://www.codecademy.com/learn/paths/computer-science) has in their syllabus. Markdown/Latex does not work in the description field.
- **Prerequisites**: _Optional_. Any prerequisites for this module. (Coming soon: If you want to reference a module as a prerequisite, you can list the module ID.)
2020-06-28 01:46:20 +00:00
- **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.
2020-06-15 23:19:07 +00:00
2020-06-24 23:08:16 +00:00
### Problem Lists
todo document this... Relevant files are `content/models.ts` and `src/components/markdown/Problems.tsx`. Hopefully, the existing mdx files can help you out...
Problem constructor:
```typescript
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:
2020-06-28 01:46:20 +00:00
```mdx
2020-06-24 23:08:16 +00:00
---
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"
---
2020-06-28 01:46:20 +00:00
import { Problem } from '../models';
2020-06-24 23:08:16 +00:00
export const metadata = {
2020-06-28 01:46:20 +00:00
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',
]),
],
},
2020-06-24 23:08:16 +00:00
};
## Standard
Do roughly the first half of the Sorting and Searching section in the [CSES Problem Set](https://cses.fi/problemset/).
<problems-list problems={metadata.problems.standard} />
```
2020-06-15 23:19:07 +00:00
### Spoilers
Spoilers are collapsible elements that only show themselves when the user clicks on it. It's useful
2020-06-22 20:58:36 +00:00
when writing solutions to problems.
2020-06-17 23:10:45 +00:00
2020-06-15 23:19:07 +00:00
```
2020-06-17 23:10:45 +00:00
<spoiler title="Show Solution">
2020-06-15 23:19:07 +00:00
2020-06-22 20:58:36 +00:00
- Insert OP benq solution here
2020-06-15 23:19:07 +00:00
2020-06-22 20:58:36 +00:00
</spoiler>
```
2020-06-15 23:19:07 +00:00
2020-06-22 20:58:36 +00:00
### Info Block
2020-06-15 23:19:07 +00:00
```
2020-06-22 20:58:36 +00:00
<info-block title="Insert Title Here">
2020-06-15 23:19:07 +00:00
2020-06-22 20:58:36 +00:00
**Markdown is Supported!!**
2020-06-15 23:19:07 +00:00
2020-06-22 20:58:36 +00:00
</info-block>
```
2020-06-15 23:19:07 +00:00
2020-06-28 01:46:20 +00:00
### Warning Block
```
<warning-block title="Insert Title Here">
**Markdown is Supported!!**
</warning-block>
```
2020-06-22 20:58:36 +00:00
### Optional Block
2020-06-15 23:19:07 +00:00
```
2020-06-22 20:58:36 +00:00
<optional-content title="Insert Title Here">
Fun fact: the title attribute is optional.
</optional-content>
2020-06-15 23:19:07 +00:00
```
### Example Module
```
---
2020-06-22 20:58:36 +00:00
id: getting-started
2020-06-15 23:19:07 +00:00
title: Getting Started
2020-06-22 20:58:36 +00:00
description: Welcome to the guide! We'll introduce what programming competitions are and how this guide is organized.
2020-06-15 23:19:07 +00:00
author: Nathan Wang
order: 1
prerequisites:
2020-06-22 20:58:36 +00:00
- Dummy prerequisite
- running-cpp
2020-06-15 23:19:07 +00:00
---
# Hello World!
2020-06-20 08:08:44 +00:00
```