Markdown, Jupyter, and Github as a New Publishing Paradigm for Classroom Content

Why take this session?

Markdown is a versatile tool that can be used throughout the teaching experience. With markdown you can prepare slides, notes, interactive demonstrations, write computer code, include images in documents and typeset equations. When paired with tools such as Project Jupyter and GitHub it can be a gamechanger for the way you work in the classroom and give you an opportunity to have a broader impact in your domain of expertise.

Who is this session for?

Anyone who prepares classroom or lab content to be curated alone or in teams for delivery to students.

How can I use markdown to help me in the classroom?

What will I learn in this session?

After taking this one-hour tutorial the attendee will:

Jupyter Notebooks

One example use-case for Markdown is through the Jupyter Project’s Jupyter notebook. The link to that project is here. Our intent in this tutorial is to provide access to a Jupyter notebook for the attendee so that you can write some content. This might be for a class, a homework assignment, a lab tutorial or similar.

While not specific to the Jupyter notebook, the notebook interface provides a simple way for us to practice markdown with a minimum of overhead.

Interactive session

Let’s get started!

TLDR/Can’t Attend? Here are the basics:

(1) Getting Started with Markdown

Syntax highlighted code block

# Header 1
## Header 2
### Header 3

- Bulleted
- List

1. Numbered
2. List

**Bold** and _Italic_ and `Code` text

[Link](url) and ![Image](src)

For more details see GitHub Flavored Markdown.

(TBD put in example on using equations)

Why Markdown and Github?

(1) Creates a very professional looking website in almost no time.
(2) Easy for students to access information.
(3) Easy to update information.
(4) Easy to reuse information from year to year.
(5) Easy to collaborate with other content creaters.
(6) Version control.

Getting Started

Example Repository

Creating a New Page

[New class page](./class_new.md)

Use a GIST for your New Page.

Tips and Tricks

Here is an example of a full course website. This is just for content delivery and not for grading or assignments. We still use the LMS for that.

(3) Try Jupyter

Want to get markdown + programming/computiation + naritive + automated slides + autograding all in one package? Jupyter is an open source project that allows a tremendous amound of different languages (Python, R, Matlab, Ruby, etc) in an interactive notebook environment. It is being used in Google’s DataLab Project, IBM’s Data Science Experience, and Microsoft’s Azure ML Studio.

Here are a couple of ways to try it out:

(4) Workshop Slides

See the markdown slides for this workshop.

See the Google slides here.

Workshop outline

(5) Case Studies Reference

Here are three case studies that use markdown and notebooks.