Table of Contents

Document Options

You can control the appearance and behavior of a Coursage document in the Markdown file’s front matter (the part at the top delimited by ---):

---
display_mode: article
repo: https://github.com/example/example
locked: true
---

# Awesome activity

Follow these instructions for a thrilling education!

If you prefer a clean Markdown file, you can also place options in a separate .yaml or .json file next to the .md file:

src/data/assignments/hw/
  awesome_document.md
  awesome_document.yaml

…or if you’ve organized the document into its own directory, you can add an options file with a _ prefix:

src/data/assignments/hw/
  awesome_document/
    _awesome_document.md
    _options.yaml

The display_mode setting controls the overall appearance of a document:

  • default or none: Compact headings that resemble the site’s home and navigational pages. Good for reading assignments that merely point to another doc, and for short informational documents.

  • instructions: Larger headings and some slightly wider spacing. Good for how-to documents and quick references.

  • article: Large headings, wide spacing, and a distraction-free layout with the site sidebar hidden. Good for activities, homeworks, and other long-form writing. (This page is an article.)

Note that you can change the default display mode for all assignments of a given type in the assignment type configuration.

unlisted

By default, all assignments show up in the assignment index page for each assignment type: a homeworks page, a readings page, etc. If you want an assignment to be linked from the daily summary and the timeline but not listed in the assignment index, make it unlisted:

unlisted: true

locked

If you want to hide something from students completely, make it locked:

locked: true

Locked assignments show up as plain text — no link! — in the timeline, daily summaries, and assignment indices, and Coursage does not generate the output document at all. You can include the locked assignments when doing local development:

bin/dev --unlock

This is a great way to handle work in progress: instructors can draft assignments locally without publishing them on the course site, and the timeline will show that an assignment is coming up without revealing the draft text.

Not just documents

The unlisted and locked options can also apply to assignments and resources that are not documents, namely:

  • ad hoc assignments in the timeline,
  • an assignment .yaml that is just a bare name or a name + URL, and
  • file resources.

In these cases, you can specify unlisted and/or locked alognside the name and optional url properties, either in an assignment/resource .yaml file or in the timeline file:

name: Awesome activity
url: https://example.com
locked: true

If you are revising or importing materials, you may end up with Markdown files that are a bit messy or incomplete. You can warn students that a document is under revision without hiding it from them completely:

cleanup_pending: true

This setting shows a friendly warning at the top of the document about it needing cleanup. In local development mode, the warning popup in the lower right will list all the upcoming assignments that have this flag set, so that you can clean them up as you go without worrying that you’ve skipped over one.

If you imported a document from an external source such as a Google Doc, add a record of the original document’s URL:

original_url: https://docs.google.com/whatever/something

If cleanup_pending is true and there is an original_url, then the cleanup_pending warning message will show students a link to original_url for reference. When cleanup_pending is no longer set, then original_url is no longer visible on the course site — though it is probably a good idea to leave it in the input data for historical reference.

If an assignment has an accompanying Git repository, add a repo property and Coursage will place a prominent “Git repository” link at the top of the document:

repo: https://github.com/mac-comp127/emoji-drawing

If you are using GitHub Classroom to manage coding assignments, then create a separate github_classroom_urls.yaml file in src/data/assignments/ to list the GitHub Classroom URLs for the assignments. Create a group for each assignment type, and list individual assignment IDs inside the group:

activities:
  fun_activity: https://classroom.github.com/a/abcxyz12
  zany_activity: https://classroom.github.com/a/defuvw34

hw:
  hw0: https://classroom.github.com/a/ghirst56
  hw1: https://classroom.github.com/a/jklopq78

While class is in session, the course site will show the GitHub Classroom URL instead of the URL from repo. (Once the course is in archive mode, the course site links directly to the repo and not the assignment.)

These URLs are in a separate file to make it easier to clear out the course site for a new semester. You can delete any or all of the URL values in github_classroom_urls.yaml:

activities:
  fun_activity: https://classroom.github.com/a/abcxyz12
  zany_activity:

hw:
  hw0:
  hw1:

When students view an assignment that has an entry but no value in github_classroom_urls.yaml, they will see a warning that the assignment is not ready yet. You can thus mass-delete all the GitHub Classroom URLs at the start of a new term (so as not to accidentally link to last semester’s URL), then add entries back in at your own pace as the semester progresses.

When an assignment type specifies an instructions_url, by default that link shows up at the top of every single assignment document of that type. However, sometimes the general instructions may not apply to a specific assignment. For example, most in-class activities in COMP 127 at Macalester involve code, and the in-class activity instructions talk about cloning the day’s starter code. However, the Idea Lab activity involves craft materials and no code, so it specifies:

hide_general_instructions: true

Assignment dates (date assigned, date(s) in class, and due date) are not properties of the assignment itself; they are determine by the course timeline.

Individual assignments do have an additional_dates property, which allows an assignment to have intermediate checkpoint dates before the due date. See the additional dates section of the timeline documentation for more information.

Assignments and resources also allow an instructor_notes property. This feature does not work well, and is due for a revamp. Don’t use it — but do think about what you might like from an “instructor notes” feature.