Course Structure
Course Overview
Teachstack courses are divided into modules. Modules are then further divided into lessons. Each lesson will contain one or more exercises. This article elaborates further on this structure and how it is generally constructed in the file structure of a course repository.
There can be significant variations in the required file structure depending on your programming language. These are primarily driven by differences in compiled vs. non-compiled languages, and the way that testing frameworks are implemented. We recommend you consult the Advice by Language section for additional guidance.
Modules
A module should contain a block of content for a single concept or theme, like a chapter in a book. There is no upper limit on the number of modules that can be contained in a course, but a valid course must contain at least one module.
Lessons
Lessons are contained within modules. A lesson is a small, bite-sized block of content. A collection of lessons should progressively and cumulatively be used to achieve the learning outcomes of the module. These are presented to the student as individual pages within the Student Workspace.
Exercises
An exercise is a narrowly defined coding challenge that allows the student to interact with lesson content. Each exercise requires a test case to be built using a language appropriate unit test framework (e.g. pytest for Python). A list of supported unit test frameworks by language
A lesson must contain at least one exercise. While there is technically no upper bound on the number of exercises that can be included in a lesson, for the sake of brevity and clarity, we recommend using a maximum of five exercises per lesson. This is a useful rubrick for pacing. If you need more than five exercises, you should consider splitting your content into two lessons.
File Structure
Teachstack coding exercises are stored according to file structure outlined in the following ASCII tree. Conceptually the structure can be separated into an upper-level and lower-level. The upper-level contains the configuration files that allows Teachstack to parse and render the coding course, and a modules folder which houses all the modules in a course. The lower-level is contained within the modules folder contains the directories and subdirectories for the modules, lessons and exercises that form a complete Teachstack course.
my_course_name/ # course folder (root directory)
├── teachstack.json # Teachstack config file
├── requirements.txt
└── modules/
└── my_module_name/ # module folder
├── my_lesson_name_1/ # lesson folder
│ ├── exercise/
│ │ └── main.file # language-specific exercise file
│ ├── tests/
│ │ └── test_1.file # language-specific test case file
│ └── instructions/
│ └── instruction.md # instructional markdown file
└── my_lesson_name_2/ # lesson folder
├── exercise/
│ └── main.file
├── tests/
│ └── test_2.file
└── instructions/
└── instruction.md
Upper Level
teachstack.json
The teachstack.json file is a core configuration file for every Teachstack course. It acts as the “blueprint” that describes the essential metadata, structure, and settings. Importantly it governs the order in which modules, and the lessons within, are presented to the student. The relative position of folders or files within the directory is not important. We recommend you read the dedicated teachstack.json article to familiarise yourself with the structure and layout of this file.
requirements.txt
This text file will list all the libraries you need to import that are not contained within the standard library for your relevant course. At a minimum you will likely need to import a library to use as your testrunner (e.g. pytest is not included in the standard Python library). This file has identical behaviour to a requirements.txt file that you would encounter in any GitHub project.
Lower Level
The modules folder should contain a folder for each module within your course. While folder or file names within the course directory are not rendered in the Student Workspace, for clarity and ease of navigation, we recommend you use a slug case module name as the folder name.
Each module folder requires a subfolder for each lesson. Again we recommend you use a descriptive slug case lesson name for the folder name. Each lesson folder must contain three subdirectories: exercise, tests and instructions.
Exercise Folder
This folder contains the skeleton exercise files specific to your language (e.g. .py, .ts, .css). A lesson may involve one or more exercise file, but the Teachstack client will display an error if no exercise files are present. Exercise files can be completely blank, or can provide a detailed scaffold or completed program.
Tests Folder
The tests folder will contain the test cases for the lesson. These must be authored using a testing framework supported by the runtime for the Student Workspace. Teachstack will handle test collection automatically for valid test files if the teachstack.json file has been completed correctly.
As the exact contents of this folder will vary depending on your course's programming language, we recommend you consult the Advice by Language section for guidance on how to implement your specific programming language.
Test case file names and any unit tests names must be unique within a course. Names will be imported to the global namespace during test collection. Any collision will prevent the course from being rendered in Teachstack.
Instructions Folder
This folder only needs to contain a single markdown file called instruction.md. This file name should not be altered, or the platform will be unable to locate and render your lesson content. No additional content should be added to this folder.