Prerequisites

In order to edit the website, you need a GitHub account and to be a part of our team's GitHub organization. You can create an account at github.com, and talk to the current Head of Controls to add you to the organization.

What is a List Page?

A list page is any page on the website in which there is a list of elements that all share a similar display format, with similar content in each element of the list. At the time of the writing of this documentation, list pages all share the format of full-width blocks that iterate in alternating colors. Some list pages include the mentors and leaders pages, the resources pages, and the robots page.

Editing a List

List pages work differently than normal content pages. Rather than the .html or .md for the page containing the actual list elements, they simply contain a static template that Jekyll uses to actually generate the page. The contents of the list are taken from .yml files in the _data/ directory.

the YAML Format

All of the lists are stored in the YAML format. YAML is a human-readable data serialization standard—all that means is that it's a format that allows humans to write the contents, and computers to read the contents. Each YAML file stores a list of elements that all have the same format.

Here's an example from _data/awards.yml:

- year: 2018
  events:
   - name: San Diego Regional
     awards:
      - Regional Finalist
      - Innovation in Controls Award sponsored by Rockwell Automation
   - name: Idaho Regional
     awards:
      - FIRST Dean's List Finalist - Ronak Roy
   - name: World Championships - Houston
     awards:
      - Newton Subdivision Finalist

As you can see, each element in a list begins with a dash followed by a space. Specific keys are denoted with the name of the key, a colon, and the value of the key for that element. You can also embed lists inside of YAML elements by using the same dash-space notation.

Editing List Elements

To edit a list element, you just need to change the values within it. The keys are named such that you should be able to discern what the value in each key does. For instance, in the awards from the 2018 season, if I wanted to add "Participation Award" to the Idaho regional and rename champs, I would make the following edits:

- year: 2018
  events:
   - name: San Diego Regional
     awards:
      - Regional Finalist
      - Innovation in Controls Award sponsored by Rockwell Automation
   - name: Idaho Regional
     awards:
      - Participation Award
      - FIRST Dean's List Finalist - Ronak Roy
   - name: FIRST World Championships in Houston, TX
     awards:
      - Newton Subdivision Finalist

Adding List Elements

To add list elements, simply copy an older element and paste it at the top of the file (or wherever you want it to be, the list pages are generated in the same order as the elements appear in the YAML list), editing/adding/removing values. For instance, if I wanted to add the 2019 season, I would add the following to the awards.yml file:

- year: 2019
  events:
   - name: San Diego Regional
     awards:
      - Quality Award sponsored by Motorola Solutions Foundation
   - name: Idaho Regional
     awards:
      - Entrepreneurship Award sponsored by Kleiner Perkins Caufield and Byers
      - Regional Finalists
   - name: World Championships - Houston
     awards:
      - Rank 6 - Galileo Subdivision