Turn any Markdown file into a live, presentable browser deck — with no slide software, no export step, and no leaving your editor.
Write your design docs, runbooks, and team updates in plain Markdown. Run one command, and it becomes a responsive, keyboard-navigable slide deck in your browser that updates the moment you hit save.
# Install with one command
curl -fsSL https://raw.githubusercontent.com/SXsid/mdslides/main/install.sh | bash
# Serve your presentation
mdslides presentation.mdmdslides is distributed as a single static binary with zero runtime dependencies. There is no Node.js, no npm, no bundler, and nothing phoning home.
Design docs and READMEs already contain the primary content of technical presentations: headings, structured narrative, tables, and architectural diagrams. Recreating this content in slide presentation software produces duplicate work, and as soon as documentation changes, slides drift out of date.
mdslides removes the duplication entirely. Your Markdown file remains the single source of truth, editable in whatever editor you prefer, while automatically rendering as a presentation-grade deck.
- Headings as Slides: Every primary heading (
#) automatically begins a new slide. - Automatic Bento Layouts: Standalone images configure themselves. One image sits beside your text; two stack; three and four assemble into balanced bento grids. More than four flow into continuation screens under the same heading.
- Real-Time Live Reload: When you save your Markdown file in any text editor, the connected browser updates instantly via Server-Sent Events.
- Native Mermaid Diagrams: Fenced code blocks with
mermaidrender as live vector diagrams on load instead of raw code. - Full GitHub-Flavored Markdown: Tables, task lists, code blocks, blockquotes, and strikethrough render with clean, professional typography.
- Integrated Theme System: Automatic support for OS light and dark color schemes, with manual keyboard toggles and persistent preferences.
- Single Self-Contained Binary: All HTML templates, CSS styles, and ES modules are embedded via Go
embed. Copy the binary anywhere and run.
Download and install the pre-compiled binary matching your operating system and architecture:
curl -fsSL https://raw.githubusercontent.com/SXsid/mdslides/main/install.sh | bashPre-compiled standalone binaries are available for Linux, macOS, and Windows from GitHub Releases:
| Platform | Architecture | Binary Name |
|---|---|---|
| Linux | x86_64 (amd64) |
mdslides |
| Linux | ARM64 (arm64) |
mdslides |
| macOS | Apple Silicon (arm64) |
mdslides |
| macOS | Intel (amd64) |
mdslides |
| Windows | x86_64 (amd64) |
mdslides.exe |
| Windows | ARM64 (arm64) |
mdslides.exe |
For complete release verification steps, see docs/DISTRIBUTION.md.
If Go is installed on your workstation:
go install github.com/SXsid/mdslides/cmd/mdslides@latestgit clone https://github.com/SXsid/mdslides.git
cd mdslides
make buildCreate a new Markdown file, for example talk.md:
# High-Throughput Stream Processing
We redesigned our pipeline architecture to handle
500,000 events per second with sub-10ms latency.
- Zero-copy deserialization
- Partition-aware buffering
- Dedicated worker thread pools
---
# Verification Benchmarks
| Ingestion Engine | Throughput (msg/s) | p99 Latency |
|---|---|---|
| Legacy Pipeline | 42,000 | 185ms |
| New Architecture | 512,000 | 7.8ms |
---
# Cluster State Machine
```mermaid
graph LR
Ingest[Ingest Gateways] --> Queue[Kafka Partitions]
Queue --> Engine[Stream Engine]
Engine --> Storage[(LSM Storage)]
```Start the presentation server:
mdslides talk.mdYour browser will open http://localhost:8080/ automatically. As you edit talk.md, your browser updates whenever you save.
mdslides <file.md> [flags]
| Flag | Default | Description |
|---|---|---|
-port |
8080 |
Port number to serve the presentation on |
-no-open |
false |
Do not launch the default web browser automatically |
-version, -v |
false |
Print binary version information and exit |
| Key / Action | Function |
|---|---|
→ or Space |
Advance to the next slide |
← |
Return to the previous slide |
Home / End |
Jump to the first or last slide |
F |
Toggle fullscreen presentation mode |
T |
Toggle light / dark theme |
? |
Toggle keyboard shortcuts cheat sheet |
Esc |
Close shortcuts cheat sheet |
The floating control bar (HUD) at the bottom of the screen provides quick access to slide navigation, fullscreen mode, theme toggles, and help dialogs.
mdslides interprets standard Markdown constructs to determine presentation layout:
- Headings (
#): Each top-level heading begins a new slide. - Thematic Breaks (
---): Force a page split under the current heading. - Image Positioning: Standalone images are extracted from text flow and organized automatically based on count (1-4 images) and source order.
- Diagrams: Fenced
```mermaidblocks are rendered as vector graphics.
For comprehensive examples and layout guidelines, read the Slide Authoring Guide.
mdslides is engineered with strict package boundaries and single-responsibility components:
[Markdown File]
|
v
markdown.ParseFile -- goldmark (+GFM) AST traversal. Emits Deck structure.
|
v
layout.Classify -- Pure function: image count and order -> grid classification.
|
v
render.HTML -- Deck + layout decisions -> single self-contained HTML document.
|
v
server.Server -- Serves HTML, monitors directory, broadcasts SSE reloads.
|
v
[Web Viewer Client] -- Modular ES scripts: nav, theme, live-reload, diagrams, shortcuts.
- Clean Layering: Knowledge flows strictly downward.
layoutandmarkdownhave zero awareness of HTML or HTTP. - Minimal Interfaces: The only interface in the codebase is
SourceWatcher, which abstracts filesystem notifications to enable fast unit testing with synthetic watchers. - Zero Cache Invalidation: The server re-parses source files on each request, ensuring live reload is always synchronized with disk state.
For deeper technical details, refer to:
- docs/ARCHITECTURE.md — Internal package design, pipelines, and extension points.
- docs/HLD.md — High-level product and layout design decisions.
- docs/DISTRIBUTION.md — Cross-platform compilation, release packaging, and distribution workflows.
make check # Run formatting checks, vet, unit tests, and build
make demo # Build and serve testdata/sample.md
make dist # Cross-compile binaries for Linux, macOS, and Windows
make release-local # Package compressed archives with SHA-256 checksumsAll contributions should maintain package boundaries, pass make check, and adhere to clean, professional documentation standards without emojis.
MIT License. See LICENSE for details.