Have to use Canvas but want to write in plain text?
Undergo a Canversion.
A command-line tool that automates the creation of course materials, letting you work in plain text and maintain a single source of truth for your entire course.
User Guide
Get up and running with Canversion.
1. Installation & Setup
Prerequisites
- Python 3.10 or higher.
- Pandoc: Must be installed and available in your system's PATH.
Setup Steps
- Clone the project to your local machine.
- Create a Python virtual environment:
python3 -m venv venv
- Activate it:
source venv/bin/activate
- Install dependencies:
pip install pandas pyyaml jinja2 requests python-dateutil lxml
2. Configuration
Located in user_config/global_config.yaml
, this file holds your details, API keys, and default paths for all courses.
# user_config/global_config.yaml
user_details:
name: "Your Name"
email: "your.email@example.com"
canvas:
base_url: "https://canvas.instructure.com"
api_token: "YOUR_CANVAS_API_TOKEN"
pandoc:
executable: "pandoc"
default_csl_style: "/path/to/your/chicago-author-date.csl"
paths:
course_data_root_dir: "/path/to/your/courses"
3. Directory Structure
/path/to/your/courses/
└── ANTH1001_S1_2025/ (class_id)
├── class_config.yaml
├── input/
├── csv/
├── topics/
└── bib/
└── output/ (auto-generated)
Developer Guide
Understand the architecture and extend the application.
Application Architecture
1. Config
config_loader.py
2. Load Data
data_loader.py
3. Process
data_processor.py
4. Template
template_manager.py
5. Output
output_generator.py
Canversion uses a five-stage pipeline to process your source files into final documents.
Extending Canversion
Adding a new task follows the "Template → Function → Register" pattern:
- Create a Template: Build a new
.md.j2
file in thetemplates/
directory. - Write the Function: Add a new
generate_...()
function inapp/main.py
that uses your new template. - Register the Task: Add your new task's name to the
AVAILABLE_TASKS
list and add anelif
block inmain()
to call your function.
Available Tasks
Run one or more tasks from the command line.
python -m app.main [CLASS_ID] --tasks [TASK_NAME]