Use reveal-md to generate multiple slides and host them on GitHub Page

As a computer science student, most of my presentations require tons of code demo and math equations. Google Slides and Office PPT are not the best option for me. Additionally, I want a convenient way to manage and share my slides.

Recently I use reveal-md to generate reveal.js slide from markdown and serve it on GitHub Page.

• Demo page: https://slides.hanklu.tw
• GitHub Repo: https://github.com/kehanlu/slides

In this article:

• The workflow I use to create my slides
• Use reveal-md to generate revealjs slides
• Host multiple static slides on GitHub Page.

reveal.js

reveal.js is a popular and open source HTML presentation framework. With web browser, you can create fully featured and beautiful presentation using HTML. (Live demo and manual).

reveal.js support many features, such as auto-animate, speaker notes…etc, I mainly focus on the following:

• Markdown
• LaTex (including inline math equation)
• Syntax highlighted code
• Pdf export
• CSS customization
• Static page generation (host on GitHub Page)

Some drawbacks:

• Not able to co-edit with others
• Hard to arrange images
• Limited interface (not able to draw arbitrary blocks, graphs and arrows…etc)
• No flying text block
• No WYSIWYG (need text-editor and browser preview)

reveal-md

Using original reveal.js to create slides with Markdown is sometimes more complex, especially when you want to manage multiple slides.

Based on reveal.js, reveal-md generate presentation from Markdown files.

Installation

npm install -g reveal-md

Usage

This will start a local server and open a Markdown file as a reveal.js slide.

reveal-md path/to/my/slides.md

with -w option, the browser will automatically reload when you change a Markdown file.

reveal-md path/to/my/slides.md -w

The following I will show you my setup and workflow for making https://slides.hanklu.tw .

My setup

mkdir slides # base folder
cd slides

npm install reveal-md
mkdir -p content content/attachments theme

An overview of file structure:

• content: markdown files
• attachments: images, audios…
• theme: custom theme
• docs: the generated static site (describe later)

.
├── content
│   ├── attachments
│   ├── slide A.md
│   └── slide B.md
├── docs
├── package.json
├── package-lock.json
├── reveal.json
├── reveal-md.json
└── theme
    └── mytheme.css

Config

See https://github.com/webpro/reveal-md for more config options.

reveal-md.json: the config for reveal-md

{
    "separator": "\n---\n",
    "verticalSeparator": "\n----\n",
}

See https://revealjs.com/config/

reveal.json：the config for reveal.js：

{
    "controls": true,
    "progress": true,
    "history": true,
    "center": true,
    "slideNumber": true
}

Run server

This will open a local server on localhost:1948, serving all markdown file in content/

reveal-md content/ -w

Create a slide

Now create a markdown file in content folder.

content/slide A.md

# meow

---

## Cat1

- apple
- banana

----

## Cat2

- Mango
- Orange

On your browser you can see some listing file and slides with default theme.

Generate static site

Generate static site to docs/ and collect static files from content/attachments

reveal-md content/ --static docs --static-dirs=content/attachments

Push to GitHub

First, create a repo on GitHub. See Adding an existing project to GitHub using the command line.

git init -b main

git add .
git commit -m "slides"

git remote add origin <remote repository URL>
git push origin main

Note

.gitignore

.DS_Store
node_modules/

GitHub Page settings

settings > GitHub Pages > Source > Branch:main /docs

Done! Now you have…

• a repo for collecting your presentations
• your presentations host on GitHub Page, everyone can view your slides.

Customized theme

I made my theme by modified the theme from original reveal.js. Copy from reveal.js/theme/.

theme
├── mytheme.css
├── source
│   └── mytheme.scss
└── template
    ├── exposer.scss
    ├── mixins.scss
    ├── settings.scss
    └── theme.scss

npm install -g sass

Watch file change and recompile.

sass --watch theme/source/mytheme.scss theme/mytheme.css

Note:

If you are using custom theme (theme/mytheme.css). By default, reveal-md will put the file at docs/_assets/mytheme.css, which will cause some issue. The directory name starts with underline(_) will not be parsed on GitHub Page.

mv docs/_assets docs/assets

My workflow

Work with VScode

With the help of Extension: Paste-Image, you can directly paste the image from clipboard in a markdown file.

.vscode/settings.json

{
    "pasteImage.path": "${currentFileDir}/attachments",
    "pasteImage.basePath": "${currentFileDir}",
}

Scripts in package.json

in package.json

// ...
"scripts":{
  "start": "reveal-md content/ -w",
  "build": "rm -rf docs && 
            reveal-md content/ --static docs --static-dirs=content/attachments &&
            mv docs/_assets docs/assets"
}

when I am creating slide…

npm run start

when I want to generate static site…

npm run build

Push to GitHub

git add .
git commit -m "`date`"
git push