Using markdown, write simple but beautiful presentations with math, animations and media, which can be visualized in a web browser or exported to PDF.

See the official git repository hosted on Gitlab or the Github mirror.

This program appropriately inserts markdown files into Reveal.js files, completely avoiding the need to edit HTML files directly.

Live demo

See for yourself: check out the live demo (and the source file presentation.md).

Installation

python -m pip install git+https://gitlab.com/da_doomer/markdown-slides.git

Markdown-slides works with Python >= 3.8.

Don't have python? Your version of python not working? Scroll down to fearless, conflict-free Python installation.

Usage

mdslides [-h] [--include RESOURCE] [--pdf] [--output_dir DIR] FILE

where

• RESOURCE: any file or directory that should be included (e.g. a directory with pictures and videos)

• FILE: input markdown file.

• DIR: output directory. Defaults to a new directory in the working directory with the same name as the input file, but without suffix.

Notes:

• PDF exporting requires chromium (see PDF exporting on reveal-js).

QuickStart Example

1. Install markdown-slides

2. Download the example presentation.md folder

    wget "https://gitlab.com/da_doomer/markdown-slides/-/archive/master/markdown-slides-master.zip?path=example"; unzip markdown-slides-master.zip\?path=example; cd markdown-slides-master-example/example;

3. Render the slide deck into a web page, including the media folder

   mdslides ./presentation.md --include media

4. Open the slides in your browser (or publish to github pages)

   open ./presentation/index.html

Syntax:

You will probably only need to break slides:

# My title
A subtitle maybe

[comment]: # (!!!)

Second slide. Easy :D

Other options are documented in the example presentation presentation.md.

If you need a quick refresher on markdown see e.g. this cheatsheet, the CommonMark reference page, or this Gfm tutorial.

You will not have to break your markdown files to use this program. Control Reveal.js' theme and options using CommonMark-compliant comments.

Everything but slide-break comments and option comments is passed to Reveal.js verbatim. Check out their documentation, especially the markdown section.

Features

Some of Reveal.js's features are:

• LaTeX math syntax.
• Automatic animations.
• Background videos and images.

Keep in mind you need an Internet connection to render equations (see issue #9).

Troubleshooting

If you encounter any issues or have some questions, open an issue on Gitlab or on Github.

Comments and pull requests are very welcome!

Fearless, Conflict-free Python installation

Markdown-slides works with Python 3.9 or newer.

Here's a fearless, conflict-free python install that Just Works™ in bash, zsh, and fish:

1. Webi will install pyenv (the python version manager) to ~/.pyenv, where it won't conflict with your system python, or any projects:

   curl -sS https://webinstall.dev/pyenv | bash
2. After installation you'll need to CLOSE and RE-OPEN your terminal, or update your PATH:

   export PATH=~/.pyenv/bin:"$PATH"
   export PATH=~/.pyenv/shims:"$PATH"
3. Now you can install Python v3.9.1 (safely in ~/.pyenv):

   # Install v3.9.1, which works with mdslides
   pyenv install -v 3.9.1
4. When you need to use mdslides, use pyenv to set your SHELL's python to 3.9.1: (and you can set it right back afterwards)

   # Switch to python 3.9.1, conflict free
   pyenv global 3.9.1
   
   # Install and use mdslides
   
   # Switch to your original system python
   pyenv global system

Bonus: You can tell pyenv to automatically pick Python 3.9.1 whenever you're in your slides folder:

cd ./path/to/my/presentations/
pyenv local 3.9.1

# the presentations folder is now set to use python 3.9.1
cat ./.python-version # 3.9.1
python --version
Python 3.9.1

cd -
python --version
Python x.x.x