Note that this site is in currently in version 1.0.0-alpha.   Some functionality may be limited.

6. Creating Syllabus Content Using Markdown

We’ll be using Markdown to write a syllabus, and then using Git to track any changes we make to it. Markdown allows us to format textual features like headings, emphasis, links, and lists in a plain text file using a streamlined set of notations that humans can interpret without much training. Markdown files usually have a .md extension.
Markdown is a markup language for formatting text. Like HTML, you add markers to plain text to style and organize the text of a document. Whereas you use HTML and CSS with WordPress, you use Markdown to render legible documents on GitHub. Markdown has fewer options for marking text than HTML. It was designed to be easier to write and edit.
For comparison, you learned to create headers in HTML like this:

<h1>My Syllabus Heading</h1>

In Markdown, we insert headings with a single hash mark like this:

# My Syllabus Heading

A sub-heading (H2) heading uses two hash marks like this:

## Readings

The lessons of this workshop were originally written in markdown. You can see here what they look like in their raw, unrendered form. Compare that with this—the source code for this lesson’s web page, written in HTML here. Markdown is also arguably more sustainable and accessible than formats like .docx because of its simplicity and related ability to be read across multiple platforms. Use of Markdown is also supported by document-conversion tools like Pandoc that can change a markdown file to an .epub with one command entered into your terminal. Here are a few more key elements to get you ready to make your own syllabus in Markdown. To provide emphasis, place asterisks around some text:

*This text will appear italicized.*
**This text will appear bold.**

For emphasis, you need to mark where it should start and where it should end, so you need astrisks at the beginning and end of whatever text is being emphasized. To create a bulleted list, put a hyphen at the beginning of each list item:

- Reading one
- Reading two
- Reading three

To create a link, put the anchor text (the text you will see) in square brackets and the URL in parentheses, directly following the anchor text in brackets. Don’t put a space between them:

I teach at [The Graduate Center, CUNY](

Paragraphs of text are denoted by putting a blank line between them:

This is a paragraph in markdown. It's separated from the paragraph below with a blank line. If you know HTML, it's kind of like the <p> tag. That means that there is a little space before and after the paragraph when it is rendered.
This is a second paragraph in markdown, which I'll use to tell you what I like about markdown. I like markdown because it looks pretty good, if minimal, whether you're looking at the rendered or unrendered version. It's like tidy HTML.


You can look at an example syllabus in raw text form here. You can see what it looks like when it’s rendered by GitHub on GitHub. When editing the markdown file in Visual Studio Code, it might look like this:

What your markdown might look like when typed into Visual Studio Code


  1. Visual Studio Code also has a preview feature for your markdown. Hit the preview button on the top right while editing your markdown file:

    Button to hit to get a preview in Visual Studio Code

    You’ll get two side-by-side panels. Your markdown file will be on the left, and your rendered preview will be on the right:

    Side by side markdown and preview in Visual Studio Code

  2. Remember to save your work—regularly!—with control + s on Windows or + s on macOS.

Challenges for lesson 6

Assignment: Challenge

Use these five elements—headings, emphasis, lists, links, and paragraphs—to create a syllabus. Have a main heading that gives the course title (one #), then subheadings for, at least, course info and readings. Use emphasis (*) for book titles and try to get a list in there somewhere.

If you want an a more advanced challenge, you can review some additional markdown elements on this page and add some extra features like images, blockquotes, or horizontal rules.


Try again!

Which best describes what you're doing when you initialize your project folder:

(Select all that apply)

Try again!

Which best describes Markdown:

(Select all that apply)

Terms Used in Lesson

Can you define the terms below? Hover over each of them to read a preview of the definitions.


Markdown is the language used to format the plain text files in your Git-enabled repository. Its also called a markup language, like HTML. Both languages add markers to plain text to style and organize the …

See term page

Workshop overall progress