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"

Each course needs a class_config.yaml file to define its specific metadata and map the filenames you use.

# ANTH1001_S1_2025/class_config.yaml
class_meta:
  department_code: "ANTH"
  unit_code: "1001"
  title: "Introduction to Anthropology"
  canvas_course_id: 12345

input_sources:
  yaml_files:
    bibliography: "bib/references.csl.yaml"
  csv_files_df:
    weekly_schedule: "data/schedule.csv"
  markdown_dirs:
    topics: "weekly_notes"

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 the templates/ directory.
Write the Function: Add a new generate_...() function in app/main.py that uses your new template.
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]