# golds reads a Go package the way a maintainer thinks about it

> golds is an experimental local Go documentation server, docs generator and code reader that surfaces type and method implementation relations, promoted selectors and cross references that plain package documentation leaves implicit. Its own author calls it poorly maintained and warns that it may crash on recent Go versions.

**go101/golds** — An experimental Go local docs server/generator and code reader implemented with some fresh ideas.

- Repository: https://github.com/go101/golds
- Website: https://go101.org/apps-and-libs/golds.html
- Stars: 652 · Forks: 28
- Language: Go
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/go101-golds

## A docs server, a generator and a code reader in one binary

golds does three jobs under one program name. The module path is go101.org/golds and the default Go program name is golds. It serves documentation locally, generates documentation pages, and reads code, and the stated aim is to extract as much information as possible from Go code so that a reader can understand a package without an IDE open. Everything runs on your machine: the documentation says all functionalities are implemented locally, with no tracing and no external website visits except those you explicitly trigger. The project is described as experimental, and the pages are produced by a command that runs over a package pattern, for example the generated documentation of the standard packages was produced with the gen flag set, nouses and only-list-exporteds enabled, render-doclinks on, and the dark theme selected. A hosted demo of the standard library output exists for anyone who wants to see the result before installing.

## Implementation relations are the part standard docs leave implicit

Running the tool over a project follows a documented order. The build step comes first so that every module and package is present locally and cgo tools are verified:

```bash
go build ./...
golds ./...
```

The collection that distinguishes golds is package level type and value information. It shows type implementation relations and method implementation relations, so you can see which concrete types satisfy a given interface without grepping. It lists promoted selectors, including ones reached through unexported embedded fields, which is the kind of detail that produces confusion when a method seems to come from nowhere. It also shows the as-parameters-of and as-results-of lists for functions and methods, including interface methods, and shows the package level value list of a package level type. The resource listing can include unexported items, makes them self indexed, and can list types by popularity as well as by alphabet, which helps in packages that declare a large number of types. Keypresses p, e, t, f, v, c and a toggle expansion of packages, examples, types, functions, variables and constants.

## Clicking a use jumps to the declaration and back again

The code reading experience is the other half of the tool, and it works in both directions. Clicking a local identifier highlights every occurrence of that identifier in the file. Clicking a use of a non-local identifier jumps to the declaration of that identifier in another file. Clicking the name of a field or a method in its declaration shows where it is used, and if the name is a method, the uses page lets you click through to the interface methods it implements. The reverse path exists too: clicking a method named in an interface type declaration lists the methods that implement it, and from the implementation page you can jump to the uses of that interface method. There is a scope limit on some of this, since the uses view for a field or method currently applies only to package level named struct types, and the interface side applies only to package level named interface types.

## Static HTML output so the docs do not need rebuilding later

golds can generate static HTML documentation pages instead of serving them, and the stated reason is to avoid rebuilding the docs later, which is useful for package developers who want to host documentation for their own packages. The project also reports generation timings for the standard packages, about ten seconds, and for the packages of the kubernetes project, about one hundred seconds. Beyond that, the server supports opening any number of pages in new browser windows, and page styling can be customised through a custom.css file placed in the user configuration directory under a golds folder. There is also a code statistics view, where clicking some of the SVG charts opens the corresponding topmost lists, so you can see at a glance where the bulk of a package sits.

## Packages that do not compile are simply not documented

The limitation list is worth reading before you point golds at a repository. All packages must compile okay to get their docs shown, so a project with a broken build or a missing cgo dependency produces empty output rather than a partial one. Only a code snapshot is analyzed, and when the code changes a new analyzation is needed from scratch, with no incremental update. Testing packages are not fully parsed currently, so test files and test-only declarations are the weakest area of the output. The project relies on the golang.org/x/tools/go/packages package for parsing, and the documentation notes that this package has no way to report module and package downloading progress, which is why the documented workflow runs a build command over the project first to fetch all modules and verify that cgo tools are installed. Reading the go.mod of golds itself shows a go 1.26 directive with golang.org/x/tools v0.40.0, golang.org/x/net v0.48.0 and golang.org/x/text v0.32.0, against a README that asks for Go toolchain 1.22 or newer.

## The author calls the project poorly maintained and blames Go AST churn

The first thing in the README is a warning that deserves to be read before anything else. It states that because of the AST parsing complexities introduced in recent Go versions, and a lack of spare time to study them, the project is poorly maintained now, and that golds might crash or show incomplete information when analyzing some Go projects. The documented analyzation table was measured on a four core AMD-2200G machine with Go Toolchain 1.14.3, and several rows carry notes about prerequisites, such as needing a go mod init before running Golds, needing go mod vendor, or running golds . instead of golds ./... for certain projects. The last push was on 2026-08-06 and the repository publishes no GitHub releases, so there is no versioned artefact to pin and no changelog beyond the files in the tree, which include a TODO.md and internal/, gold/, gocore/, godoge/ and code/ directories.

## Local analysis against the alternative of trusting a hosted index

The practical alternative to golds is to read the source in an editor with language server support, or to rely on documentation hosted and indexed for you, which gives you a stable site but no local server and no implementation relation maps. The difference in approach is ownership of the analysis. golds parses your checkout with x/tools/go/packages and keeps everything on your machine, so what you read matches the code you have, including unexported items and the local commit, and the same tool can emit static HTML that a package author owns. The hosted route gives you convenience and other people's caching, at the cost of seeing a version of the package that is not necessarily the one on your disk. The price golds charges for the first route is fragility against Go language changes, which the README attributes to AST complexity in recent versions and to limited time available for keeping up.

## Conclusion

golds suits a Go developer reading an unfamiliar package who wants to see implementation relations and use sites without opening an IDE, and a package author who wants static HTML documentation checked into their own repository. It does not suit a team that needs a supported toolchain: the author states the project is poorly maintained, says it may crash or show incomplete information on some projects, and the analysis table was produced with Go 1.14.3 while go.mod now declares go 1.26. Verify first that your target packages compile cleanly, since Golds skips anything that does not, and expect to re-run the analysis from scratch after every code change.

## FAQ

### What is golds and how do I install it?

golds is an experimental Go local docs server, docs generator and code reader, with the module path go101.org/golds and the program name golds. The README points to a page on Go101.org for installation and usage details, and states that Go toolchain 1.22 or newer is needed to build and run it.

### What can golds show that ordinary package documentation does not?

It shows type implementation relations, method implementation relations, promoted selectors even on unexported embedded fields, as-parameters-of and as-results-of lists, and the uses of package level types, constants, variables and functions. It can also list types by popularity when JavaScript is enabled.

### Does golds work without JavaScript?

Yes, it is described as JavaScript-off friendly, though the experience is a little richer when JavaScript is on. Features that need JavaScript include listing types by popularity and the keypress toggles for doc expand and collapse states.

### What are the main limitations of golds?

All packages must compile for their docs to be shown, only a code snapshot is analyzed so a change requires a fresh analyzation, and testing packages are not fully parsed. The author also notes the project is poorly maintained and may crash or show incomplete information on some Go projects.

## Sources

- [go101/golds on GitHub](https://github.com/go101/golds)
- [Issues](https://github.com/go101/golds/issues)
- [License: MIT](https://github.com/go101/golds/blob/develop/LICENSE)
- [Project website](https://go101.org/apps-and-libs/golds.html)
- [README](https://github.com/go101/golds/blob/develop/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/go101-golds