gomark

Docs for Go libraries where every example actually runs.

GoMark turns a folder of markdown into a real documentation site — and the Go code blocks in your docs run live, right in the reader's browser. No playground server, no backend, no infrastructure: execution happens client-side via a WebAssembly build of the yaegi interpreter, so your examples stay honest and your servers stay boring.

package main

func main() {
	println("Hello, Gophers!") // edit me and hit Run
}

The block above is runnable on gomark.dev — a site built with GoMark itself. Try editing it and clicking Run.

Point it at your markdown and ship. Routing, navigation, search, sitemap, robots, and the in-browser runner are all built in.

Read the docs at gomark.dev.

Install

go install github.com/arivictor/gomark/cmd/gomark@latest

Quick start

Create a content directory and add markdown files. The file structure maps to the URL structure — content/docs/hello.md is served at /docs/hello, and index.md files serve at their folder path.

# Hello, World!

Welcome to my docs site.

Preview it locally with live reload, then build a static site:

# Dev server: renders live and auto-reloads the browser as you edit
gomark serve ./content --live

# Production: render to a static site you can host anywhere
gomark build ./content ./dist --url https://docs.example.com

The output of gomark build is plain HTML/CSS/JS that runs on any static host — GitHub Pages, Netlify, S3, nginx. There is no server to run in production, and the Go runner executes entirely in the reader's browser. See the deployment guide for GitHub Pages, container, and other host recipes.

Configure

Site title, logo, SEO (Open Graph / Twitter / description), navigation, social links, analytics, and build options live in an optional gomark.yaml that both build and serve read. It's auto-discovered in your project (or pass --config):

title: My Docs
url: https://docs.example.com
logo:
  light: /logo-light.png
  dark: /logo-dark.png
seo:
  description: Docs for my Go library.
  twitter_site: "@myhandle"
nav:
  - label: GitHub
    url: https://github.com/me/my-docs
analytics:
  provider: plausible
  id: docs.example.com

CLI flags override environment variables, which override the file, which overrides the defaults. There are no custom layouts or CSS — every site uses the built-in theme. See the configuration guide for the full schema.

Use it as a library

GoMark is also a single importable package, github.com/arivictor/gomark, if you'd rather drive it from Go:

package main

import (
	"log"

	gm "github.com/arivictor/gomark"
)

func main() {
	s := gm.NewSite(
		gm.WithSiteTitle("My Docs"),
		gm.WithSiteContentDir("content"),
	)

	// Build a static site...
	if err := s.Export("dist"); err != nil {
		log.Fatal(err)
	}
	// ...or run the dev server: s.Serve(":8080", true)
}