Minimalist Markdown presentations in the terminal.
mdpresent is a small, offline presentation reader for ordinary Markdown files. It turns sections separated by --- into slides, supports terminal-friendly alignment and progressive reveals, and can browse a directory containing multiple decks.
Version 0.1.5 adds MDP Package Format v1: an ordered Markdown book and its images can now travel inside one .mdp file. Legacy deck.md presentation packages remain compatible. No browser, account, cloud service, or presentation database is required.
Sometimes a presentation needs only words, structure, timing, and a quiet screen. Markdown keeps the source readable in any editor, easy to version with Git, and usable long after a particular presentation application disappears.
mdpresent is intended for:
- Minimalist talks and lectures
- Legal, compliance, and technical briefings
- Presentations over SSH or on low-powered computers
- Offline and portable presentation libraries
- Distraction-free teaching and storytelling
- Text-first environments, including bootable USB systems
- Full-screen terminal presentation mode
- Ordinary
.mdfiles and self-contained.mdppackages - Directory-based presentation library and deck selector
- Left, centre, and right alignment
- Top, middle, and bottom vertical positioning
- Headings, paragraphs, lists, quotations, code blocks, and basic tables
- Progressive reveals using
<!-- pause --> - Amber, phosphor, cyan, and monochrome themes
- Slide overview, go-to-slide, blank screen, reload, and optional footer
- Unicode rendering with an ASCII fallback
- Responsive layout when the terminal is resized
- Explicit reader mode with vertically scrollable sections
- Flags accepted before or after the file path
- Optional
mode=readerdeck metadata and a liveMmode toggle - PNG, JPEG, and first-frame GIF images in reader mode
- True-colour half-block image rendering adapted from TermPlayer
- Ordered multi-file books using ordinary Markdown and image folders
- Portable manifest-driven
.mdpbooks with packaged images - Safe in-memory package loading without extracting files onto disk
- Windows, macOS, and Linux builds from one Go codebase
Download the appropriate executable from the repository's Releases page, then run a Markdown deck:
mdpresent.exe examples\why-contracts-fail.mdPoint mdpresent at a directory to open its presentation selector:
mdpresent.exe examplesRunning mdpresent without a path scans the current directory for .md and .mdp files.
Open a sectioned Markdown document in reader mode. The flag may appear before or after the file:
mdpresent --reader book.md
mdpresent book.md --reader
mdpresent book.md -rThe included test documents declare mode=reader, so they also open as books without a flag:
mdpresent examples/reader-demo.md
mdpresent examples/reader-images.md --theme cyanIn reader mode, --- separates scrollable sections. Left and Right move between sections; Up and Down or the mouse wheel scroll within the current section. Press M to switch between reader and presentation mode without restarting.
Open a directory of chapters as one book:
mdpresent --reader gerimis/Without --reader, a directory retains its existing behaviour and opens as a presentation library.
Open a packaged book. Its manifest selects reader mode automatically:
mdpresent Gerimis.mdpGo 1.27 or later is required by the current module file.
go mod download
go test ./...
go build -buildvcs=false -o mdpresent ./cmd/mdpresent
./mdpresent examples/why-contracts-fail.mdWindows Command Prompt:
go mod download
go test ./...
if not exist bin mkdir bin
go build -buildvcs=false -o bin\mdpresent.exe .\cmd\mdpresent
.\bin\mdpresent.exe .\examples\why-contracts-fail.mdSee INSTALL-GO.md for installation guidance.
Separate slides with --- on its own line:
# First slide
Opening text
---
# Second slide
- First point
- Second pointMetadata is placed in an HTML comment, keeping the source valid Markdown in other readers:
<!-- deck: title="My Presentation" author="Kevin Koo" theme=amber mode=present -->Supported themes are amber, phosphor, cyan, and mono. Set mode=reader when the file is a book or notes collection rather than a slide deck.
Place a slide directive near the beginning of a slide:
<!-- slide: align=center valign=middle theme=phosphor -->
# One Question Remains
Who bears the loss?Horizontal values are left, center (or centre), and right. Vertical values are top, middle, and bottom.
Individual blocks can have their own alignment:
::: center
This block is centred.
:::
::: right
— Closing submission
:::# Three Warning Signs
- No defined deadline
<!-- pause -->
- No termination mechanism
<!-- pause -->
- No limit on further workEach forward action reveals the next fragment before advancing to the following slide.
Notes are retained in the deck but hidden during the presentation:
<!-- notes:
Explain the factual background without naming the client.
-->Basic GitHub-style Markdown tables are supported. The column markers also control terminal alignment:
| Risk | Exposure | Priority |
|:------|:--------:|---------:|
| Delay | High | 1 |Very wide cells are shortened with an ellipsis to keep the table within the terminal.
Reader mode recognises ordinary standalone Markdown images:
PNG, JPEG, and GIF files are decoded directly by Go. GIF files display their first frame. Relative paths are resolved from the Markdown file's directory. Images are scaled to the available content width, converted to true-colour half blocks, and cached for scrolling. -no-color and -ascii show a text placeholder instead.
Version 0.1.5 still renders images only in reader mode. Images may now come from either an ordinary book directory or an .mdp package.
A book can be distributed as an ordinary folder:
gerimis/
├── chapter-1.md
├── chapter-2.md
├── chapter-10.md
└── images/
└── rain.png
Run mdpresent --reader gerimis/ to open it as one book. Only .md files immediately inside the selected directory become chapters; image folders and other files are ignored. Chapter names are sorted naturally, so chapter-2.md comes before chapter-10.md. Each chapter may contain multiple --- sections and may reference images relative to its own location.
The directory name becomes the book title. O opens the combined section overview, Left and Right cross chapter boundaries, and R reloads the directory so newly added chapters are discovered. Prefixing filenames with padded numbers such as 001-, 002-, and 100- remains recommended because it is also predictable in file managers and archive tools.
| Key | Action |
|---|---|
| Right, Down, Space, Enter, Page Down | Reveal or next slide |
| Left, Up, Backspace, Page Up | Previous reveal or slide |
| Home / End | First / last slide |
G |
Go to a slide number |
O |
Open the slide overview |
B |
Blank the screen |
F |
Toggle the footer |
R |
Reload the deck from disk |
M |
Switch to reader mode |
? |
Show help |
Escape or Q |
Exit with confirmation |
| Key | Action |
|---|---|
Up / Down, K / J |
Scroll by line |
| Page Up / Page Down | Scroll by viewport |
Left / Right, H / L |
Previous / next section |
| Home / End | Top / bottom of current section |
| Ctrl+Home / Ctrl+End | First / last section |
G |
Go to a section number |
O |
Open the section overview |
F |
Toggle the footer |
R |
Reload the document |
M |
Switch to presentation mode |
| Mouse wheel | Scroll the current section |
Escape or Q |
Exit with confirmation |
An .mdp file is a ZIP-compatible container for one presentation or one ordered book. New packages use a root-level mdpresent.json manifest:
Gerimis.mdp
├── mdpresent.json
├── chapters/
│ ├── 001-prologue.md
│ └── 002-first-rain.md
└── images/
└── station.png
The manifest declares kind: "book" and lists chapters in their authoritative order. Relative image paths are resolved inside the package. Existing packages containing deck.md without a manifest remain presentation packages.
Version 0.1.5 does not yet include a package compiler. Zip the contents of a correctly structured source directory and rename .zip to .mdp. See MDP.md for the complete format, security limits, compatibility rules, and manual packaging instructions. A future mdpresent pack command will automate this process.
mdpresent [options] [deck.md | deck.mdp | directory]...
mdpresent [deck.md] [options]
-r, --reader
read sections or an ordered chapter directory
-p, --present
force presentation mode
--mode string
reader, present, or auto (default auto)
--theme string
override theme: amber, phosphor, cyan, or mono
--no-color
disable ANSI colours
--ascii
use ASCII borders and symbols
-V, --version
print version and exit
-h, --help
show help
Flags may appear before or after the path. --mode auto (the default) honours <!-- deck: mode=reader --> when that metadata is present.
Windows:
mkdir bin
go build -buildvcs=false -trimpath -ldflags "-s -w" -o bin\mdpresent.exe .\cmd\mdpresentCross-compile from macOS or Linux:
mkdir -p bin
GOOS=windows GOARCH=amd64 go build -buildvcs=false -trimpath -ldflags="-s -w" -o bin/mdpresent.exe ./cmd/mdpresent
GOOS=linux GOARCH=amd64 go build -buildvcs=false -trimpath -ldflags="-s -w" -o bin/mdpresent-linux-amd64 ./cmd/mdpresent
GOOS=darwin GOARCH=arm64 go build -buildvcs=false -trimpath -ldflags="-s -w" -o bin/mdpresent-macos-arm64 ./cmd/mdpresentUnsigned, newly built executables may be inspected by reputation-based antivirus software. Building from source provides the most direct way to verify what is being run. Do not disable antivirus protection globally.
The presentation workflow remains the core product. Version 0.1.1 introduced reader mode; version 0.1.2 added static inline images; version 0.1.3 hardened mode selection; version 0.1.4 added ordered multi-file books; version 0.1.5 adds portable illustrated MDP book packages.
See ROADMAP.md for the reader-mode boundary, image roadmap, and decision criteria.
Version 0.1.5 is an illustrated multi-file and packaged-book reader suitable for experimentation with book-length collections. Video, animation, scripting, remote control, and web export remain out of scope.
Copyright © 2026 Kevin Koo Seng Kiat. Developed with assistance from OpenAI's ChatGPT and xAI's Grok.
The version 0.1.2 half-block image renderer is adapted from Kevin Koo's TermPlayer project, developed with assistance from Microsoft Copilot, Gemini, and Grok.
Built with Bubble Tea and Charm ANSI.
Copyright © 2026 Kevin Koo Seng Kiat.
Licensed under the MIT License.