Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jceb/mdshow

Turn markdown files into beautiful presentations quickly
https://github.com/jceb/mdshow

fontawesome markdown markup pandoc presentations revealjs slides slideshow

Last synced: 11 days ago
JSON representation

Turn markdown files into beautiful presentations quickly

Awesome Lists containing this project

README

        

# WARNING: This project is discontinued.

A replacement has been started with https://github.com/jceb/slidesdown.

# `mdshow`

> Turn markdown files into beautiful presentations quickly.

`mdshow` is built to quickly turn ideas into beautiful presentations.

The tool of choice for capturing ideas is the text-based
[Markdown](https://daringfireball.net/projects/markdown/) format. The
heavy lifting of making text beautiful is left to
[reveal.js](https://revealjs.com/), a popular web presentation framework.
`mdshow` does the work in between of turning text into a presentation.

[![](assets/screenshot400.png)](https://youtu.be/ZNXvQGsk_wA)

- [Introduction video to mdshow](https://youtu.be/ZNXvQGsk_wA)
- [Example HTML presentation](https://mdshow.e-jc.de/)
- [Example PDF](./examples/slides.pdf)
- [Example Markdown](https://raw.githubusercontent.com/jceb/mdshow/master/examples/slides.md)

## Table of Contents

- [Features](#features)
- [Background](#background)
- [Install](#install)
- [Usage](#usage)
- [Maintainers](#maintainers)
- [Contributing](#contributing)
- [License](#license)

## Features

- Built with [reveal.js 4.0](https://revealjs.com/) and [pandoc
2.9](https://pandoc.org/)

### Focus

- Minimally invasive. All data is kept in `slides.md`, `assets/`, and a
temporary `.build/` folder
- Markdown as the sole markup to focus on

### Enterprise

- Custom themes and reuse of themes across all presentations
- Default settings across all presentations
- Custom settings per presentation
- Live-reload of changes
- PDF conversion

### Setup

- Scaffolding for a quick start (run `mdshow scaffold` to create )
- Auto-generated title slide
- Usable default settings

### Presentation

- [Font Awesome](https://fontawesome.com/) integration
- [chart.js](https://www.chartjs.org) integration
- Multiple columns per slide
- Syntax highlighting for source code
- Incremental display of bullet points and other fragments
- Zoom into slide (press `` or `` to zoom)
- Separate speaker notes view (press `` to show)
- Slide overview and navigation (press `` to enter overview and
`` to show selected slide)

## Background

I've been using various markup formats like org-mode, asciidoc and
markdown extensively and for professional purposes, e.g. writing a
thesis, publishing documentation or keeping notes. However, for
presentations I usually revert back to MS PowerPoint and Libreoffice
Impress although web browsers are obviously way better at presenting
content!

While PowerPoint & Co. get the job done, plain text is so much faster
and more usable to me. For example, I can keep it in a repository to
track revisions + use all the git infrastructure that exists around
sharing content.

While plain text is faster, I had a hard time finding tools that would
make it easy for me to concentrate on creating content. Furthermore, the
*speed* of tools is very important to me. On the side of functionality I
value *theming*, esp. across multiple presentations as well as *no
clutter* in my presentation directory.

I took lots of inspiration from
[markdeck](https://github.com/arnehilmann/markdeck) that I've been using
successfully for a few years. I like the full-featured approach of
markdeck and aim to bring many of its features to `mdshow` following an
opinionated path.

## Install

### Prerequisites

- `autoconf`
- `automake`
- `curl`
- `g++`
- `gcc`
- `make`
- `pandoc`, suggest version 2.9.x
- `unzip`

### Installation

Download the program:

```
curl -LO https://raw.githubusercontent.com/jceb/mdshow/master/mdshow
```

Copy the `mdshow` program to a directory in `$PATH` and make it
executable:

```
chmod a+x mdshow
```

Test and download dependencies:

```
mdshow setup
```

## Usage

Create a new presentation in a new directory:

```
mdshow scaffold
```

The command will create a `slides.md` file and an `assets` directory.
Place all assets like pictures in the `assets` directory. The content of
the presentation lives in `slides.md`.

Display the presentation in a [browser](http://localhost:3000) with
live-reload:

```
mdshow serve
```

If you want to use a different file name pass it to mdshow via the
`SLIDES` parameter:

```
mdshow serve SLIDES=custom.md
```

Convert the presentation to a PDF file (make sure `mdshow serve` is
running before executing the following command):

```
mdshow pdf
```

Convert the presentation to a single, self-contained HTML file (make
sure `mdshow serve` is running before executing the following command):

ATTENTION: this command fails to include images that are added to a
slide via `data-background-image` attribute.

```
mdshow html
```

More commands and information:

```
mdshow help
```

## Maintainers

[@jceb](https://github.com/jceb)

## Contributing

PRs accepted.

Small note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification.

## License

Apache-2.0 2020 Jan Christoph Ebersbach