course.yaml Reference

course.yaml is the single source of truth for the entire course. The generator reads nothing else to determine what files to create.

Top-level structure

course:      # course-wide metadata
  ...

artifacts:   # course-level artifacts (e.g. syllabus, overview deck)
  - ...

modules:     # ordered list of modules
  - ...

`course` block

course:
  id: my-course                  # used in file paths and URLs
  title: "Logic 101"
  subtitle: "Introduction to Formal Logic"
  semester: "WS 2026"
  language: "en"                 # drives i18n strings; built-ins: en, de
  date_format: "%d.%m.%Y"        # optional display format for template-rendered dates
  ects: 3
  instructors:
    - name: "Prof. Jane Smith"
      email: "smith@example.com"
      role: "lecturer"           # lecturer | tutor | coordinator
  organization:
    institution: "Example University"
    department: "Department of Philosophy"
  defaults:                      # applied to every module unless overridden
    status: planned
    visibility: public
    overwrite: on-force          # on-force | always | never
    duration: 90                 # minutes
  schedule:
    start_date: 2026-10-01
    end_date:   2027-01-31
    weekly_day: "Monday"
  i18n:                          # optional inline i18n overrides (see Internationalisation)
    nav:
      home: Startseite

Instructors

Instructors are defined at course level and can be overridden per module. If a module omits its own instructors: list, the course-level list is inherited automatically by the generator.

Each entry supports:

Field	Description
`name`	Full name (required)
`email`	Email address (optional)
`role`	`lecturer`, `tutor`, or `coordinator`

`defaults` block

Any field in defaults is merged into every module entry that does not set that field explicitly. Common uses: status, visibility, overwrite, duration.

`date_format`

course.date_format is optional and controls how built-in templates render human-facing date strings.

It uses Python/POSIX strftime tokens (for example %d.%m.%Y, %Y-%m-%d).
It affects rendered display text (for example module page title dates and schedule tables/lists in syllabus.qmd and index.qmd).
It does not change front matter date: values; those remain machine- readable source dates.

If omitted, the default display format is %Y-%m-%d.

`enabled`, `overwrite`, `visibility`, and `status`

The generator treats these as separate concepts:

enabled controls whether an item is generated at all. When it is false, the generator skips creating the stub file and does not add it to Quarto config.
overwrite controls whether an existing generated stub may be replaced. on-force means only when quarto-coursegen generate --force is used, always means on every run, and never means never overwrite an existing file.
visibility controls whether the item appears in the public course website. The supported values are public and hidden.
status is lifecycle metadata. It is used by the default templates to decide whether to show a document as published or as a placeholder like “coming soon”, but it does not turn generation on or off.

In practice, a hidden item may still be generated if enabled: true, but it is omitted from the public navigation, index pages, and module page links.

Module entries

modules:
  - id: intro                     # unique; used in file names and URLs
    type: lecture                 # lecture | exercise | lab | seminar | …
    title: "Introduction"
    subtitle: "Why logic?"        # optional
    description: |               # optional free-text
      Overview of the course …
    date: 2026-10-01
    duration: 90                  # minutes; overrides defaults.duration
    status: planned               # planned | draft | ready | published
    overwrite: on-force           # on-force | always | never
    visibility: public            # public | hidden
    instructors:                  # overrides course-level instructors
      - name: "Dr. Jones"
        role: tutor
    tags: [logic, intro]
    learning_objectives: |
      - Understand the scope of formal logic
      - Distinguish syntax from semantics
    lms:
      release: 2026-09-28
      due: 2026-10-08
    dependencies: []
    artifacts:
      - id: intro-slides
        type: slides
        enabled: true
        output_formats: [revealjs, beamer]
      - id: intro-handout
        type: handout
        enabled: true
        output_formats: [website, pdf]

Module fields

Field	Default	Description
`id`	—	Required. Unique identifier; used in file names and URLs
`type`	—	Module type (metadata only; `lecture`, `exercise`, …)
`title`	—	Display title
`subtitle`	—	Optional subtitle
`description`	—	Optional free-text description
`date`	—	ISO date of the session
`duration`	`defaults.duration`	Duration in minutes
`status`	`defaults.status`	Lifecycle metadata; typical values are `planned`, `draft`, `ready`, `published`, and `archived`. The default templates treat `published` and `archived` as release-ready.
`overwrite`	`defaults.overwrite` or `on-force`	Existing module page overwrite policy: `on-force`, `always`, or `never`
`visibility`	`defaults.visibility`	`public` or `hidden`; `hidden` items are excluded from the public course website even if they are generated.
`instructors`	course-level list	List of instructor entries
`tags`	—	List of tags (metadata only)
`learning_objectives`	—	Multiline string or list
`lms`	—	LMS release/due dates (metadata only)
`dependencies`	`[]`	List of other module IDs this module depends on
`artifacts`	—	List of artifact entries — see Artifacts

Course-level `artifacts`

Artifacts can also be declared at the top level for course-wide documents such as a syllabus or a course overview slide deck:

artifacts:
  - id: syllabus
    type: syllabus
    enabled: true
    file: "content/syllabus.qmd"

These follow the same schema as module-level artifacts. See Artifacts for all artifact fields and options.

Top-level structure

course block

Instructors

defaults block

date_format

enabled, overwrite, visibility, and status