Learn how to combine reveal.js+pandoc+GitHub Pages to put together a great presentation.
Reveal.js is a great framework for producing awesome presentations. If you are reading this, then you are probably already familiar with it; if you don’t, and you give presentations using slides, then you should stop reading immediately and go read about Reveal here. This article explains how to host your presentations on GitHub pages. Check this page to see what the result looks like.
I find it very convenient to host my presentations on GitHub for three reasons. First, I deploy and then I don’t need my laptop with me anymore: usually at conferences or in class there is always one desktop computer connected to the projector: I can open the browser, visit the page hosted on GitHub and it always works. Second, if somebody wants to check the presentation later, he does not have to download anything or ask me to send the slides: write down the url and visit it whenever you want. Finally, If I have to make a small change, I can use the GitHub editor: the presentation is updated on the commit. Convinced? Keep reading to learn how to do it.
How to do it
Create an empty repository on GitHub
The first thing to do is creating a new repository: we will call it
Set a branch for Pages
Now you have to specify which branch to publish: got to https://github.com/youruser/reponame/settings, and from the menu
branch under GitHub Pages set
master as the source branch, then click save. At this point you don’t need to do anything else on the GitHub website: close the browser and open the terminal.
Download reveal.js on your local machine inside the folder
git clone email@example.com:hakimel/reveal.js.git reponame
Set your GitHub repo as the default origin
This commands remove the remote origin of reveal.js and connects it to your newly created repo:
cd reponame/ git remote rm origin $ git remote add origin https://github.com/youruser/reponame.git
reponame is the name of the repo that you just created on GitHub.
We are almost done: let’s push! I use the
-f option to overwrite the README.md that is in the remote branch: I initialized the repo with the README so that I could go directly to the settings and set
master as the source branch for Pages; if the branch is empty, you can’t do that.
$ git push -f --set-upstream origin master
Now you have just pushed the demo presentation of reveal.js to your repository. You can see it here: http://youruser.github.io/reponame/. If you can’t see it, then give it a minute.
Editing the presentation
To create your presentation and replace the demo, you have to modify the
index.html file. A quick way to do it is to write it in markdown — one title per slide — and then export it to HTML using pandoc (follow the instructions to install it).
This is my sample presentation in markdown:
# ./revealHello/presentation.md --- author: Angelo Basile title: Reveal.js+GitHubPages+Pandoc date: June 21, 2017 --- # Reveal rocks Some code ```python print("hello world") ``` # Slide 2 * test * test
Now, assuming that you have
presentation.md in the the presentation folder, you type the following to export the presentation from markdown to HTML.
$ pandoc -t revealjs -V revealjs-url=./ --slide-level=2 -s presentation.md -o index.html
Note: you have to set the number of levels that you want, otherwise you will produce one big slide.
Now you are done: push again to save the changes and update your presentation online.
$ git add . $ git commit -m 'edited presentation with pandoc' $ git push
If you enjoyed the article, consider subscribing to the newsletter to receive free updates directly in your mailbox.
create a new repository from https://github.com/new
under GitHub Pages set the variable source to
master branch and click Save
$ git clone firstname.lastname@example.org:hakimel/reveal.js.git reponame $ cd reponame/ $ git remote rm origin $ git remote add origin https://github.com/youruser/reponame.git $ git push --set-upstream origin master
Here is a screencast that shows that whole process: