worky

A Go library for building interactive, self-contained workshop tools.

The problem: running a workshop means participants fight setup — missing tools, broken environments, unclear progress. Worky fixes this with a single binary that locks chapters until checks pass and shows live status in the browser.

Participants download one file, run one command, and follow along in their own browser. No Docker, no cloud, no separate web server.

Try the demo

The demo/ directory is a fully working workshop you can run right now:

cd demo
go mod tidy
go run . serve --open

Then complete each chapter:

# Chapter 00 — Getting Started
touch done.txt
export WORKSHOP_USER=yourname
go run . check

# Chapter 01 — Hello Worky
echo "Hello, Worky!" > hello.txt
go run . check

# Chapter 02 — Finishing Up
echo "# Workshop Complete" > complete.md
go run . check

Watch the sidebar icons update live in your browser as each chapter unlocks. Run go run . status to see all chapters, go run . reset to start over.

How it works

A workshop is a Go binary that embeds a site/ directory of HTML and Markdown files:

your-workshop/
├── main.go          # imports worky, wires chapters + checks + embedded site
├── site/
│   ├── index.html           # home page
│   ├── workshop.css
│   ├── workshop-progress.js
│   └── 00-setup/
│       └── index.md         # chapter content (Markdown, rendered server-side)
└── go.mod

The worky server renders .md files on the fly and serves .html files as-is — no build step, no external tools.

If you prefer external slides (Google Slides, Marp, Reveal.js), skip writing chapter content — the built-in status page shows chapter progress with live 🔒/🔓/✅ icons regardless.

Participants:

1. Download the binary (or git clone + go build)
2. Run ./my-workshop serve --open
3. Follow along in the browser, run ./my-workshop check to unlock each chapter

Create a workshop in 30 seconds

# Install the CLI
go install github.com/davideimola/worky/cmd/worky@latest

# Scaffold a new workshop
worky init "My Workshop"
cd my-workshop
go mod tidy
make serve

Add more chapters as your workshop grows:

worky new chapter 01 "Hello World"
# → creates site/01-hello-world/index.md
# → prints the Go snippet to add to main.go

Build for distribution:

worky build   # go build

Manual setup

1. Create the Go project

go mod init github.com/acme/my-workshop
go get github.com/davideimola/worky

2. Write main.go

package main

import (
    "embed"

    "github.com/davideimola/worky"
)

//go:embed all:site
var site embed.FS

func main() {
    worky.New(worky.Config{
        Name:    "My Workshop",
        HomeDir: ".my-workshop",
        Port:    8080,
        SiteFS:  site,
        Chapters: []worky.Chapter{
            {
                ID:   "00",
                Name: "Setup",
                Slug: "00-setup",
                Checks: []worky.Check{
                    {Description: "Docker is running", Run: myDockerCheck},
                },
            },
        },
    }).Run()
}

3. Write content

Create site/00-setup/index.md:

# Setup

Welcome to the workshop! Make sure your environment is ready.

## Steps

1. Start Docker Desktop
2. Run `./my-workshop check` to verify and unlock the next chapter

4. Build and distribute

go build -o bin/my-workshop .
GOOS=linux  GOARCH=amd64 go build -o bin/my-workshop-linux-amd64 .
GOOS=darwin GOARCH=arm64 go build -o bin/my-workshop-darwin-arm64 .

CLI commands

If chapter-id is omitted, check auto-detects the first incomplete unlocked chapter.

Progress storage

Progress is stored in ~/<HomeDir>/progress.json. The first chapter is always unlocked. Running check for a chapter marks it complete and unlocks the next one.