Code Runner

This guide covers marking code blocks as runnable so readers can run and edit Go examples inline. Execution happens entirely in the reader's browser — see How the Runner Works for the architecture.

Enable the feature#

The runner is enabled by default. There is no service to run and nothing to configure — a standard site already has it on:

s := gomark.NewSite(
	gomark.WithSiteContentDir("cmd/site/content"),
	gomark.WithSiteMode(gomark.PreRender),
)

To turn the run controls off across the whole site, pass --no-runner on the CLI, set build.runner: false in gomark.yaml, or — from Go — pass gomark.WithSiteRunnerEnabled(false) (or set PLAYGROUND_ENABLED=false).

Mark runnable code fences#

GoMark attaches run controls to Go code fences marked with run=true or editable=true:

```go:title="hello.go":run=true:editable=true
package main

import "fmt"

func main() {
    fmt.Println("hello")
}
```

This renders as below — give it a try:

package main

import "fmt"

func main() {
	fmt.Println("hello")
}

The first run downloads the in-browser runtime (cached afterward), then executes the snippet locally.

What runs#

A snippet needs a package main declaration and a func main(). Beyond that you can use most of the standard library, generics, goroutines, and helper functions. Snippets run through the yaegi interpreter, so a few things behave differently from go run:

1. Some reflection-heavy code, unsafe, and cgo are unsupported
2. There is no filesystem or network access in the browser sandbox
3. A deliberate infinite loop freezes the reader's own tab
4. Output is capped to protect browser memory.