💾 Archived View for log.pfad.fr › 2022 › vanitydoc captured on 2024-08-18 at 16:58:52. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Self-hosting Go documentation on vanity URL

[Update 2024] Vanitydoc reloaded

I updated this post after updating large parts of vanitydoc (it can now serve the documentation of the current module and generate static files of multiple modules at once).

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 that 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:

4d63.com/vangen (static html, with links to repo and doc)

code.rocketnine.space/tslocum/godoc-static (static godoc)

go.yhsif.com/vanity (redirects to pkg.go.dev)

kkn.fi/vanity (redirects to pkg.go.dev)

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

Introducing vanitydoc

code.pfad.fr/vanitydoc

The vanitydoc command has the following features:

static generation of HTML
inclusion of the `go-import` meta tags (obviously)
dark and light theme
static generation of Gemtext (for gemini hosting)
inclusion of the `VCS Autodiscovery` meta tags

The last point is an RFC that aims at increasing interoperability between software forges and third-party tools:

VCS Autodiscovery RFC

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

code.pfad.fr/risefront

its import path is a vanity URL, which is a static site serving the latest documentation of the package (accessible via https and gemini protocols thanks to sourcehut pages)

code.pfad.fr/risefront

the presence of the meta tags, allows godocs.io (alternative to pkg.go.dev) to generate links to the source code

godocs.io/code.pfad.fr/risefront

while the actual source code is hosted on Codeberg

https://codeberg.org/pfad.fr/risefront

Basic usage

To preview the documentation of the module of the current folder, simply run `vanitydoc` (it does not rely on `go list` since March 2023):

go run code.pfad.fr/vanitydoc@latest

To generate the static files, a JSON file must be prepared. Its format is documented in the README:

Configuration documentation of vanitydoc

Requirements

The package requires go 1.19 for compilation (it uses the new go/doc package)

Future work

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

Listing the packages currently requires the go toolchain. Figure out a way to compile "go list" inside the package (done in March 2023).
The generated documentation is for the current build tags. Generate all sets of build tags under specific URLs.
Document the version that was used to generate the documentation (golang.org/x/tools/go/vcs package is missing cmd/go/internal/vcs.Cmd.Status)

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

📅 2022-12-02

Back to the index

Send me a comment or feedback