pkg.go.dev Isn't Your Docs Site

Go has the best source-of-truth model for documentation in any mainstream language.

Package comments are part of the code. Examples live in _test.go files and run in CI. go doc is in the toolchain. pkg.go.dev indexes every public module on the planet from those comments, automatically, for free. The Go community got the inputs right. Most Go projects then ship the outputs on someone else’s URL.

Your API reference lives at pkg.go.dev/your/module, which is Go’s URL with your import path stapled on the end. Everything around it is scattered by default. The guides start in the README and migrate to a GitHub wiki the moment it gets too long, which is also the moment people stop updating it. Examples sit in test files, the changelog is whatever the release tooling emitted, the architecture notes are in a Notion doc the team can see and nobody else can. The llms.txt, if it exists, was hand-written, because nothing in that chain knows the file is supposed to be there.

The Go community accepted this fragmentation because the alternatives required leaving the toolchain. Sphinx is for Python. Doxygen is for C++. Mintlify is for the OpenAPI crowd. Nothing in the Go ecosystem covered the gap between excellent source-of-truth and an owned, modern docs site, so most projects shipped the README plus pkg.go.dev split and moved on.

What moved

Two things moved.

The bar for serious developer documentation moved past pkg.go.dev’s defaults. Stripe-tier is now the floor for any project that wants to be taken seriously, and pkg.go.dev’s design has not meaningfully evolved in years because it was never trying to be your project’s site; it was trying to be Go’s package index, and it does that job well.

The reader changed. Agents grounding tool calls on your API reference are now reading your docs alongside humans. llms.txt, JSON search indexes, structured anchors per symbol, machine-readable example metadata: none of these exist on pkg.go.dev because pkg.go.dev was not built for that reader and was never going to be.

The Go community has not adjusted. The default project shape in 2026 is still README plus pkg.go.dev, with the agent-readable surfaces missing entirely and the rest scattered across wiki pages, blog posts, and Notion docs nobody can index.

The move

The move for Go is the same move as for C++, with the seam in a different place.

The C++ ecosystem spent twenty years trying to replace Doxygen and concluded there was no escape, which was the wrong conclusion because Doxygen is two tools and only one needed replacing. “Don’t Replace Doxygen” makes that argument.

Go’s situation is the inverse of C++ with the same underlying structure. The source of truth is excellent and worth keeping exactly as it is: package comments, examples-as-tests, go doc. What those comments get rendered into is the only thing that needs to change.

Keep the parser. Replace the renderer.

How

Sourcey reads Go source directly. The config is one block:

{
  tab: "Go API",
  slug: "go-api",
  source: godoc({
    module: ".",
    packages: ["./..."],
    includeTests: true,
  }),
}

That produces one Go API tab generated from native package comments and test examples, sitting alongside the project’s guides, recipes, architecture notes, OpenAPI or MCP references when the project exposes them, and llms.txt and llms-full.txt written from the same build. The pipeline writes nothing to disk that wasn’t already in the source. There is no Markdown mirror to drift, no Doxygen XML retro-fitted onto a Go project, no second documentation dialect.

One site, one source of truth, one URL the project owns.

Scafld, in public

Scafld is the live reference. A working Go protocol for multi-phase agent work, not a toy module: real packages, public command behaviour, shipping code. Its Go API tab lives at 0state.com/scafld/docs/go-api, generated from the same package comments and test examples that pkg.go.dev would render from. Same source, project’s URL, project’s presentation, project’s llms.txt.

The package reference sits beside the rest of Scafld’s docs (guides, the protocol specification, recipes), not on a separate domain.

pkg.go.dev is still the right place for what it does

Keep using pkg.go.dev. A global package index is essential and pkg.go.dev is the canonical one. Sourcey takes the same source of truth, produces a project-owned site from it, and puts the rest of the docs alongside the API reference. The two surfaces serve different jobs.

pkg.go.dev is where a developer searches when they have an import path and want to find a module. Your docs site is where they go once they have decided the project is worth learning. One of those surfaces belongs to Go and always should. The other one is yours to lose.

The only thing missing

The Go community already paid the expensive ninety percent of good documentation. The docs live in the code. Examples are tests that run in CI. The toolchain treats every line of it as first-class and indexes every public module on the planet for free, years before anyone was talking about agents reading an API reference.

The cheap ten percent, a destination the project actually controls, is the part that got handed to someone else’s domain. Scafld takes the same package comments pkg.go.dev would render and ships them at 0state.com/scafld/docs/go-api: same source of truth, the project’s URL, the project’s llms.txt, and the rest of the docs sitting beside the API reference instead of three services away.

Go did the hard ninety percent a decade ago. Renting out the last ten is just habit.