Slidesdown

Slideshows as fast as you can type.

Slidesdown is powered by the incredible reveal.js presentation framework.

Learn

Visit slidesdown.github.io/learn.html to get started.

Usage: View Slides

Online Viewer

Visit slidesdown.github.io/loader.html and enter the URL to your Markdown presentation, e.g. github.com/slidesdown/slidesdown/SLIDES.md.

CLI

Slidesdown provides a CLI to quickly open files on your computer in the Online Viewer or a viewer hosted in a local Docker container that can be used fully offline (i.e. perfect for presentations you want to keep private).

Installation

sudo curl -L https://raw.githubusercontent.com/jceb/slidesdown/main/slidesdown -o /usr/local/bin/slidesdown; sudo chmod a+x /usr/local/bin/slidesdown

The following optional programs are used by slidesdown:

• docker required for offline presentations and hot-reloading slides while editing.
• python3 required for online presentations via slidesdown.github.io if the slideshow file shall be served from the local computer, i.e. useful for creating slides or when the presentation is private and shall not be made accessible publicly via GitHub.
• decktape or docker for exporting slideshows as PDF.
• xdg-open, open-cli or open (MacOS) for opening the slideshow in the default browser.
• curl for updating the slidesdown script.
• node for making the presentation accessible on the internet via a CloudFlare tunnel.
• yq JSON and YAML parser.
• basenc Base64 encoder.

Update

sudo slidesdown -u

Open local file in slidesdown Online Viewer (python3 required)

Attention: The file with not transmitted to any online service! It will only be served from a local web server to your local browser!

Navigate to any folder with a SLIDES.md file (), then run this command:

slidesdown

If the file name is different from SLIDES.md, pass the file name, too:

slidesdown README.md

Open local file in slidesdown Offline Viewer (python3 required)

Navigate to any folder with a SLIDES.md file (), then run this command:

slidesdown -d

If the file name is different from SLIDES.md, pass the file name, too:

slidesdown -d README.md

Export Slides as PDF

The export requires decktape.

slidesdown -e

If the file name is different from SLIDES.md, pass the file name, too:

slidesdown -e README.md

The exporter can also be used via Docker:

slidesdown -d -e

Usage: Create Slides

Simple

Create a file called SLIDES.md and add your content. Once done, publish it online and open the presentation in the online viewer or use the CLI to do so.

Use Template

There are multiple options for starting with a template that includes meta data and useful configuration options:

1. Download from GitHub:

curl -sflO https://raw.githubusercontent.com/slidesdown/slidesdown/main/examples/SLIDES.md

2. Use CLI:

slidesdown -t

3. Copy template from here:

---
# Metadata about the presentation:
title: Presentation Title
author: Your Name
date: 2023-01-20
keywords: some useful keywords

# Presentation settings:
# URL to favicon
favicon: /favicon.svg
# Theme, list of supported themes: https://github.com/slidesdown/slidesdown.github.io/tree/main/vendor/reveal.js/dist/theme
theme: white
# Code highlighting theme, list of supported themes: https://github.com/slidesdown/slidesdown.github.io/tree/main/vendor/highlight.js
highlight-theme: tokyo-night-dark

# Show progress bar
progress: true
# Show controls
controls: true
# Center presentation
center: true
# Create separate pages for fragments
pdfSeparateFragments: false
# Full list of supported settings: https://revealjs.com/config/ or
# https://github.com/hakimel/reveal.js/blob/master/js/config.js
# UnoCSS styling: https://unocss.dev/interactive/ and https://tailwindcss.com/docs
# Icons: https://icones.js.org and https://unocss.dev/presets/icons
---

# My first markdown slideshow

Author: Your Name

<!-- generated with
!deno run --unstable --allow-read --allow-write https://deno.land/x/remark_format_cli@v0.2.0/remark-format.js --maxdepth 2 %
-->

## Agenda

1. [A horizontal Slide](#a-horizontal-slide)
2. [More Examples](#more-examples)

## A horizontal Slide

- More icons at
  [Icônes <div class="i-fa6-solid-face-smile inline-block m-auto"></div>](https://icones.js.org)

notes:

- Some
- speaker
- notes

### A veritical Slide

- More class styles at [tailwindcss](https://tailwindcss.com/docs) via
  [UnoCSS](https://unocss.dev/interactive/?s=bg-color)

## More Examples

https://github.com/slidesdown/slidesdown/blob/main/SLIDES.md

---

<h2>The End</h2>

Thank you for your time.

Publish Slides

GitHub Repository

Use the GitHub CLI - gh

gh repo create myslides --public --clone
slidesdown -t
# edit slides ...
git add SLIDES.md
git commit -m "first slideshow"
git push

Now, open the presentation in the online viewer:

xdg-open "https://slidesdown.github.io/?slides=$(gh browse -n)"

GitHub Gist

Use the GitHub CLI - gh

slidesdown -t
# edit slides ...
gh gist create SLIDES.md --public

Now, copy the printed URL into the URL variable and open the online viewer:

URL="https://gist.github.com/..."
xdg-open "https://slidesdown.github.io/?slides=${URL}"

Development

Required Tools

• curl HTTP client
• gh GitHub CLI for creating releases
• git-cliff changelog generator
• just task runner
• node >=20
• yq YAML parser

Folder Structure and Important Files

• published/ build target folder served at https://slidesdown.github.io and used in the docker image
• examples/ contains example presentations
• index.html is the presentation template that gets loaded
• Justfile tasks collection, run just to get the list of tasks
• public/ contains external dependencies (not part of git) and
  • public/loader.html presentation loader served at https://slidesdown.github.io/loader.html
  • public/learn.html tutorial served at https://slidesdown.github.io/learn.html
  • public/plugin/slidesdown.js Markdown converter plugin - this is the core of this project
• slidesdown CLI
• src/ contains various scripts for docker and the HTML page
  • (deprecated!) src/custom-elements.js contains the custom elements that get injected into the presentation, e.g. <v-box></v-box>, <h-box></h-box> and <columns-2></columns-2>

Setup

• Run yarn to install all JavaScript depedencies

Modify Source Code

• Run just update-all to (re)download external dependencies to the public/ folder
• Run just dev to start the vite development server plugin when it gets modified

Build

• Run just build to recreate the docs/ folder
• Run just build-docker to build a new docker image

Release

• Commit all changes
• Run just release to create a new GitHub release, update CHANGELOG.md, and update tag in slidesdown script

References

• mdshow is an older attempt of mine to create simple and fast presentations from Markdown files.
• reveal.js provides the presentation framework that's the basis for slidesdown.