Documentation_

Install

Keynope 0.1.4 supports macOS 14 Sonoma or later on Intel and Apple silicon. For the native editor and automatic updates, install Keynope from the Mac App Store:

Download on the Mac App Store ↗

For the native app and the keynope CLI together, use Homebrew:

brew tap keynope/keynope
brew trust keynope/keynope
brew install --cask keynope

Without Homebrew, the direct installer places Keynope.app in ~/Applications, installs the CLI and presenter helper under ~/.keynope/bin, and adds that directory to your shell's PATH. No sudo is needed.

curl -fsSL https://keynope.sh/install | sh &&
export PATH="$HOME/.keynope/bin:$PATH"

Upgrade an existing installation with:

brew update
brew upgrade --cask keynope

Build from source

Source builds require Go and Xcode Command Line Tools. From the repository root:

make build app
bin/keynope examples/example-deck.md

make build app creates bin/keynope, bin/KeynopePresenter.app, and bin/Keynope.app. Local builds are ad-hoc signed and can require Screen Recording permission again after rebuilding.

Your first deck

Run Keynope without a filename to open the startup menu. Choose New to create a starter deck or Open to choose an existing Markdown file.

keynope
keynope talk.md

Keynope begins in its visual terminal workspace. Press p to send the live presentation signal to the presenter, arrow keys or Space to advance, and ? whenever you need contextual help.

Deck format

A deck remains a readable Markdown file. A line containing --- separates slides. Headings, paragraphs, lists, fenced code, and Markdown images become selectable slide elements.

<!-- keynope width=160 height=45 -->

# Opening statement

The point you want remembered.

- Evidence one
- Evidence two

---

# Live code

```go
fmt.Println("hello, room")
```

Authored dimensions

The leading keynope width/height metadata records the terminal grid in which the deck was designed. Presentation surfaces and --export preserve these dimensions. Avoid removing it after you have positioned elements.

Images and links

![Architecture](architecture.png)
[Project repository](https://github.com/keynope/keynope)

Relative image paths resolve from the deck directory. GIF and WebP animations play in the terminal and exported presentation. Use the visual editor for placement, scale, glyph style, brightness, sharpness, layering, and links; Keynope persists those choices as compact HTML comments and image query parameters.

Generated metadata

Master definitions, slide layouts, speaker notes, page-number policy, visual properties, and exact placement are stored inside comments. They remain invisible to ordinary Markdown viewers. Prefer editing this metadata through Keynope rather than by hand.

Visual editor

Keynope’s editor is keyboard-first but mouse-aware. Press Tab or Shift-Tab to move through elements, use arrows to move a selection, and press Enter to edit selected text.

Editing and history

Type to edit, Enter commits, and Escape cancels. Use Ctrl-Z and Ctrl-Y for undo and redo. Copy, cut, and paste elements with the standard Ctrl-C, Ctrl-X, and Ctrl-V shortcuts.

Slide navigation

1 opens the slide overview. / searches the deck and j jumps directly to a slide. Use d to delete the current slide.

Visuals and effects

Press v for the current slide’s visual properties: foreground, terminal background, header color, background pattern, and animated effect. Each mastered slide can inherit, override, or explicitly disable every property.

Effects

matrixstarsplasmaglitchdigital-snowradarneuralcircuitdata-stormflamewarpscanlinefireworksexplosion

Backgrounds

soft-plasmaauroratopographywavesmeshconstellationribbonsdiagonal-flowblueprint

Press e or b to browse effects or backgrounds directly. The picker previews each choice against the current slide before you commit.

Master decks

Press M to open Master View. A deck has one Base Master and any number of named layouts.

• Base Master supplies deck-wide graphics, effects, backgrounds, colors, styles, and the default page number.
• Layouts add fixed elements and editable Title, Subtitle, Body, Code, or Image placeholders.
• Slides inherit their layout and can override visual properties independently.

Typical workflow

1. Design shared elements and page numbering in the Base Master.
2. Create layouts for recurring compositions.
3. Select an element and press p to assign its placeholder role.
4. Press n and choose a layout for a new slide.
5. Press L to change an existing slide’s layout.

When a layout changes, Keynope rebinds matching content by placeholder slot and role. Content without a matching destination is retained as a local slide element.

Page numbers

Press # to cycle inherit, show, and hide. In Master View this controls Base or layout policy; on a slide it controls only that slide. Page numbers use the actual slide index across terminal, presenter, thumbnails, and HTML export.

Presenting

Run keynope deck.md. The native helper opens on an external display when one is available and otherwise waits in the menu bar. Press p to toggle the live signal; while editing, the external surface shows TV snow instead of exposing unfinished work.

Screen sharing

Use the presenter menu bar’s Share submenu to place an application, window, or entire display over the live deck. Shared content is aspect-fitted with a margin so the current slide remains visible. Choose Share → Nothing to stop capture.

Sharing is video-only. Full-display capture excludes Keynope Presenter to prevent recursive capture.

Classic mode

keynope --classic deck.md

Classic mode runs without the native presenter companion.

HTML export

keynope --export deck.md

This writes deck.html beside the source. The file is standalone and includes navigation, effects, backgrounds, terminal rendering, and the authored deck dimensions. Open it directly or serve it from any static host.

Inside the visual editor, press x to export using the active presentation dimensions. Command-line --export preserves the dimensions recorded in the deck metadata and is the mode used by the web renderer.

Render API

The public projector accepts Markdown and returns standalone Keynope HTML.

curl --fail-with-body \
  -H 'Content-Type: text/markdown' \
  --data-binary @deck.md \
  https://projector.keynope.sh/ \
  --output deck.html

You can alternatively send JSON:

{"markdown":"# Hello from Keynope"}

Relative images cannot be included in a Markdown-only request because the API receives no companion files. Use already-rendered text content or host the finished export with its required assets.

Shortcut reference

The authoritative shortcut view is built into Keynope: press ? in any mode and the list adapts to the current selection. These are the global essentials.

Troubleshooting

Presenter does not open

Confirm KeynopePresenter.app remains beside the real CLI inside Homebrew’s Keynope Caskroom payload. Reinstall with brew reinstall --cask keynope.

Screen Recording keeps prompting

Use an official signed and notarized release. Ad-hoc local builds can receive a new identity after rebuilding. Remove stale entries in System Settings → Privacy & Security → Screen Recording, then approve the current Keynope Presenter once.

The exported layout differs

Keep the leading authored-size metadata in the deck. Current --export releases preserve it. Upgrade Keynope if an older export used the invoking terminal’s dimensions.

An image is missing

Verify the path is relative to the Markdown file and the asset exists. The web projector accepts one Markdown body only and therefore cannot receive local companion images.

Need more help?

Ask in Discussions. For reproducible defects, open a GitHub issue with your macOS version, architecture, Keynope version, steps, and a minimal deck.

Contribute

Ideas, workflow feedback, presentation anecdotes, documentation improvements, bug reports, and code are welcome. Start broad proposals in Discussions and keep pull requests focused.

make test
make build