# maaslalani/slides: present Markdown decks in a terminal over SSH

> A Go terminal presentation tool that renders Markdown, executes code blocks and can serve a deck over SSH. It suits engineers who present from a shell, not people who need a browser editor.

**maaslalani/slides** — Terminal based presentation tool

- Repository: https://github.com/maaslalani/slides
- Website: http://maaslalani.com/slides/
- Stars: 11,670 · Forks: 315
- Language: Go
- License: MIT
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/maaslalani-slides

## What maaslalani/slides replaces, and for whom

Most presentation software assumes a graphical environment. You open an editor, drag a text box, and export a file that only that application renders faithfully. slides takes the opposite position: the deck is a Markdown file, the renderer is a terminal, and the separator between slides is a horizontal rule. If you already write documentation in Markdown, the authoring step costs nothing new.

The audience is narrow on purpose. It fits engineers who present to other engineers, maintainers who want a talk stored next to the code it describes, and anyone who has to present on a remote machine where installing a desktop application is impractical. The README frames the pitch directly: create slides and present them without leaving your terminal.

It is a poor fit for a marketing deck, a conference keynote with animations, or anything a non-technical colleague must edit. There is no visual editor and no canvas. The file is text, and the output depends on the terminal emulator, the font and the color profile of whoever is watching.

## How slides renders a Markdown file into a deck

The mechanism is a pipeline rather than a document model. slides reads a Markdown file, splits it on horizontal rules into slides, and hands each slide to the glamour library for styling. The repository pins github.com/charmbracelet/glamour v1.0.0 in go.mod, and the theme option points at a glamour theme JSON, either a local path or a remote URL that slides fetches before presenting.

The interface layer is Bubble Tea, the terminal UI framework from the same ecosystem, visible in go.mod as charm.land/bubbletea/v2. Navigation, search and the footer are all part of that model. The footer content comes from the metadata block at the top of the file: author, date and paging, where paging accepts %d directives for the current and total slide numbers.

Two features sit outside plain rendering. Code execution runs a fenced block on the current slide when you press ctrl+e and shows the output as virtual text. Pre-processing is the more interesting one: a block opened with three tildes names a command, the block contents are piped to that command as stdin, and the stdout replaces the block before the slide is displayed. That turns a diagram description into an ASCII diagram at load time.

There is a guard on pre-processing. The documentation states that the file must have execution permissions before slides will pre-process it, added with chmod +x file.md. That is a deliberate gate, not a bug, and it means a deck you download from someone else will not run commands until you decide it should.

## Installing slides and presenting a first deck

The README lists several installation routes. Homebrew covers macOS, yay covers Arch, and there is a Nixpkgs entry, a Snap package for any Linux distribution running snapd, and a Go install for anyone with a toolchain. Pick the one that matches your machine.

```bash
brew install slides
```

On Arch the equivalent is yay -S slides, and on a snapd system it is sudo snap install slides. If you prefer building from source, the Go route is:

```bash
go install github.com/maaslalani/slides@latest
```

Now write a deck. A horizontal rule separates one slide from the next, and a YAML block at the top sets the footer metadata.

```markdown
---
theme: ./path/to/theme.json
author: Gopher
date: MMMM dd, YYYY
paging: Slide %d / %d
---

# Welcome to Slides
A terminal based presentation tool

---

## Everything is markdown
In fact, this entire presentation is a markdown file.
```

Run it by passing the file name. According to the README, slides watches the file for changes and updates the presentation live, so you can edit in one pane and watch the deck in another.

```bash
slides presentation.md
```

Inside the presentation, space, the right arrow, enter, n, j and l all advance. A number followed by any of those keys jumps forward that many slides, and a number followed by G goes to a specific slide. Pressing / opens search, which the README says treats the term as a regular expression, with /i for case-insensitive matching. ctrl+n moves to the next result. The repository also ships examples/ with files such as code_blocks.md, preprocess.md and metadata.md, which are the fastest way to see each feature in a working deck.

## Serving a deck over SSH instead of installing slides on the viewer's machine

The feature that distinguishes slides from other terminal Markdown viewers is slides serve. Run it on the machine that holds the file, and the README says the command prints a port. A viewer then connects with an ordinary SSH client, no slides binary and no copy of the presentation required.

```bash
slides serve presentation.md
```

```bash
ssh 127.0.0.1 -p 53531
```

The README gives 127.0.0.1 and port 53531 as the example, so treat both as illustrative rather than fixed. The repository depends on charm.land/wish/v2 and github.com/charmbracelet/ssh, which is the SSH server library this is built on. The practical consequence is that the viewer's terminal does the rendering, so the deck looks the way their font and color settings allow, not the way yours do. It also means the presentation is only reachable while the serve process is running on that host.

## Where slides breaks down

Code execution is the sharpest edge. Pressing ctrl+e on a slide with a code block runs that block on your machine. The README does not document a sandbox, a confirmation prompt, or a language allowlist. A deck is therefore executable content, and the pre-processing guard (the chmod +x requirement) exists precisely because the maintainers know it. If you plan to open decks from other people, read the file first. That is not paranoia; it is the same rule you apply to a shell script.

The terminal is the second constraint. Layout depends on the viewer's window size and font metrics, and there is no fixed canvas. A slide that looks right on your 120-column terminal may wrap badly on a projector driven by a laptop with different settings. There is no speaker view, no presenter notes pane, and no animation model, so anything that depends on timing or on a second screen is out of scope.

Maintenance is the third thing to weigh. The most recent release listed is v0.9.0 from 2022-09-13, while the last push to the repository was on 2026-07-08. That gap is worth understanding before you build a workflow around it: the code is moving, but the tagged release line has not, so a Go install pulls current main rather than the v0.9.0 artifact. The README also does not document a rollback path or a compatibility policy between versions.

## How slides differs from lookatme and from browser-based decks

The README credits lookatme as the project's inspiration, and the two solve the same problem from different directions. lookatme is a Python tool, so it installs through the Python packaging ecosystem and inherits that runtime. slides is a single Go binary, which means no interpreter to manage and a straightforward path to dropping it on a machine that has no package manager for Python. The trade-off runs the other way too: a Python project can lean on Python libraries for extensions, while slides is bounded by what its Go dependencies expose, and its theming is limited to glamour theme JSON files.

Against browser-based presentation tools the difference is starker. A browser deck gives you a visual editor, a shareable link, and an audience that needs no instructions. slides gives you a text file in version control, a diffable history of your talk, and an audience that already has a terminal. The README's own example of piping a deck in makes the point: curl http://example.com/slides.md | slides turns any URL serving Markdown into a presentation. You cannot do that with a binary slide format.

## Licence, upgrade cost and what to check before adopting

slides is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, and it is the same licence used by most of the Go terminal ecosystem it depends on. This is a description of the licence text, not legal advice; if you are redistributing a modified binary inside a product, have your own counsel read the notice requirements.

The upgrade cost is where the release history matters. Because v0.9.0 dates from 2022-09-13 and the last push is 2026-07-08, the two ways of installing slides are not equivalent. A package manager such as Homebrew or Snap ships whatever version the maintainer of that formula or snap last published, while go install github.com/maaslalani/slides@latest pulls the current module. If you need a reproducible build, pin the module version explicitly rather than relying on @latest, and check which version your distribution channel actually carries. The Makefile in the repository is small: make runs the deck in examples/slides.md, make test runs go test ./... -short, and make build produces a slides binary. Those three targets are the whole build surface.

## Conclusion

Adopt slides if your decks are Markdown, your audience is comfortable in a terminal, and you want code blocks that execute in place or a deck reachable with ssh 127.0.0.1 -p 53531. Do not adopt it if you need a browser editor, speaker notes, or a GUI that non-technical viewers can drive. Before committing, check the last push date against the release history and confirm that every code block you intend to run is a language the tool can execute on your machine.

## FAQ

### How do I install slides on my machine?

The README lists brew install slides for macOS, yay -S slides on Arch, nix-env -iA nixpkgs.slides for Nixpkgs unstable, sudo snap install slides on any Linux distribution running snapd, and go install github.com/maaslalani/slides@latest for a Go toolchain. Binaries are also published on the releases page.

### How do I use slides to present a Markdown file?

Write a Markdown file with horizontal rules between slides, then run slides presentation.md. If you pass a file name, slides watches it for changes and updates the presentation live, and it also accepts input through stdin, so curl http://example.com/slides.md | slides works.

### Can slides run the code inside a code block?

Yes. Pressing ctrl+e on a slide that contains a code block executes it and displays the result as virtual text on the screen. The README does not describe a sandbox or a confirmation step, so a deck should be treated as executable content.

### What is pre-processing in slides and why does it need chmod +x?

A block opened with three tildes names a command; the block's contents are passed to that command as stdin and the stdout replaces the block before the slide is shown. The documentation states that the file must have execution permissions for this to happen, added with chmod +x file.md, as a security measure.

### Can someone view a slides presentation without installing slides?

Yes, if you run slides serve presentation.md on the host that has the file. The README then shows connecting with ssh 127.0.0.1 -p 53531, so a viewer with only an SSH client can see the deck. The serve process must be running for the presentation to be reachable.

## Sources

- [License: MIT](https://github.com/maaslalani/slides/blob/main/LICENSE)
- [maaslalani/slides on GitHub](https://github.com/maaslalani/slides)
- [Project website](http://maaslalani.com/slides/)
- [README](https://github.com/maaslalani/slides/blob/main/README.md)
- [Releases](https://github.com/maaslalani/slides/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/maaslalani-slides