Documents

A document is something for students to read. It may include small or large quantities of text, may have complex formatting, may include images, and may include subdocuments that become separate pages.

There are two different types of document in a course web site: assignments (which have dates) and resources (which do not). The pages of this author guide are also documents. See the assignments and resources section and the course data structure overview.

Content authors typically write documents as Markdown files. Coursage supports a flavor of Markdown with custom Coursage extensions; See the sectionss on document formatting later in this guide.

It is also possible to treat links to Google Docs, PDFs, etc. as documents. Doing so discards the accessibility and semantic extraction benefits of Coursage, but may be the best choice when assigning externally produced materials such as book excerpts.

Document file structure

A document can be a single Markdown file:

doodads.md

A document can thus also be a whole directory, which is useful when a document includes supporting files such as images. The following is equivalent to the single file above — same references from the timeline, same output with the same URL in the resulting course site:

doodads/
  _doodads.md

(Note that the leading _ in the Markdown filename is an instruction to Superfluous to merge the file into its parent. The rest of the filename is arbitrary; _whatever.md or _.md would also work. Naming the file with document ID, as in _doodads.md, is a courtesy to humans: it help differentiate tabs in a text editor, for example.)

A document with images and subdocuments might have a file structure like this:

doodads/
  _doodads.md
  images/
    small-doodad.png
    large-doodad.svg
  sections/
    history.md
    lore.md
    cheat-codes.md

In Coursage parlance, that entire directory tree is still a single “document.”