mdp: a Markdown file turned into a terminal slide deck

Horizontal rulers are the only slide separator

mdp reads a single Markdown file and renders it full screen, and it has no slide syntax of its own. The split happens on horizontal rulers: text above the first `---` is slide one, and every further ruler opens the next slide. There is no per-slide metadata block, no notes field and no way to set a background, so a deck stays a plain text file with rules where the breaks go.

Headers prefixed with `@` are treated separately from the body. The first two lines of that kind are shown as the title in the top bar and the author in the bottom bar, which is how the bundled `sample.md` gets its name on screen. The README does not say what happens to a third `@` line, so treat two as the ceiling.

Choosing a Markdown element as the delimiter has a consequence worth knowing before you write anything: a thematic break inside a slide cannot exist. No escape for a `---` that should not start a new slide is documented.

The Makefile picks its curses library from uname

mdp is one C binary built from every `.c` file in `src/` and linked against a curses library that the Makefile chooses before anyone edits anything:

CURSES  = ncursesw
LDFLAGS ?= -s
CFLAGS   ?= -O3
CFLAGS   += -Wall
LDLIBS   = -l$(CURSES)

The default is `ncursesw`, the wide character build, which is also what the README asks you to have as installed headers. Two branches override it, and both are indented with tabs in the file:

ifeq ($(UNAME_S),Darwin)
	CURSES := ncurses
	LDFLAGS :=
endif

On Darwin the library drops to plain `ncurses` and the `LDFLAGS` assignment is cleared, so a build on macOS is not a build on Linux even though the source is identical. On Windows the recipe switches to `pdcurses` when `OS` reports `Windows_NT` and `uname` does not report `CYGWIN`, which leaves the Cygwin path on `ncursesw`. Release defaults are `CFLAGS` at `-O3` plus `-Wall` and an `LDFLAGS` of `-s`; passing `DEBUG=1` replaces both with `-fsanitize=address -O0 -Wall -g` and drops the strip.

libncursesw headers, then make, then mdp sample.md

The dependency comes before the build: mdp needs the ncursesw headers to compile, and the package names differ per distribution. On Raspbian that is `libncurses5-dev` plus `libncursesw5-dev`, on Fedora it is `ncurses-devel` plus `ncurses-c++-libs`. Without them the compiler has no curses declarations to work with.

From a checkout, the whole path is five commands:

git clone https://github.com/visit1985/mdp.git
cd mdp
make
make install
mdp sample.md

The recursive `src` target descends into the source directory, the `install` target copies the binary to `$(BINDIR)` and the `mdp.1` man page to `$(MANDIR)/man1`, and `mdp sample.md` opens the bundled deck in a full screen view. `PREFIX` defaults to `/usr/local`, and `DESTDIR` exists so a packager can stage into a temporary root.

Not compiling is also documented. The README offers `apt-get install mdp` on Debian and Ubuntu, `brew install mdp` or `sudo port install mdp` on macOS, `sbopkg -i mdp` on Slackware, a FreeBSD port at `misc/mdp`, and a Cygwin package from the setup program. One setting is worth doing by hand on any of them, because the colour fading depends on it:

export TERM=xterm-256color

A terminal capable of 256 colours still renders a reduced palette when `TERM` says otherwise.

config.h needs a recompile, and colours only work in 8 color mode

Configuration is a header, not a runtime file. The `config.h` in `include/` is edited and the project recompiled, and those settings cover colours, keybindings and list types. That is the whole surface: there is no per-user rc file, no command line option to remap a key, and no way to change anything without a toolchain and a rebuild. A hand-tuned `config.h` also stops matching what the distribution ships, so the next package upgrade hands your custom keymap back to you unchanged.

The colour paragraph has a wrinkle. The README states that configuring colours only works in 8 color mode, while the feature it promotes, fading, wants a terminal in 256 colour mode through `TERM=xterm-256color`. Those are two different terminal modes, so a custom palette and the fade are not something you get in the same session as written. If you need to know which mode you ended up in, nothing in the README answers it, and the `docs/` directory is the only pointer given for anything past this page.

Number keys stop at slide 9 and there is no presenter view

The default control set is printed in the README and small on purpose. `h`, `j`, `k`, `l`, the arrow keys, Space, Enter, Backspace and Page Up or Page Down move one slide at a time. Home or `g` jumps to the first slide, End or `G` to the last, `q` exits, and `r` reloads the input file from disk.

`r` is the key that shapes how people work with this tool. The deck is a text file, so you can keep it open in an editor, fix a bullet, save, and press `r` in the terminal to see the change without restarting.

The limit is the range a keyboard gives you. Numeric shortcuts run from `1` to `9`, so slide 40 of a long deck is reached by paging forward or by jumping to the end and walking back. There is no presenter view, no timer, and no second screen, because the process owns one terminal grid and draws the entire deck into it. Anything that needs the audience display and the speaker display to differ is outside what this program can do.

No tagged releases, so upgrades come from a package or a rebuild

The repository has no GitHub releases, which leaves no version to pin and no changelog to read before replacing an installed binary. The last push was on 2026-09-09. Two upgrade paths remain: take whatever the distribution package holds, which on Debian and Ubuntu is `apt-get install mdp`, or follow the `master` branch that the clone in the README pulls.

Rebuilding is cheap and reversible. `make clean` recurses into `src/`, removes the binary and drops `tests/__pycache__`. `make test` runs the suite through `python3 tests/test_c`, so a machine without Python 3 can compile mdp but cannot run its tests. The `install` target places exactly two files, the binary at mode 755 and `mdp.1` at mode 644, and `uninstall` removes exactly those paths, which keeps a local install from colliding badly with a packaged one.

The root also holds `mdp.cygport`, `COPYING`, `AUTHORS` and `CREDITS`. The licence is GPL-3.0, and `COPYING` is the text to read before you distribute a binary you built yourself, especially after editing `config.h`.

A closed list of Markdown, and nothing for images or tables

The formatting on offer is short and specific. Line wide it handles headlines, code, quotes and unordered lists. Inline it handles bold text, underlined text and code. That is the whole list. Tables, images and ordered lists are absent from it, and the README does not document them. `sample.md` is the only worked example in the repository, and it is worth reading before authoring a deck rather than after the first bad slide.

This is where the approach separates from browser based slide tools. Those compile Markdown into HTML and let the browser resolve layout, so an image tag or a table is markup the page handles. mdp draws into a terminal grid through ncurses. What that buys is a deck that runs over ssh with nothing installed on the viewer's machine. What it costs is every element needing a richer renderer, and a talk built around a chart or a screenshot is the wrong shape for it.

Editorial conclusion

mdp is a good choice for a developer giving a short deck from a terminal, and a poor one for a talk that needs images, tables or a presenter view. Decide between the distro package and a clone of master first, then confirm that the terminal you will present from reports 256 colours through TERM, since the colour fading and the custom palette in config.h sit in different terminal modes.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. visit1985/mdp on GitHub