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 project’s API reference lives at pkg.go.dev/your/module, which is Go’s URL with your import path stapled on the end. The guides live in the README until it gets too long, at which point they migrate to a GitHub wiki that nobody updates after launch. The examples live in test files. The changelog is whatever the release tooling generates. The architecture notes live in a Notion doc shared inside the team and invisible to everyone outside it. The llms.txt, if you ship one, is hand-edited because nothing in the chain knows about it.

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 changed

Two things changed.

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 with the same structure. The Go source-of-truth is excellent and should stay. The presentation surface is fragmented and should not. Keep the model: package comments, examples-as-tests, go doc. Replace only what those comments get rendered into.

Keep the parser. Replace the renderer.

How

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

{
  tab: "Go API",
  slug: "go-api",
  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 project’s docs site is where users go after they have decided your project is interesting and want to learn how it works. The first surface is Go’s. The second one should be yours.

What this means

Go projects do not need a second documentation dialect. They need the source model they already have, rendered into a site they own.

The Go community already paid the hardest cost of writing good docs: putting them in the code, keeping them next to tests, using a toolchain that treats them as first-class. The only thing missing was somewhere to put them that the project controlled.

Documentation belongs to the project.