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

  1. Clone the project to your local machine.
  2. Create a Python virtual environment: python3 -m venv venv
  3. Activate it: source venv/bin/activate
  4. 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:

  1. Create a Template: Build a new .md.j2 file in the templates/ directory.
  2. Write the Function: Add a new generate_...() function in app/main.py that uses your new template.
  3. Register the Task: Add your new task's name to the AVAILABLE_TASKS list and add an elif block in main() to call your function.

Available Tasks

Run one or more tasks from the command line.

python -m app.main [CLASS_ID] --tasks [TASK_NAME]