Cortex Presentation Kit

Create one Markdown presentation and use it in two modes:

• Web mode uses Slidev for browser presenting, speaker notes, PDFs, PNGs, and static websites.
• Terminal mode uses Presenterm for code walkthroughs, test output, diagrams, and prepared demonstrations.

You maintain one deck. cortex-present validates it and generates the renderer-specific files.

New here? Follow Create and present your first deck. You do not need to know Slidev or Presenterm.

Table of contents

• Choose what you want to do
• Install
• Create and present your first deck
• Use an existing deck
• Write a deck
• Examples
• Present and export
• Command reference
• Ask an LLM to do it
• How it works
• Safety
• Platform notes
• Contributing

Choose what you want to do

I want to…	Start here
Create my first presentation	cortex-present new my-talk
Preview a deck in my browser	cortex-present dev my-talk --web
Present from my terminal	cortex-present dev my-talk --terminal
Check why a deck will not compile	cortex-present check my-talk
Export PDF, PNG, HTML, or a website	Export
Copy working Markdown examples	Examples
Let an LLM create the deck for me	LLM prompt
Understand the internals	How it works

Install

You need Node.js 20.12 or newer and npm.

npm install
npm run build
npm link
cortex-present doctor

npm link makes this repository’s local cortex-present command available on your machine. It does not publish the package.

If you prefer not to use npm link, replace cortex-present in this guide with node dist/cli.js.

Install Presenterm for terminal mode

Web mode works after npm install. Presenterm is a separate native application and is only required for terminal mode.

Choose one installation method:

macOS:

brew install presenterm

Windows with WinGet:

winget install --id=mfontanini.presenterm -e

Windows with Scoop:

scoop install main/presenterm

Arch Linux:

sudo pacman -S presenterm

Any platform with Rust installed:

cargo install --locked presenterm

Confirm the installation:

presenterm --version
cortex-present doctor

If none of these options fits your system, download a binary from Presenterm releases or use its official installation guide.

Create and present your first deck

1. Create it

From the toolkit repository, run:

cortex-present new my-talk

This creates:

decks/my-talk/
├── deck.md       # Edit this file
├── assets/       # Images used by the deck
├── scripts/      # Prepared terminal demonstrations
└── snippets/     # Source files displayed in slides

2. Edit it

Open decks/my-talk/deck.md. Change the title, audience, and slide content. The generated template already contains two valid slides.

3. Check it

cortex-present check my-talk

A successful check looks like:

✓ decks/my-talk/deck.md: 2 slides are valid; no code executed.

4. Present it

For the browser:

cortex-present dev my-talk --web

Open http://localhost:3030/.

For the terminal:

cortex-present dev my-talk --terminal

That is the complete authoring loop. Keep editing decks/my-talk/deck.md; generated files under .cortex/ are disposable.

Use an existing deck

If someone sends you a deck directory:

1. Place it under decks/.
2. Check it before starting either renderer.
3. Review every referenced script before enabling execution.

cortex-present check their-deck
cortex-present dev their-deck --web

You can also pass a direct Markdown path:

cortex-present check ./decks/their-deck/deck.md

Write a deck

The canonical deck uses normal Markdown with a small number of structured directives.

Metadata and slides

Every deck begins with:

---
title: Does MIP-4 forget a reserve dip after a revert?
audience: Cortex MIPs subgroup
duration: 8m
theme: cortex-dark
---

Use <!-- slide --> between slides:

# First slide

Explain the model.

<!-- slide -->

# Second slide

Show the implementation.

The required fields are title, audience, duration, and theme. Duration accepts values such as 8m, 30m, or 1.5h.

Supported content

Content	Canonical syntax	What happens
Text, lists, tables, code	Normal Markdown	Passed to both renderers
Speaker notes	:::notes	Hidden from audience content
Local image		Used by both renderers
Mermaid diagram	```mermaid	Rendered by both engines
Source import	:::source{...}	Requested lines are embedded
Prepared script	:::run{...}	Executable only in opted-in terminal mode
Columns	:::columns	Adapted to each renderer’s layout

The full syntax and validation rules live in docs/deck-format.md.

Examples

Copy these blocks into any canonical deck.

Speaker notes

:::notes
Define a call frame before explaining the sequence.
Pause after asking the question.
:::

Local image

![Reserve rollback sequence](./assets/reserve-rollback.png)

Remote images are rejected. Copy images into the deck’s assets/ directory.

Mermaid diagram

```mermaid
sequenceDiagram
  Parent->>Child: call
  Child--xParent: revert
  Parent->>Parent: continue
```

Slidev handles this in web mode. Presenterm requires Mermaid CLI (mmdc) for terminal rendering; cortex-present doctor reports whether it is available.

Source import

:::source{path="./snippets/state.cpp" language="cpp" lines="120-150" highlight="132-140"}
:::

• path points to a file inside the deck.
• language controls syntax highlighting.
• lines is the inclusive range to display.
• highlight optionally emphasizes original file lines in web mode.

Two columns

:::columns{widths="1,1"}
## Expected behavior

The failed frame is removed.

<!-- column -->

## Regression

The parent observes a clear reserve signal.
:::

Prepared terminal script

Create decks/my-talk/scripts/run-test.sh:

#!/usr/bin/env bash
set -euo pipefail

forge test --match-test test_caughtChildRevertClearsReserveSignal -vvv

Make it executable on Linux, macOS, or WSL:

chmod +x decks/my-talk/scripts/run-test.sh

Reference it in the deck:

:::run{script="./scripts/run-test.sh"}
:::

Validation does not run this script. Web mode shows it as a prepared demonstration. Terminal execution requires an explicit --execute flag.

Complete issue #9 example

decks/issue-9/deck.md demonstrates every supported feature in one presentation:

cortex-present check issue-9
cortex-present dev issue-9 --web

Issue #9 is an ordinary example deck. It is not embedded in the parser, compiler, theme, or new-deck template.

Present and export

Check before presenting

cortex-present check my-talk

check catches malformed metadata, unsupported directives, empty slides, missing files, invalid line ranges, remote images, unsafe paths, and common private-key patterns. It never executes code.

Web mode

cortex-present dev my-talk --web

URL	Purpose
http://localhost:3030/	Audience presentation
http://localhost:3030/presenter/	Presenter view and notes
http://localhost:3030/overview/	All slides at once
http://localhost:3030/export/	Browser export interface

Use another port with --port 4040.

Terminal mode

cortex-present dev my-talk --terminal

Use arrow keys, Page Up/Page Down, or j and k to navigate. Press ? for Presenterm shortcuts and Ctrl+C to quit.

After reviewing the deck and its scripts, enable prepared demonstrations with:

cortex-present dev my-talk --terminal --execute

Press Ctrl+E on an executable Presenterm block. Never enable execution for an untrusted deck.

Export

Export every supported target:

cortex-present export my-talk

Or choose one:

cortex-present export my-talk --format html
cortex-present export my-talk --format web
cortex-present export my-talk --format pdf
cortex-present export my-talk --format png

Outputs appear under artifacts/my-talk/:

Output	Renderer
terminal.html	Presenterm
web/	Slidev static build
slides.pdf	Slidev
slides/	Slidev PNGs

Compile without starting a renderer

cortex-present compile my-talk

This writes disposable adapters under .cortex/my-talk/. Continue editing the canonical decks/my-talk/deck.md, not the generated files.

Command reference

Command	Purpose	Executes deck scripts?
cortex-present new <name>	Create a generic deck	No
cortex-present check <deck>	Validate the canonical source	No
cortex-present compile <deck>	Generate both adapters	No
cortex-present dev <deck> --web	Start Slidev	No
cortex-present dev <deck> --terminal	Start Presenterm	No
cortex-present dev <deck> --terminal --execute	Start Presenterm with prepared scripts enabled	Yes
cortex-present export <deck>	Produce supported exports	No, unless --execute is added
cortex-present doctor	Check local tools	No

Ask an LLM to do it

Paste the prompt below into an LLM that has filesystem and terminal access. Replace the bracketed text with your presentation details.

Create a Cortex Presentation Kit deck for me.

Toolkit directory: [absolute path to cortex-presentation-kit]
Deck name: [lowercase-name]
Title: [presentation title]
Audience: [who will attend]
Duration: [for example, 8m]
Goal: [what the audience should understand or decide]
Source material: [paths to notes, code, images, test output, or documents]

Use the repository README and docs/deck-format.md as the authoring contract.

Do the work, not just a plan:
1. Run `cortex-present new [lowercase-name]` from the toolkit directory.
2. Read the supplied source material.
3. Edit only the canonical deck under `decks/[lowercase-name]/deck.md` and its local assets, snippets, and scripts.
4. Keep the presentation focused: explain the model, show the implementation, run or prepare the evidence, and ask for one decision.
5. Define unfamiliar terms before relying on them.
6. Use speaker notes for what I should say; keep audience slides concise.
7. Copy only the required source excerpts or assets into the deck so it is self-contained.
8. Never place secrets in the deck and never enable script execution.
9. Run `cortex-present check [lowercase-name]`.
10. Run `cortex-present compile [lowercase-name]`.
11. If web dependencies are available, run a Slidev production build.
12. Report the files created, validation results, and the exact preview command.

Do not edit generated files under `.cortex/`. Do not claim Presenterm and Slidev are visually identical.

The prompt deliberately keeps execution disabled. After reviewing the finished deck and every script, you can choose whether to enable terminal demonstrations yourself.

How it works

canonical deck.md
      │
      ▼
Markdown abstract syntax tree
      │
      ├── metadata and directive validation
      ├── path, asset, range, and secret checks
      │
      ├── Presenterm Markdown
      └── Slidev Markdown

shared theme tokens
      ├── Presenterm YAML
      └── Slidev CSS

The compiler uses unified, remark-parse, remark-frontmatter, and remark-directive. Directives are parsed as structured Markdown nodes rather than replaced with text-matching shortcuts. Zod validates metadata and attributes before a renderer starts.

The adapters share content and evidence, not pixel-level output. Presenterm remains optimized for the terminal; Slidev remains optimized for the browser.

Read docs/architecture.md for the component and trust boundaries.

Safety

• check and compile never execute deck scripts.
• Scripts must remain inside their deck directory.
• Paths cannot escape the deck directory.
• Remote images are rejected.
• Common private-key and mnemonic patterns are rejected.
• Slidev never receives an executable browser block.
• Presenterm execution requires an explicit --execute flag.

Treat every deck as untrusted until you have read its canonical Markdown and referenced scripts. See SECURITY.md for reporting guidance.

Platform notes

Linux

Use sudo pacman -S presenterm on Arch Linux. On other distributions, use a pre-built release or cargo install --locked presenterm. Kitty, WezTerm, Ghostty, and Foot offer strong terminal-image support.

macOS

Use brew install presenterm. Presenterm currently supports one speaker-notes listener on macOS.

Windows

Use WinGet or Scoop as shown in Install. WezTerm is a practical choice for terminal images.

WSL

Install Node.js, npm, and Presenterm inside the Linux distribution. A Windows Presenterm installation is not automatically available inside WSL. Do not share node_modules between Windows and WSL.

Contributing

Run:

npm run lint
npm run typecheck
npm test
npm run fixtures
npm run verify:slidev
npm run qa:visual

CI checks linting, strict TypeScript, unit and integration tests, fixture compilation, and a Slidev production build. Playwright checks the example deck for overflow at 1920×1080.

See CONTRIBUTING.md, the canonical format, and the upstream Presenterm and Slidev documentation.

MIT licensed.