Table of Contents

External calendars

Coursage will show events from external calendars on the course home page while the semester is in session. This encourages students to attends upcoming office hours, campus events, and the like. It supports any calendar that is published online in .ics format, which includes public Google and iCloud calendars.

Because Coursage generates public web sites, it does not support private / password-protected calendars. If the data isn’t public, it shouldn’t be on your Coursage site.

Coursage organizes events into categories, each of which appears as a separate section on the course home page. Configure these categories in categories.yaml:

dept_events:
  name: "MSCS department events"
help:
  name: "Help sessions"

Data sources

Coursage can gather events from multiple calendars, and those external calendars do not necessarily correspond to the displayed event categories. To add an external calendar source, add a file in src/data/calendars/sources/ that describes (1) where to get the calendar data and (2) how to categorize it. For example, here is a mscs.json (either JSON or YAML works) that pulls Macalester MSCS Department events:

{
  "name": "MSCS Events",
  "view_url": "https://calendar.google.com/calendar/embed?src=macalester.edu_k7f54d0aeqnpvqb3kjl5kvnuvg%40group.calendar.google.com&ctz=America%2FChicago",
  "ics_url": "https://calendar.google.com/calendar/ical/macalester.edu_k7f54d0aeqnpvqb3kjl5kvnuvg%40group.calendar.google.com/public/basic.ics",
  "default_category": "dept_events"
}

Notes:

view_url This is a clickable URL that shows the calendar as a web page.
ics_url This is a URL that provides calendar data in .ics format.
default_category The ID of a category from the categories file where events from this calendar will go. Multiple calendars can go to the same category.

Because it is common to use Google calendars, you can specify a single gcal_id from which Coursage will derive the appropriate view_url and ics_url for you. Here is an equivalent variant of the mscs.json above:

{
  "name": "MSCS Events",
  "gcal_id": "macalester.edu_k7f54d0aeqnpvqb3kjl5kvnuvg@group.calendar.google.com",
  "default_category": "dept_events"
}

To find the gcal_id for a calendar:

  • Go the the Google Calendar web interface.
  • Click the triple dots next to a specific calendar in your calendar list, and choose “Settings and sharing.”
  • Search for “Calendar ID” within that settings page (in tiny text, about 3/4 of the way down; cmd-F / ctrl-F is your friend).

Sometimes the event titles in a calendar need a little context. For example, here is a hypothetical calendar with events that all have titles like “Sally’s Office Hours.” We use the desc_prefix setting to alter the titles to, for example, “COMP 100: Sally’s Office Hours.”

{
  "name": "COMP 100 preceptors",
  "gcal_id": "monj77g628aokilm1p7l3m1m1nno@group.calendar.google.com",
  "desc_prefix": "COMP 100: ",
  "default_category": "help"
}

Event categorization

Sometimes not all the events from a calendar belong in the same category. Here is configuration that pulls Dev Garden events, and categories open consulting hours under “Help sessions” but all other events under “MSCS department events:”

{
  "name": "Dev Garden",
  "gcal_id": "macalester.edu_foee38ec77nqatr9hor7id17bk@group.calendar.google.com",
  "default_event_url": "https://devgarden.macalester.edu",
  "default_category": "dept_events",
  "categories": [
    {
      "match_desc": "open consulting hours",
      "category": "help"
    }
  ]
}

Notes:

default_event_url This makes all events in the calendar clickable and directs them to the given URL, even if the individual event does not specify a URL.
match_desc A regular expression. Matched against the event title/description.

You can use per-event categorization to completely filter out certain events by assigning them to a the category null. For example, the MSCS events calendar lists a large number of office hours that crowd out the community events; here is a third version of mscs.json that hides them:

{
  "name": "MSCS Events",
  "gcal_id": "macalester.edu_k7f54d0aeqnpvqb3kjl5kvnuvg@group.calendar.google.com",
  "default_category": "dept_events",
  "categories": [
    {
      "match_desc": "office hours|R support",
      "category": null
    }
  ]
}

Coursage is a static site generator, but calendars are dynamic data. Keeping the upcoming events up to date means periodically rerunning the generator. The production environment does this automatically every so often, but if you want to keep calendar events up to date in your local development environment, read on.

In order to prevent site rebuilds from being slow, and to avoid hammering the calendar servers when testing changes locally, the site generator caches the fetched calendar data. You will get calendar events the first time you run bin/dev, but those events will then stay frozen in time on your local machine, eventually rolling off into the past.

To update the displayed events, first delete cache/ in your project directly (if it exists) and then rerun the generator:

rm -rf cache/
bin/dev