mpkg

Generate static HTML for Go vanity import paths.

mpkg reads a YAML config, generates a self-contained static site where every module page carries the correct go-import and go-source meta tags, and produces a searchable index listing all packages. Deploy the output directory to any static host — no server-side code required.

Installation

Homebrew (macOS/Linux):

brew tap sembraniteam/tap
brew install mpkg

Go:

go install go.sembraniteam.com/mpkg@latest

Or download a pre-built binary from GitHub Releases.

Quick Start

1. Create mpkg.yaml:

base_url: your-domain.com

site:
  title: "My Go Packages"
  tagline: "Custom vanity import paths"
  logo: "MyOrg"
  logo_font: "standard"

build:
  output_dir: build

modules:
  mylib:
    git_url: https://github.com/your-org/mylib
    branch: main
    description: "A short description of your package."
    tags: [library, go]

2. Validate the config:

mpkg validate

3. Generate the site:

mpkg generate

4. Deploy build/ to your static host (Nginx, GitHub Pages, Caddy, etc.).

Users can now run:

go get your-domain.com/mylib@latest

Configuration

All fields in mpkg.yaml:

Field	Type	Default	Description
base_url	string	—	Your domain, e.g. example.com (required)
site.title	string	—	HTML <title> of the index page
site.tagline	string	—	Subtitle shown below the logo
site.logo	string	MPKG	Text rendered as ASCII art in the header
site.logo_font	string	standard	go-figure font name
build.output_dir	string	build	Directory where HTML files are written
modules.<name>.git_url	string	—	Git repository URL (required)
modules.<name>.branch	string	main	Default branch
modules.<name>.description	string	—	Short description shown on the index page
modules.<name>.tags	[]string	—	Tags used for search filtering

Commands

Command	Description
validate	Validate mpkg.yaml without generating any output
generate	Build static HTML into the output directory
serve	Preview the generated site with a local HTTP server
watch	Serve and auto-regenerate when mpkg.yaml changes
version	Print the mpkg version
completion	Generate shell autocompletion script

Global flag

Flag	Default	Description
-c, --config	mpkg.yaml	Path to config file

generate

mpkg generate [flags]

Flag	Default	Description
--clean	false	Remove the output directory before generating
-o, --output	(from config)	Override the output directory
-q, --quiet	false	Suppress all output except errors

serve

mpkg serve [flags]

Flag	Default	Description
-p, --port	8080	HTTP port to listen on
--open	false	Open the browser automatically after the server starts

watch

mpkg watch [flags]

Flag	Default	Description
-p, --port	8080	HTTP port to listen on
--open	false	Open the browser automatically after the server starts

Contributing

git clone https://github.com/sembraniteam/mpkg.git
cd mpkg
go test ./...   # run the full test suite
go build .      # build the binary

Open an issue before submitting a large change. PRs are welcome.