Writing Course Pages in Markdown and HTML
Author: Phil Chambers | Markdown
Markdown is well known in the tech field, and it sure is nice to use when writing course pages. If you are writing a lot of text and would like to use basic (and perhaps a little more advanced) markup with relative ease compared to the Rich Content Editor or HTML editor built into Canvas, then this could be for you.
There are many ways to write a Page in Canvas - the traditional one would be to open the Rich Content Editor (RCE) and start typing - or copying and pasting from a document that the subject matter expert has given you. If you do the former, I find that you spend a while messing around with the options presented in the editor, such as changing things to headings, bold text, etc. With the latter, you might be copying and pasting from a XML-document like a Microsoft Word file which can bring in unwanted styles or numerous unnecessary span tags. I find that using a Markdown editor is a lot cleaner and easier to flip between styles on the page.
What it is for - and what it isn’t
What it is
First all, what is Markdown? Well the simplest way to demonstrate that is to go to The Markdown Guide and start reading about it. Here’s a description from the page:
Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.
“What is Markdown?” from Markdown Guide
What it’s not
Markdown is not a replacement for HTML, and was not supposed to be. You can insert HTML into Markdown files in some instances, and if you controlled your institution’s Canvas stylesheet, you could edit how certain HTML elements appeared on the page when converted from Markdown files. I never assume this is the case though as I do not have access to this stylesheet myself and, to my utter despair, have to add inline CSS to the HTML in each Canvas page (oh the horror!) This is not something that would be made easier by just switching to Markdown.
How do I get started?
Don’t have time to read the whole guide? Well all you really need to get started is the Markdown Cheat Sheet and a text-editor capable of writing in Markdown syntax.
Editors
I use two editors primarily to create Markdown files.
- Bear
- This is a note taking application for macOS and iOS/iPadOS. I use it when I want to make notes about absolutely everything when I am on the go. There are other applications like this but it is the one I have used the most.
- Visual Studio Code
- This is what I am using now to create these blog/tutorial entries and the entire website using Hugo. The website is set up with HTML/CSS/JavaScript and then I just make a new Markdown file for whenever I want to make a blog entry. It’s very simple!
How is this different from making a page using the Canvas editor?
Imagine you want to make a copy of paragraphs of text in Canvas using the Rich Content Editor. After you figure out what you want to write, you would have to highlight the text you want to be a heading, or bold or whatever style changes you have decided on and use the toolbar to change all of these, one by one. If you were using the HTML editor, you would need to go into the code and do this:
<h2>First Paragraph</h2>
<p>This is the text for this part.</p>
<h2>Second Paragraph<h2>
<p>This is the text for this next part.</p>
In Markdown though? All you need to do is this:
## First Paragraph
This is the text for this part.
## Second Paragraph
This is the text for the next part.
Isn’t that much easier? The headings are created using the # character. The more you add, the lower the headings go. I believe it goes all the way down to H6, which would be this:
###### Heading 6
Other Elements
There’s no need to go through the trouble of clicking the ‘bold’ button either for bold text, because you can just type this in the Markdown editor:
This is how you make **bold** text!
Then, when converted to HTML, it becomes the following:
<p>This is how you make <strong>bold</strong> text!</p>
Turning this into a Canvas page
So how do we turn that into a webpage that students can see? Well, the benefit of using a Markdown application like Bear is that you can export your .md (Markdown) files as .html. Then you just copy that HTML code into Canvas and there you go.
Keeping Clean Versions
Another benefit of editing a Canvas page outside of Canvas is that you have a clean copy of it which is a lot easier to manage than using the Canvas editor (both RCE and HTML). Creating your course content outside the LMS from the start means that any unfortunate surprises that you might run into with the Canvas editor(s) are avoided and can be easily fixed if necessary. This is true whether you are using Markdown or a code editor like Visual Studio Code to write directly in HTML (perhaps you have a course template that you edit on Canvas with icons, etc).
Local vs Online Files and Folders
Another great advantage of this is that you can just organize your course structure offline without needing to worry about loss of access to a course. I make courses in an offline format first using a combination of Markdown and HTML files plus any of the additional content required for a course like images, assignment-related files, etc. Then when you are ready, you can export them via HTML to Canvas. No need to worry about saving files or pages from the Canvas LMS!
My Course Structures
When using this kind of course creation method, I end up having folders that look like this:
.
|-- module_1
|-- img
|-- mod_1_overview.html
|-- mod_1_resources.html
|__ mod_1_lectures.html
|-- module_2
|--img
|__image1.png
|__ mod_2_assignment_1.html
|-- module_3
[...]
Then you can do whatever you need to afterwards before copying and pasting the html into the Canvas html editor. Speaking of which…
I have a bunch of custom classes and styles though…
This is where it can get tricky, and you may need to employ the help of an external program to quickly add or replace the default Canvas headings with inline style versions of your institution’s headings if you cannot access the stylesheet document. My workplace has its own Canvas course template but uses inline styles to create that rather than editing the stylesheet. I created a small script where I can quickly replace all the elements with the custom versions from our template. For example, <h2> becomes something like <h2 style="color: black; [...]">.
If you do have Admin access to Canvas and can change the styles through the stylesheet, it is just a matter of doing a find and replace (either manually or automatically) to add those classes to headings.