Self-hosting go documentation on vanity URL

2 December 2022, on Olivier's log

Go packages are identified by their import path. This import path usually starts with the URL where the code is hosted, but it can also be another domain which informs the go tool where the actual code can be downloaded (so-called "vanity import paths"). Using a domain you control is great because it allows for the code to be moved between software forges without any disruption for people using the package.

There are already a couple of packages able to automatically generate html with the right meta tags: (static html, with links to repo and doc) (static godoc) (redirects to (redirects to

However I wasn't delighted with any of those solutions, so I developed my own.

Introducing vanitydoc

The vanitydoc command has the following features:

The last point is an RFC which aims at increasing interoperability between software forges and third party tool:

VCS Autodiscovery RFC

To show an example of interoperability, consider one of my other package:

Basic usage

To generate the documentation for a module, simply list the packages using `go list -json` and pipe them to `vanitydoc`:

go list -json="Dir,ImportPath,Doc,Module" ./... | \
go run -html=dist/html -gemtext=dist/gmi gitea://


Future work

I am currently happy of this package and plan to use it as-is. It could be improved in multiple ways, however I didn't find an elegant solution to the following problems yet:

Feel free to send a patch on codeberg or by email to contribute to this package (licensed under BSD-3-Clause)!