Margo

Margo is a Go prototype for building slide decks from Markdown with a Hugo-like project model.

The current repo contains:

• the CLI implementation
• the product docs in docs/product/PRD.md and docs/product/implementation-plan.md
• the user guide in docs/AUTHORING_GUIDE.md
• a working local deck scaffold/build/serve flow
• one committed reference fixture deck in examples/reference-deck
• one committed benchmark deck in examples/benchmark-deck

Current Status

This is an early prototype, not a release-ready tool.

Working today:

• margo new <deck-name>
• margo init
• margo build
• margo serve
• margo pack <deck-dir>
• margo unpack <archive.margo> [destination]
• margo theme add <repo>
• margo theme list
• margo clean
• margo new slide <name>
• margo new theme <name>
• margo new theme <name> blank
• margo theme update <name>

Implemented in the content model:

• YAML config parsing
• YAML slide front matter
• Markdown rendering with Goldmark
• theme loading from themes/<name>/
• per-slide layout selection
• draft filtering
• hidden/skip filtering
• section context
• bundle-based Markdown notes, including speaker scripts and research, with optional interactive HTML viewing

Not finished:

• PDF export
• PPTX export
• manifest-driven sequencing beyond the current loader path
• presenter mode
• browser-refresh injection outside the scaffolded default theme

Build

Build a local binary:

go build -o ./bin/margo ./cmd/margo

Run directly without installing:

go run ./cmd/margo help

Build versioned release archives:

VERSION=0.1.0 ./scripts/release.sh

Homebrew packaging notes for maintainers live in docs/HOMEBREW.md.

Override the default targets by passing explicit GOOS/GOARCH pairs:

VERSION=0.1.0 ./scripts/release.sh darwin/arm64 linux/amd64

Example Workflow

Create a deck:

./bin/margo new my-deck
cd my-deck
../bin/margo build

Serve the deck locally:

../bin/margo serve

If the default preview port is unavailable, choose another port interactively or pass one explicitly:

../bin/margo serve --port 1414

Create a slide:

../bin/margo new slide roadmap

Create a theme:

../bin/margo new theme custom

Install a vendored theme from a Git repo:

../bin/margo theme add https://example.com/brand-theme.git --ref v0.1.0
../bin/margo theme list

Update an installed vendored theme from its recorded Git source:

../bin/margo theme update brand

Project Shape

A generated deck currently looks like:

my-deck/
  margo.yaml
  slides/
    01-title/index.md
    02-why/index.md
  themes/
    default/
      theme.yaml
      layouts/
        deck.html
        slide-default.html
        slide-title.html
  archetypes/
    default/
      archetype.yaml
  assets/

Development Notes

• The repository root is the CLI source repo, not a deck project.
• Generated test decks and local caches are ignored by .gitignore.
• examples/reference-deck is the committed fixture deck for manual checks and regression work.
• examples/benchmark-deck is the committed 20-slide deck for manual performance and density checks.
• margo serve uses 127.0.0.1:1313 by default. If that port is unavailable, interactive runs now prompt for another port and non-interactive runs should use --port <port>.
• Some local preview verification required running outside the sandbox because binding local ports may be restricted in this environment.

Benchmark the committed 20-slide deck build path with:

go test -run '^$' -bench BenchmarkBenchmarkDeckBuildFlow ./internal/output/html