Project structure

A tour of the folders and the one file that defines the course order.

Reading 5 min

By the end of this lesson you will

Find any file in the project by its job
Know the single place that controls course order

Cheat sheet

_quarto.yml: Settings and course order
index.qmd: Home page metadata
modules/: One folder per module
theme/: SCSS, Lua filter, scripts

Resources

Quarto project basics

A course is one self-contained Quarto website project. Copy the whole folder to start a new course.

my-course/
├── _quarto.yml            # site settings AND the course order (sidebar)
├── index.qmd              # home page: course metadata lives in its front matter
├── modules/
│   ├── start/
│   │   ├── index.qmd      # module overview page
│   │   └── how-it-works.qmd   # a lesson
│   └── writing/ ...
├── scripts/build.py       # pre-render: generates the home + module pages
├── theme/
│   ├── dark.scss          # dark colour tokens (default theme)
│   ├── light.scss         # light colour tokens
│   ├── _rules.scss        # layout and components, shared by both
│   ├── lesson.lua         # draws the lesson header from front matter
│   └── scripts.html       # progress tracking + quiz behaviour
└── _generated/            # build output, never edit by hand

One file controls the order

The sidebar in _quarto.yml is the table of contents of the whole course:

sidebar:
  contents:
    - text: "Course Home"
      href: index.qmd
    - section: "Start Here"
      href: modules/start/index.qmd
      contents:
        - modules/start/how-it-works.qmd
        - modules/start/project-structure.qmd

Reorder lines to reorder the course. Previous and next links, the home page and the module pages all follow this list.

Name files by topic

Use project-structure.qmd, not lesson2.qmd. Moving a lesson then never means renaming files or fixing links.

Glossary

Module: a group of lessons, one folder.

Lesson: one .qmd page.

Front matter: the YAML block at the top of a page.

Check your understanding

Q1. You want lesson B to come before lesson A. What do you change?

Rename the files with number prefixes Swap their lines in the sidebar in _quarto.yml Edit _generated/home.md

One folder = one self-contained course.
The sidebar in _quarto.yml defines the order.
Name files by topic, not by number.