README

Build slides using markdown, whilst adhering to the principles learned from the How to avoid death By PowerPoint TEDx Talk.

You can see the slides of this repository as a demo at https://hogenttin.github.io/hogent-revealmd/ . Play with it to see what it can do!

• Basic usage
  • Installation
  • How do I use this?
  • Live preview
  • Create static site (HTML)
  • Generate PDF
• Configuration
  • Theme
  • Landing page
  • reveal-md options
  • reveal.js options
  • Reveal.js plugins
• Additional tools
  • Automatic deployment
  • Formatting
  • Linting

Basic usage

Installation

1. Install nodejs .

2. Install reveal-md :

   npm install --global reveal-md

How do I use this?

Edit, add or delete put your markdown files in the docs folder. That's all to get started! 🚀

Live preview

Reveal-md allows you to start up a live preview, so you can instantly see how your slides look like whilst editing the markdown files.

To develop a slideshow with live reloading:

reveal-md <slides.md> --watch

Or all slideshows:

reveal-md . --watch

Create static site (HTML)

To generate a static site:

reveal-md --static

This will create the html folder. You can always delete this directory if you want to.

This step is only necessary if you want to host your slides yourself on a webserver. If you use Github actions (see below), this step is not needed: it will be done automatically when you push to the repository.

Generate PDF

To generate a PDF:

reveal-md <slides.md> --print slides.pdf --print-size A4

The resulting PDF isn't very nice though at the moment ... :/ .

---

Configuration

Configuration

💡 You don't have to change these files or settings if you want to keep things simple. In that case, just ignore this section.

Theme

If you want another theme, you can change the theme option in reveal-md.json to point to another CSS file. You can also use an existing link like https://hogenttin.github.io/hogent-revealjs/reveal.js/css/theme/hogent.css from https://github.com/HoGentTIN/hogent-revealjs .

If you copy or fork this repo, but always want to keep the theme of your slides at any time automatically in sync with this repo, you can ... .

a. Set the theme option to the URL https://hogenttin.github.io/hogent-revealmd/_assets/theme.css and delete the local CSS file.

or

b. Change theme.css so you import https://hogenttin.github.io/hogent-revealmd/_assets/theme.css and then you can add CSS overrides below:

@import url(https://hogenttin.github.io/hogent-revealmd/_assets/theme.css);

/* Add your overrides here, e.g. ... */

ul {
    color: red;
}

Landing page

You can change the template index-template.html to create a nice landing page for your course. It uses the Mustache template engine .

reveal-md options

You can add them to reveal-md.json .

reveal.js options

You can add them to reveal.json .

Reveal.js plugins

You can add additional functionality using Reveal.js plugins. These are not standard supported in reveal-md, but can be enabled. E.g., the Mermaid plugin for drawing graphs is added in this repo as an example on how to do it.

---

Additional tools

Additional tools

💡 You don't need this if you want to keep things simple. In that case, just ignore this section. Otherwise, it's here if you want an example.

Automatic deployment

This repo automatically builds the slides and pushes them to https://hogenttin.github.io/hogent-revealmd/ whenever a commit is pushed to the main branch. This is done using using GitHub actions . You can find the workflow in the .github folder.

Formatting

An editorconfig config has been added in .editorconfig. This works nicely together with prettier for which additional config has been added in .prettierrc.yaml:

prettier --write "**/*.{md,yml,yaml}"

⚠️ Use 4 spaces for indentation of nested lists. Otherwise the nesting may not work. This is consistent with the original MarkDown and the CommonMark specs.

Linting

A markdownlint config has been added in .markdownlint-cli2.yaml:

markdownlint-cli2 "**/*.md"

A yamllint config has been added in .yamllint.yaml:

yamllint .

You can also use the pre-commit hooks in .pre-commit-config.yaml to automatically check this at every local commit.