Data driven presentations with Jupyter notebooks — part II: using remarkjs presentation framework

…. where I describe the workflow for using remarkjs and using a markdown file and the html framework to host slideshow on github

Part I: Using revealjs with jupyter notebooks to host slideshow
Part II: this …
Part III: Adding interactions

This is the second part of an ongoing series that I am writing about creating slideshows with jupyter notebooks and hosting it on github. Last time, I discussed you can use a jupyter notebook, convert the jupyter notebook text to first markdown and then use pandoc to convert the markdown document to a reveal.js slide presentation deck and host it on github pages for demonstration. This is useful and produces nice looking slides, but the process is also long: you will need to start with jupyter notebook document, convert to markdown and then use pandoc to convert the document and use git to host it. That said, there are ways where you can convert a jupyter notebook to reveal.js slide decks but you will need to know a fair bit of CSS styling to get it to a shape that will satisfy your needs. Second, while it is possible to use markdown in revealjs slide decks and it is possible to use an external markdown document in revealjs slide decks, it involves a fair bit of work. So, what if you write a jupyter notebook, convert it to markdown document, and immediately use it to develop a set of slide decks?

This is where remarkjs shines. This time we will see that using remarkjs slide presentation framework, you can start with a jupyter notebook, convert it to markdown, add markups, and then use an html template to produce flexible slides that you can show from github pages. We will continue to show how you can add interactivity to the slide decks in part III. In this part, we will use remarkjs to create the slide deck

Step by step

Step 1. Start with a github repo, create a gh-pages branch, clone the repository, and switch to the gh-pages branch. Here is the code with explanations (pretend that our username is ‘someuser’, and repo name is ‘foo’):

~$ git submodule add <>
~$ cd foo
~$ git checkout -b gh-pages

Step 2. Now get a copy of a javascript from the remarkjs website

~$ wget

Step 3. Set up the template html page on this folder with the following code and give it a name, say slideshow.html

<!DOCTYPE html>
<meta charset="utf-8">
@import url(;
@import url(,700,400italic);
@import url(,700,400italic);

body { font-family: 'Droid Serif'; }
h1, h2, h3 {
font-family: 'Yanone Kaffeesatz';
font-weight: normal;
.remark-code, .remark-inline-code { font-family: 'Ubuntu Mono'; }
<textarea id="source">

class: center, middle

<script src="remark-latest.min.js">
var slideshow = remark.create({
sourceUrl: ''

Step 4. Work on the jupyter notebook and write your document, then convert your ipynb document to a markdown file, say your markdown file is ‘’ (it must match the name of the markdown file in the html file), here is the code:

~$ jupyter nbconvert -t markdown markdown.ipynb

In the markdown file, you will need to indicate each slide by putting a --- separator mark between each slide and use -- to indicate increment of elements. All other markdown elements will work.

Step 5. Now upload this file to your github repo

~$ git add .
~$ git commit -m "created the files"
~$ git push origin gh-pages

You can either edit the markdown file directly or you can work on the ipynb file and then convert the ipynb files to markdown file each time you make the changes and upload to git with changes.

Here is the slideshow:

Associate Professor of Epidemiology and Environmental Health at the University of Canterbury, New Zealand. Also in:

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store