Margo Authoring Guide

Margo Authoring Guide

The practical workflow for building, styling, and sharing decks from Markdown.

Margo Workflow Overview
Section

Workflow

Margo Workflow Overview
Agenda
  1. Getting a deck running
  2. Structuring slides and front matter
  3. Reusing assets, shortcodes, and includes
  4. Choosing and customizing themes
  5. Understanding the render pipeline
  6. Knowing the current limits
Workflow Map
Section

Getting Started

Getting Started
Workflow
Build The CLI And Create A Deck

Build and Start

  • go build -o ./bin/margo ./cmd/margo
  • ./bin/margo new my-deck
  • cd my-deck
  • ../bin/margo serve

Generated Structure

  • margo.yaml
  • slides/
  • themes/default/
  • archetypes/
  • assets/
  • shortcodes/
CLI Setup
Workflow
Configure margo.yaml

One file sets the deck contract

  • deck metadata defines title, logo, language, and footer
  • theme selection activates the visual system
  • outputs control which artifacts are built
  • snippets inject approved shell-level HTML when needed

Treat margo.yaml as the deck's operating contract. It is the first file to read when you are orienting yourself in a new project.

theme:
  name: default
  color_mode: dark
  typography: executive
  accent_color: "#4db6ac"
Root Config
Workflow
Preview, Build, And Clean

The loop is intentionally short

  • margo serve previews at 127.0.0.1:1313
  • margo build writes the configured outputs
  • --port handles conflicts cleanly
  • --include-drafts is useful during editing
  • margo clean removes generated output
3
Core Commands
Serve, build, and clean cover most day-to-day authoring.
Dev Loop
Section

Slides And Archetypes

Slide Authoring
Authoring
New Slides And Front Matter

New slides are bundles

  • each slide lives at slides/<id>/index.md
  • slide-local assets can sit beside index.md
  • front matter selects order, section, layout, and visibility
  • archetypes help create the initial shape, but rendering uses layouts

Margo logo glow

Slide Bundles
Authoring
Layouts, Shortcodes, And Includes

Structural layers

  • layouts control shell and slide structure
  • shortcodes add reusable content blocks inside Markdown
  • includes keep repeated Markdown in one place

Stay in Markdown for content. Let layouts and shortcodes carry the visual weight.

Why this split works

  • authors stay mostly in Markdown
  • shared fragments reduce repetition
  • shortcodes carry richer content blocks
  • layouts keep the visual system consistent

Rule of thumb

Keep content in Markdown and let layouts, shortcodes, and includes do the repetitive structural work.

Reuse Patterns
Authoring
Override Model And Rendering Roles

Current Override Model

  • deck-local shortcodes override theme shortcodes
  • deck-local partials override theme partials
  • one active theme per deck
  • layouts choose structure, shortcodes choose content blocks

Authoring

  • front matter
  • body Markdown
  • shared fragments

Rendering

  • shortcodes expand
  • Markdown becomes HTML
  • layouts wrap the result
Reuse Model
Authoring
Assets And Figure Shortcodes

Shared assets can stay elegant

  • deck-level assets live under assets/
  • slide-level assets live beside slide Markdown
  • figure gives you semantic image markup with caption support
  • video handles poster assets and remote video sources
Margo logo on light background
The default theme can render shared deck assets through a shortcode.Source: repo assets
Media Handling
Section

Themes

Themes
Theming
Theme Structure And Overrides

A theme can provide

  • layouts/deck.html
  • layouts/print-deck.html
  • layouts/slide-*.html
  • partials/*.html
  • shortcodes/*.html

A deck can override locally

  • partials/*.html
  • shortcodes/*.html
  • theme options in margo.yaml

This keeps project-specific variation explicit rather than magical.

Theme Anatomy
Theming
Render Pipeline

The pieces operate in sequence

  1. archetypes create the initial slide files
  2. slide Markdown and front matter are loaded
  3. shortcodes expand inside the body
  4. Markdown is converted to HTML
  5. slide layouts wrap the content
  6. deck and print layouts wrap the slide collection
  7. partials provide reusable layout fragments

The Go code should stay generic: parsing, validation, asset resolution, and model shaping. Markup shape belongs in templates.

Rendering Model
Section

Wrap-up

Margo Workflow Overview
Closing

Current realities

PDF still depends on a local browser path and needs ongoing QA PPTX export is not implemented yet Presenter mode is not implemented yet Theme APIs can still evolve

Good files to study

examples/reference-deck/ examples/benchmark-deck/ docs/AUTHORING_GUIDE.md

Get Margo

Margo Repo on Github

Current State
Use left/right arrow keys