godocs.io one year later

It's been more than a year since we started godocs.io. For those unaware, godocs.io is a fork of the now-defunct godoc.org which serves documentation for Go packages. Some users may prefer godocs.io for its lightweight pages, simpler user interface, lower resource consumption, or ability to render documentation regardless of project license. I am pleased to announce version 1.0 of gddo, the software which powers it all. Since forking, we've made many improvements. As a result, gddo now supports:

• Viewing documentation for Go modules
• Fetching modules from a Go module proxy
• Fetching modules from your local Go module cache
• Running without a database for local usage
• Rendering documentation for all Go platforms
• Parsing forge meta tags for module-aware source links
• Serving documentation over Gemini

Along the way we've removed over 9,500 lines of Go code, bringing the codebase down to around 6,000 lines of Go code. We invite you to spin up an instance of gddo yourself, or check out the hosted instance at godocs.io.

Forge meta tags

I'd like to draw special attention to forge meta tags. These tags are used by godocs.io to link to module source code. They have a few advantages over the go-source meta tags which they replace, the main one being that they work with Go modules as they allow linking to specific versions of code (or references in Git terminology). They are also not tied to a specific programming language.

When fetching the documentation for a Go module (e.g. example.org/project), godocs.io will make an HTTP request to the site and look for forge meta tags. These tags have been added to SourceHut's Git and Mercurial services. We would like to encourage other forges to adopt these tags as well.

If you operate a software forge, or have a vanity import path, simply add the following tags to every project page on your site (be sure to tweak the URLs to suit the forge/project):

<meta name="forge:summary" content="https://example.org/project">
<meta name="forge:dir" content="https://example.org/project/tree/{ref}/item/{path}">
<meta name="forge:file" content="https://example.org/project/tree/{ref}/item/{path}">
<meta name="forge:rawfile" content="https://example.org/project/blob/{ref}/{path}">
<meta name="forge:line" content="https://example.org/project/tree/{ref}/item/{path}#L{line}">

You may also want to add the following VCS meta tags, which are similar to go-import meta tags but not tied to a specific language:¹

<meta name="vcs" content="git">
<meta name="vcs:clone" content="https://example.org/project">
<meta name="vcs:clone" content="git@example.org:project">
<meta name="vcs:default-branch" content="master">

For more information, see the RFC. Special thanks to ~ancarda for authoring it!