1.4  Contributing

Most challenge contributors should be able to edit Quarto, Markdown, and YAML without touching a frontend framework.

The main rule is simple: public challenge and dataset pages are edited in their record files, not copied into the documentation book.

1.4.1 Common Tasks

  • Edit shared docs in the relevant documentation/ subdirectory.
  • Add pages by creating .qmd files in the relevant docs folder and listing them in documentation/_quarto.yml.
  • Add challenge metadata and protocol prose in challenges/<challenge-id>/challenge.qmd.
  • Add dataset metadata and notes in datasets/<dataset-id>/dataset.qmd.
  • Use the order field in challenge and dataset front matter when the public display order matters.
  • Put citations and math directly in the challenge or dataset record body when they belong to one record.
  • Put reusable rules, metric definitions, physics background, and schema conventions in the relevant documentation/ subdirectory.

1.4.2 Single-Source Records

Each challenge has one canonical source:

challenges/<challenge-id>/challenge.qmd

Each dataset has one canonical source:

datasets/<dataset-id>/dataset.qmd

Those files provide structured YAML front matter for cards, filters, status pills, facts, datasets, metrics, baselines, and links. Their Quarto bodies provide the record-specific prose that appears on the public detail pages.

Avoid creating documentation/**/challenge-*.qmd or documentation/**/dataset-*.qmd pages that restate record metadata. If a challenge needs a shared explanation, add it to the relevant reference page and link to it from the record.

1.4.3 Checks

Run these before opening a pull request:

make validate
make build

The validation step catches broken metadata before future challenge pages, dataset pages, leaderboards, or evaluation tooling depend on it.