Configuration File

Instead of passing CLI flags every time, you can place a coursegen.yaml in the root of your course repository. The generate command discovers it automatically.

Auto-discovery

The command searches for a config file in the current directory in this order:

  1. coursegen.yaml
  2. .coursegen.yaml
  3. coursegen.yml
  4. .coursegen.yml

You can also point to a config file explicitly:

quarto-coursegen generate --config /path/to/coursegen.yaml

Supported keys

# coursegen.yaml

course: course.yaml       # path to course.yaml, relative to this file
output_root: .            # where content/, index.qmd, _quarto*.yml go
templates: templates/     # local Jinja2 templates overlay (optional)
lang: lang/               # local i18n lang directory overlay (optional)
protected_paths:          # optional paths protected from generate --force
    - index.qmd
    - _quarto.yml
Key Default Description
course course.yaml Path to course.yaml
output_root . (current directory) Root directory for all generated output
templates — Local templates directory; searched before built-in templates
lang — Local lang directory; searched before built-in lang files
protected_paths [] Files or directories protected from overwrite, including generate --force (for example index.qmd, _quarto.yml, or _quarto-format.yml)

Precedence

CLI arguments  >  coursegen.yaml  >  built-in defaults

CLI flags always take precedence over anything in coursegen.yaml.

Example: multi-root layout

If your course.yaml lives in a subdirectory, point coursegen.yaml at it:

# coursegen.yaml
course: config/course.yaml
output_root: .
templates: templates/
lang: lang/

Example: custom output root

To generate all output into a build/ subdirectory:

# coursegen.yaml
course: course.yaml
output_root: build/

Example: protect root hand-editable stubs

If you want generate --force to keep the manually edited root website stubs, protect them explicitly:

# coursegen.yaml
protected_paths:
    - index.qmd
    - _quarto.yml
    - _quarto-format.yml

Directory entries are allowed as well. Non-existent paths are ignored. Generator-owned files such as _quarto-nav.yml and sub-project _quarto.yml files are not affected by protected_paths.