GitHub to Canvas Gem

Introduction

The github-to-canvas gem is designed to aid in integrating GitHub and the Canvas LMS. This gem takes a GitHub repository's README.md file, converts it to HTML, and pushes it to Canvas using the Canvas API. This gem can also update existing Canvas lessons, allowing continuous alignment of content between GitHub and Canvas.

This gem is built for use internally at Flatiron School, so some features may be specific to Flatiron School branding and needs. Access to the Canvas LMS API and the ability to add pages and assignments to a Canvas course are required. Write access to the GitHub repository being converted is also required for some features.

NOTE: the --forkable option is now deprecated! Please be sure to update any commands you use to remove it.

Installation

gem install github-to-canvas

Setup

Generate Canvas API Key

In order to access the Canvas API, you must first generate an API key. Go to your Canvas Account Settings and under Approved Integrations, create a New Access Token. You will need to store this API key as an ENV variable called CANVAS_API_KEY.

If you are using Zsh, the following command will add your new key to the top of ~/.zshrc:

echo "$(export 'CANVAS_API_KEY=<your-new-API-key-here>' | cat - ~/.zshrc)" > ~/.zshrc

If you are using Bash, use this command instead:

echo "$(export 'CANVAS_API_KEY=<your-new-API-key-here>' | cat - ~/.bash_profile)" > ~/.bash_profile

If you aren't sure which you use, run echo $SHELL

Add Canvas API Base Path

The exact Canvas API path is specific to where your Canvas LMS is located. For example, Flatiron School's base path is https://learning.flatironschool.com/api/v1. Add this path as an ENV variable like the API key. Do not add a / at the end after /api/v1.

echo "$(export 'CANVAS_API_PATH=<your-base-api-path>' | cat  - ~/.zshrc)" > ~/.zshrc

Or for Bash:

echo "$(export 'CANVAS_API_PATH=<your-base-api-path>' | cat  - ~/.bash_profile)" > ~/.bash_profile

After both the API key and path are added to ~/.zshrc, run source ~/.zshrc (source ~/.bash_profile for Bash) to make them available in your current terminal. You can verify these variables are present by running ENV and finding them in the output list.

Common Uses

The GitHub to Canvas gem can be used for the following:

• Create a Canvas Lesson from a Local Repository
• Create a Canvas Lesson from a Remote Repository
• Read a Remote Repository as HTML
• Update a Canvas Lesson from a Local Repository
• Update a Canvas Lesson from a Remote Repository
• Retrieve Canvas Course Information as YAML Markdown
• Map GitHub Repositories to a Canvas Course YAML file
• Create New Canvas Course from a YAML file
• Update Lessons in an Existing Course from a YAML file
• Syntax Highlighting

Creating and Updating Canvas Lessons

Create a Canvas Lesson from a Local Repository

Navigate into a repository folder cloned down to your local machine and run:

github-to-canvas -c <CANVAS_COURSE_ID> --type <TYPE> -lr

The command above will create a Canvas lesson of the given type (page or assignment) in the course indicated. It will also remove the repository's top-level header and add an HTML header for Canvas that includes links to the GitHub repository.

Creating a lesson this way will also produce a .canvas file. This file contains info about the Canvas lesson that was created; it is used with a GitHub workflow that automatically updates the Canvas page when a lesson's README is updated in GitHub.

Create a Canvas Lesson from a Remote Repository

To create from a remote repo, run the following command:

github-to-canvas --create-from-github <URL> --course <CANVAS_COURSE_ID> --type <TYPE> -lr

This command works the same as the one above, except that it pulls the content from a remote repo rather than a locally cloned repo. The repository must be public in order to read the markdown file.

Read a Remote Repository as HTML

To read the contents of a remote repo:

github-to-canvas --read-from-github <URL>

This will produce an HTML conversion of the repository's markdown. This HTML can be directly pasted into Canvas' HTML editor if a manual process is needed.

Update a Canvas Lesson from a Local Repository

If you previously created a Canvas lesson from a local repository, you should have a .canvas file present in the repo. If that file is present, you can run the following command to update the listed Canvas lesson automatically:

github-to-canvas -a -lr

If you don't have or want to use the .canvas file, you can also specify the course ID and lesson ID. Running this command will add the specified course to the .canvas file in the local repo:

github-to-canvas -a --course <CANVAS_COURSE_ID> --id <CANVAS_LESSON_ID> -lr

Canvas course and lesson IDs can be found in the URL.

Update a Canvas Lesson from a Remote Repository

You can update an existing Canvas course using a remote GitHub repository like so:

github-to-canvas --align-from-github <URL> --course <COURSE_ID> --id <LESSON_ID> --type <TYPE> -lr

This will read remote markdown using the provided URL and update a Canvas course using the info provided. Type must match the existing lesson type.

Course Creation

This gem can create Canvas courses from scratch. These features are still in development and may not work for all course designs. Quiz and Discussion Topic lesson creation is still under development and will not work.

By providing a YAML file of the desired course structure, this gem can create a course, add in modules, and populate those modules with pages and assignments. The required YAML file must follow a specific structure. Using the steps below, this gem can create the necessary YAML markup from existing Canvas courses.

Retrieve Canvas Course Information as YAML Markdown

To create YAML markup of an existing Canvas course, use the following:

github-to-canvas --query <CANVAS_COURSE_ID>

This command will use the Canvas API to read a course's information, including its module and lesson structure and lesson URLs. YAML markup will be produced as a result. This output can be directly saved to a file, which will make the next step a little easier:

github-to-canvas --query <CANVAS_COURSE_ID> > query_results.yml

The output will look similar to this:

---
:name: The Course's Title
:id: 111
:modules:
  - :id: 2020
    :name: First Module's Name
    :lessons:
      - id: slugified-page-name
        title: This is the Title Of The First Lesson, a Page
        indent: 0
        type: Page
        html_url: https://learning.flatironschool.com/courses/111/modules/items/27001
        page_url: slugified-page-name
        url: https://learning.flatironschool.com/api/v1/courses/111/pages/slugified-page-name
        published: false
        repository: ""
      - id: 333
        title: This is the Title Of The Second Lesson, an Assignment
        indent: 1
        type: Assignment
        html_url: https://learning.flatironschool.com/courses/111/modules/items/27002
        page_url: ""
        url: https://learning.flatironschool.com/api/v1/courses/111/assignments/333
        published: false
        repository: ""
  - :id: 2021
    :name: Second Module's Name
    :lessons:

The output YAML will not include associated GitHub repository information.

Map GitHub Repositories to a Canvas Course YAML file

To associate repositories to an existing course YAML, the following command can be used:

github-to-canvas --map <YAML_FILE>

For this feature to work, all Canvas lessons must have the GitHub HTML header that is added using -l. This header contains the necessary repo information.

Save the output YAML to another file if you want to use it for later course creation. For example:

github-to-canvas --map query_results.yml > course_structure.yml

The resulting YAML file will contain course information, the module and lesson structure, and each lesson's associated GitHub repository.

Create New Canvas Course from a YAML file

To create a Canvas course with this gem, you will need a correctly structured YAML file with the course info, modules, lessons and associated lesson repositories. In addition, all lessons must have a type (Page or Assignment), a repository, and a title. Other lesson options are currently ignored.

Here's an example of what the YAML file should look like.

---
:name: Test Building Course
:course_code: TEST-GEM-COURSE
:modules:
  - :name: Module 1
    :lessons:
      - title: Lesson 1
        type: Assignment
        repository: https://github.com/learn-co-curriculum/react-hooks-component-props-mini-project
      - title: Lesson 2
        type: Page
        repository: https://github.com/learn-co-curriculum/phase-0-pac-1-js-variables

With the necessary data configured, use the --build-course option and pass in the course's YAML file:

github-to-canvas --build-course course_structure.yml -lr

This command will cause the following to happen:

• Create a Canvas course using the top level :name: in the YAML data
• Create the first module
• Create the first lesson using the repository, title and type, as well as additional command options
• Add the newly created lesson to the current module
• Create the second lesson and add it to the module...
• Repeat process until all modules and lessons are created

Update Lessons in an Existing Course from a YAML file

The GitHub to Canvas gem can be used to update all lessons in a course with a single command. To do this, you will need an up-to-date course YAML file with repositories mapped to each lesson.

github-to-canvas --query <COURSE_ID> > query_results.yml
github-to-canvas --map query_results.yml > your_new_course.yml

Use the resulting file (in this example, your_new_course.yml) to update all lessons in a course based on their GitHub repo:

github-to-canvas --update-course YAML_FILE -lr

The gem will iterate over the data and update every lesson according to the associated repository.

Syntax Highlighting

This gem uses the Rouge Ruby gem to add syntax highlighting to fenced code blocks. Rouge tokenizes the fenced code blocks and generates HTML elements with CSS classes to style code blocks. The classes generated by Rouge are intended to work with Pygments.

You can download and customize CSS themes for the classes generated by Rouge at this site:

• http://jwarby.github.io/jekyll-pygments-themes/languages/javascript.html

After selecting your preferred CSS, you will need to update your Canvas theme so the CSS can run on each page.

Known Issues

HTML Code Snippets Do Not Render

The Canvas API renders all HTML it receives. If your repository's markdown includes HTML that is not meant to be rendered, the content will be rendered as part of the page's HTML, resulting in unusual display errors in Canvas. Examples of this would be lessons on HTML or JavaScript that include HTML code snippets.

To fix any rendering issues in Canvas, go to the Canvas WYSIWYG editor for the afflicted lesson. Click the HTML editor option (</> button in the lower right) to switch to HTML.

Read the GitHub repo as HTML:

github-to-canvas --read-from-github URL

Copy the output HTML and paste it into the Canvas editor (if your lesson has a <header> with github links, leave this in). This should clear up some larger page rendering issues, but may not fix all code snippets issues. To fix these, switch back to the regular Canvas WYSIWYG editor, then open a second tab to the GitHub repo you're converting from. Copy any HTML code snippets from GitHub and paste them into the Canvas editor where they should be displayed.

The Canvas editor will treat the pasted HTML content as code and will automatically replace some characters, escaping the code from the normal rendering process.

Note that realigning after fixing this content with the gem will break the rendering for these lessons again. A fix is planned for this issue, but has not been implemented.

Markdown Formatting Issues Cause Errors in Canvas

An empty line should separate individual markdown headers, paragraphs and code snippets in the markdown. Without these empty lines, the contents will be interpreted as one continuous paragraph and ignore formatting.

New Repos That Use a main Branch

If you are using a new GitHub repository that uses a main branch, you may not be able to create or update from a remote repository. You can still create and update from a local repository by using the --branch (-b) option and specifying main as the branch.

A fix is planned for this issue, but not implemented.

Overview of GitHub to Canvas workflows

Using this gem, you can maintain Canvas courses in multiple ways - either by creating and updating individual Canvas lessons or through the YAML file process.

At Flatiron School, we use the Canvas blueprint course feature. We use the github-to-canvas gem to update the blueprint copy of lessons. These updates will appear in future copies of the course or when synced down associated courses in Canvas.

This can either be done with individual lessons or using a YAML files to keep entire courses updated.

If you are using github-to-canvas in this way, changes should always be made on the repository, not on Canvas. Any changes made only on Canvas will get overwritten if the lesson is updated using the gem.

Common Options

• --create-lesson, -c: Requires a Canvas course ID. Creates a new Canvas lesson, converting the local repository's README.md to HTML. Adds .canvas file to remote repository
• --align, -a: Updates a canvas lesson based on the local repository's README.md. If no other options are used, --align will look for a .canvas file to know what to lesson to update
• --course: Provide a specific course ID. When used with --id, this can override the default behavior for --align, allowing you to update any existing lesson and ignore the .canvas file if present.
• --id: Provide a specific lesson ID. This can be found in the URL of the specific lesson. For Pages, used the slugified lesson title.
• --type: Sets the type of Canvas lesson to be created (page, assignment or discussion). If no type, type decided based on repository structure.
• --name: Can be used to override default naming behavior. By default, Canvas lesson names are determined by the first top-level (#) header in the repository's markdown file.
• --fis-links, -l: Adds additional Flatiron School HTML header after markdown conversion, including links back to the GitHub repo and it's issue form.
• --remove-header-and-footer, -r: Removes top lesson header and any Flatiron School specific footer links before converting to HTML. Removing top lesson header prevents duplicate titles while viewing in Canvas.
• --create-from-github: Requires a GitHub repository URL. Also requires --course and --type. Creates a Canvas lesson, reading from the remote repo instead of a local repository. Repository must be public.
• --align-from-github: Requires a GitHub repo URL, --course, --id, and --type. Updates a Canvas lesson from a remote repository.
• --read-from-github: Requires a GitHub repo URL. Reads a remote repository and converts its contents to HTML, but does not push to Canvas.
• --branch, -b: Can be used when creating or aligning with a local repo to specify which branch to use. Use this if you have a new repository that uses a main branch instead of master.
• --save-to-github, -s: If you are are creating or aligning content locally, the .canvas file is not automatically committed to the repo. This option will attempt to commit and push the .canvas file to the remote repository.

DEPRECATED:

• --forkable: Adds a Fork button to the Flatiron School HTML header. For use with custom Canvas JS to enable Canvas assignment forking workflow for Flatiron School students.

Run github-to-canvas --help for additional options not listed in this Readme.

Examples of Valid Images This Gem Can Convert

This gem can convert both standard inline markdown and HTML images.

Inline Markdown:

HTML: