Timeline

The course timeline, which lives in src/data/timeline.yaml, specifies:

• what topics the course covers when,
• what happens in each day of class,
• when things are assigned, and
• when they are due.

The timeline file is the single source of truth about assignment dates. Move an assignment in the timeline, and all the places on the course web site that show its date assigned or date due will update automatically.

Basic structure

At the top level, the timeline is a list of topics and days:

- topic: "Fundamentals"

- day:
  ...some stuff...

- day:
  ...more stuff...

- topic: "Esoterica"

- day:
  ...yet more stuff...

Coursage automatically assigns days to calendar dates based on academic_calendar.yaml. The topics are not assigned to dates, but appear as dividers in on the course schedule page.

In addition to the large-scale topic dividers in the timeline, individual days may optionally specify a topic:

- topic: "Fundamentals"
- day:
    topic: "Knitting basics"

Each day entry in the timeline can list assignments in three categories:

• what activities happen in class on that day,
• what’s newly assigned on that day, and
• what’s due on that day.

Here’s what that looks like:

- day:
    topic: "Knitting basics"
    due:
      - task: student_survey
      - reading: basic_stitches
    in_class:
      - "Basic knitting demo"
      - activity: knit_purl
    assigned:
      - hw: scarf

The due, in_class, and assigned sections are all optional. You can specify them in any order you like in the timeline file, but the course site will always show them in the order they appear above: first what’s due, then what’s in the class, then what’s newly assigned (presumably after class).

Calendar dates and the course timeline

The timeline is an abstract course plan, not a calendar: it contains no calendar dates, only a sequence of class days. The only part of the input data that contains specific calendar dates is the academic calendar.

That is the input. Coursage’s output — the course web site — contains numerous dates: a course schedule, separate pages for each day of class, due dates for individual assignments, etc. None of those dates appear in the input data; Coursage derives them by combining the academic calendar with the course timeline. For example, this academic_calendar.yaml:

start_date: "2025-09-05"
meeting_days: ["Mon", "Wed", "Fri"]
...etc..

…would combine with this timeline.yaml:

- day:
    in_class:
      - activity: fun_intro
    assigned:
      - hw: first_hw
- day:
    in_class:
      - activity: thrilling_adventure
- day:
    due:
      - hw: first_hw

… to produce a web site with the following dates:

Fri, Sep 5, 2025

• In class: Fun intro
• Assigned: First HW

Mon, Sep 8, 2025

• In class: Thrilling adventure

Wed, Sep 10, 2025

• Due: First HW

This split between calendar and course structure offers adaptability: for example, to shift all coursework to a later date, add an entry in the timeline. It also facilitates course plan reuse across semesters: to move coursework to a new semester, change the start date.

(Note that the web site may also show events imported from external calendars. Those event dates come from the external calendar; Coursage does not manage them.)

Assignments in the timeline

Consider this timeline again:

- day:
    topic: "Knitting basics"
    due:
      - task: student_survey
      - reading: basic_stitches
    in_class:
      - "Basic knitting demo"
      - activity: knit_purl
    assigned:
      - hw: scarf

Here "Basic knitting demo" is freely structured text. That text appears anywhere Coursage shows details for that particular day. This is a good way to list topics in a discussion- or lecture-based class. That text supports Markdown syntax, so you can use it to link to slides or other classroom resources. The example above could also read:

      - "[Basic knitting demo](https://slideware.megacorp.com/FGKJDHFG)"

The other timeline items above are not plain text; they are links to assignments.

Referencing assignments by ID

In the example above, task, reading, activity, and hw are assignment types, while student_survey, basic_stitches knit_purl, and scarf are the IDs of individual assignments. When the timeline refers to an assignment by ID like this, its content appears in a separate file in the assignments/ directory. For example, this assignment entry in the timeline:

- activity: knit_purl

…would point to a Markdown (.md) file like this:

src/data/assignments/activities/knit_purl.md

…or to a directory, if the assignment document contains multiple files such as subsections and images:

src/data/assignments/activities/knit_purl/

If the assignment is purely a link to an external web site and you do not want a document for it hosted on your own course site, then instead of a .md file, you can create a data file that specifies a URL:

src/data/assignments/activities/knit_purl.yaml

name: "Knit and Purl"
url: https://craftytube.example.com/knitting-video

Ad hoc assignments

Sometimes creating a separate file for an assignment is overkill. Instead of specifying an assignment ID, you can create an ad hoc assignment by specifying a name and URL directly in timeline.yaml, indented under the assignment type:

- activity:
    name: "Knit and Purl"
    url: https://craftytube.example.com/knitting-video

You can even provide nothing but a name if a name is all the students need:

- activity:
    name: "Walk to the Mississippi"

In that example, “Walk to the Mississippi” shows up in the course web site’s index of all activities, even though there is nothing for that page to link to. If you don’t want that to happen — if you want something to show up in the timeline and the daily summary but not in the assignment index pages — then make it unlisted:

- activity:
    name: "Open Q&A, review"
    unlisted: true

Here is an example of both assignment IDs and ad hoc assignments coexisting in one day of class:

- day:
    topic: "Fuzzy sweaters"
    due:
      - reading: alpacas
    in_class:
      - activity:
          name: "Alpaca knitting"
    assigned:
      - hw: sweater

(Note here that there is a reading assignment whose ID is alpacas, and there is a separate in-class activity whose name is “Alpaca knitting.”)

Due dates

Assignment that are not in-class activities typically span multiple days. The timeline describes this by listing the assignment twice, once under assigned: and once under due:. For example:

- day:
    topic: "Fuzzy sweaters"
    assigned:
      - hw: sweater
- day:
    ...etc...
- day:
    due:
      - hw: sweater

Here, the sweater homework will show as being assigned on the first day, in progress on the second day, and due on the third day.

Assignments that are never explicitly assigned

It is possible for an assignment to have a due date but never be officially assigned. By default, Coursage shows such assignments exactly as the data would suggest: it show up as due on that date, but is never “in progress” and does not show up in the daily details until the day it is due. However, it is possible to configure an assignment type to automatically assign items of a certain type the day before they are due. See the Assign Types section for more information.

Working on long-term assignments during class

It is possible for the same assignment to have a due date and be a thing that students work on in class:

- day:
    topic: "Fuzzy sweaters"
    assigned:
      - hw: sweater
- day:
    in_class:
      - note_before: "Work on"
      - hw: sweater
- day:
    due:
      - hw: sweater

Assignment checkpoints and additional dates

If a large-scale assignment is due in several phases, one approach is to create a separate assignment for each part:

- day:
    assigned:
      - hw: sweater_part_1

...many days...

- day:
    due:
      - hw: sweater_part_1
    assigned:
      - hw: sweater_part_2

...many days...

- day:
    due:
      - hw: sweater_part_2

However, sometimes it’s best to have a single set of instructions for an assignment but multiple checkpoint dates. Here we accomplish this by creating a large assignment with the full instructions, plus two smaller assignments for the intermediate checkpoints:

- day:
    assigned:
      - hw: sweater
...
- day:
    due:
      - hw: sweater_checkpoint_1
...
- day:
    due:
      - hw: sweater_checkpoint_2
...
- day:
    due:
      - hw: sweater

Then, in the large assignment instructions in src/data/assignments/hw/sweater.md, we attach the sub-assignments using an additional_dates property:

---
display_mode: article
additional_dates:
  - label: "Checkpoint 1"
    hw: sweater_checkpoint_1
  - label: "Checkpoint 2"
    hw: sweater_checkpoint_2
---

# Knit a Sweater!

(Instructions go here)

Additional daily details

Notes

Sometimes you want additional information to show up in the daily details, but not in the timeline and not in the assignment itself. You can use note to attach a remark to an assignment:

- day:
    in_class:
      - activity:
          name: "The cosmic philosophy of crochet"
        note: "(in-class discussion)"
    assigned:
      - hw: crochet_sofa_cozy
        note: "(start soon!)"

A note can also be a list of multiple separate items:

- hw: scarf
  note:
    - "All homeworks are due at 6:00pm on the due date."
    - "Don't forget to use preceptor office hours!"

Sometimes it makes more grammatical sense to have the note appear before the name of the assignment; use note_before for this:

in_class:
  - note_before: "Work on"
    hw: sweater

Announcements

Notes are small details that appear next to a specific assignment. If you want something big and visually prominent to draw students’ attention on a specific day of class, use announcement:

- day:
    topic: "Sewing with a machine"
    announcement: "Class is in the Idea Lab!<br>Library 2nd floor! 😎"
    due:
    in_class:
      - activity: sewing_machine

On that particular day of class, the announcement will be highly visible on the course site’s home page. This is a good way to announce things like a location change or class cancellation.