Getting Started - CodeVA-Curriculum/polyscribe-canvas GitHub Wiki

After you install polyscribe-canvas, you are ready to set up a course repository. The instructions below provide details on setting up a course and uploading course material to Canvas. I recommend starting with a "test" course that doesn't have any active participants so you can learn the basics and gain confidence updating the course using polyscribe-canvas rather than the Canvas web UI.

First, create a new Git repository for the course materials. I generally use the GitHub CLI for this kind of thing, so I'll provide those instructions below. If you are familiar with Git, set up your local and remote repositories using whatever process you are familiar with.

To create a new repository on GitHub, run the following command (replace <organization-name> and <repository-name as appropriate):

gh repo create <organization-name>/<repository-name>

For example, if you are a CodeVA employee trying to create a repo called cs-basics, you would run the following command:

gh repo create CodeVA-Curriculum/cs-basics

Then, clone the repository to your local machine so you can build the course elements:

gh repo clone <organization-name>/<repository-name>

After you clone the repository, open it in your text editor of choice. If you followed the installation instructions verbatim, you can run the following command:

code <repository-name> &$ exit

Then, create the course boilerplate by following the steps below:

1. Create two new folders in the root directory of the repository, one called assets and one called modules
2. Create two new files in the root directory of the repository, one called config.yaml and one called secret.yaml
3. Create a new file called .gitignore with the following contents to avoid inadvertently publishing sensitive information to GitHub:

secret.yaml

Important: Don't skip this .gitignore step! This will configure Git to skip your secret.yaml file when it pushes commits to your origin repository. Failing to add secret.yaml to .gitignore will put you at risk of publishing your Canvas API key.1

When you're done with the boilerplate, your repository should look like this:

assets/
modules/
config.yaml
secret.yaml
.gitignore

Next, you need to add content to your config.yaml and secret.yaml files. The config.yaml file has several fields you can add; some are optional, and some are not.

Here's a minimal example of a valid config.yaml file:

title: CS Basics
authors: Jon Stapleton
id: 12345
link: "https://virtualvirginia.instructure.com"

The secret.yaml file should contain only one field, token:

token: <API token>

You will need to generate an API token using the Canvas web UI in order to use polyscribe-canvas. Follow the steps below:

1. Log into the Canvas web UI for the instance that will host your course.
2. Navigate to your account settings (e.g., visit https://virtualvirginia.instructure.com/profile/settings)
3. Scroll down to "Approved Integrations", and click the + New Access Token button and fill out the form
4. Copy the API key; you will not see it again after this, so don't lose it!

After retrieving your API key, paste it into the token field in the secret.yaml file. Do not share your API key--it grants wide access to your Canvas profile, and you should guard it like you would a password.

You can use the same API key for multiple courses. If you lose the API key, delete it from your Canvas profile using the web UI and generate a new one.

Next, create a test element or two and upload it to Canvas using polyscribe-canvas. Create a new file called test.md in the modules folder, and paste the following content:

---
title: Test Page
type: page
---

Hello! This is a test page.

## Here's a heading

And some more text. Here's an image from a URL:

![A cat](https://placecats.com/400/400)

...and here's an image from a local file:

![A placeholder](placeholder.jpg)

The test.md file will end up as a Page on Canvas. The page includes an image called placeholder.jpg, which we will need to upload to Canvas. Luckily, polyscribe-canvas will take care of this for us.

Add a JPEG image file to the assets folder and name it placeholder.jpg. Any images you want to include in your pages must be added to assets, or they will not display properly on Canvas.

Once you've created your test course element, you can try uploading it to Canvas. To render your course elements and upload them, run the following command from within your course repository:

polyscribe render .

The tool will identify that there is one element and one asset that have not been uploaded to Canvas yet. When polyscribe prompts you to decide whether or not to upload the missing assets and re-render, type Y and press Enter.

Now that you've had polyscribe upload the assets, the files will have rendered correctly and you can upload them to Canvas. When prompted to decide whether or not to upload, type Y and press Enter.

After the tool is finished, you should see your test element on Canvas in the Pages list!