https://adnano.co/2022/02/10/godocs.io-one-year-later/

godocs.io one year later

2022-02-10 on adnano.co

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:^1

<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!

---------------------------------------------------------------------

 1. These are not currently used by godocs.io, but they may be used
    in the future. -[?]

This work is licensed under a CC-BY-SA-4.0 license. Source code
Have a comment on one of my posts? Send an email