Data for the site is downloaded fromproxy.golang.org. We monitor theGo Module Index regularly for new packages to add to pkg.go.dev. If you don’t see a package on pkg.go.dev, you can add it by doing one of the following:

• Visiting that page on pkg.go.dev, and clicking the “Request” button. For example:
  https://pkg.go.dev/example.com/my/module

• Making a request to proxy.golang.org for the module version, to any endpoint specified by theModule proxy protocol. For example:
  https://proxy.golang.org/example.com/my/module/@v/v1.0.0.info

• Downloading the package via thego command. For example:
  GOPROXY=https://proxy.golang.org GO111MODULE=on go get example.com/my/module@v1.0.0

Removing a package

If you would like to hide versions of a module on pkg.go.dev, as well as from thego command, you should retract them. Retracting a module version involves adding aretract directive to your go.mod file and publishing a new version. See the Go blog postNew module changes in Go 1.16 and themodules reference for details.

Note that it is possible to retract the latest version of a module; the modules reference link above includes an example. Also note that published versions cannot be reused or modified, and this includes retracted versions.

If you cannot publish a new version with retractions because the source code repository or domain name is no longer accessible, or if you want to hide documentation for all current and future versions, you canfile a request for the pkgsite team to hide your package documentation from pkg.go.dev. Note that the package will continue to be available viago get orgo install unless its module is retracted.

Documentation

Documentation is generated based on Go source code downloaded from the Go Module Mirror atproxy.golang.org/<module>/@v/<version>.zip. New module versions are fetched from index.golang.org and added to pkg.go.dev site every few minutes.

Theguidelines for writing documentation for the godoc tool apply to pkg.go.dev.

It’s important to write a good summary of the package in the first sentence of the package comment. The go.dev site indexes the first sentence and displays it in search results.

Build Context

Most Go packages look and behave the same regardless of the machine architecture or operating system. But some have different documentation, even different exported symbols, for different architectures or OSes. Some packages may not even exist for some architectures.

Go calls an OS/architecture pair a “build context” and writes it with a slash, likelinux/amd64. You may also see the termsGOOS andGOARCH for the OS and architecture respectively, because those are the names of the environment variables that the go command uses. (See thego command documentation for more information.)

If a package exists at only one build context, pkg.go.dev displays that build context at the upper right corner of the documentation. For example,https://pkg.go.dev/syscall/js displays “js/wasm”.

If a package is different in different build contexts, then pkg.go.dev will display one by default and provide a dropdown control at the upper right so you can select a different one.

For packages that are the same across all build contexts, pkg.go.dev does not display any build context information.

Although there are many possible OS/architecture pairs, pkg.go.dev considers only ahandful of them. So if a package only exists for unsupported build contexts, pkg.go.dev will not display documentation for it.

Source Links

Most of the time, pkg.go.dev can determine the location of a package’s source files, and provide links from symbols in the documentation to their definitions in the source. If your package’s source is not linked, try one of the following two approaches.

If pkg.go.dev finds ago-source meta tag on your site that follows thespecified format, it can often determine the right links, even though the format doesn’t take versioning into account.

If that doesn’t work, you will need to add your repo or code-hosting site to pkg.go.dev’s list of patterns (seeGo Issue 40477 for context). Read about how tocontribute to pkg.go.dev, then produce a CL that adds a pattern to theinternal/source package.

Best practices

Pkg.go.dev surfaces details about Go packages and modules in order to help provide guidelines for best practices with Go.

Here are the details we surface:

• Hasgo.mod file. The Go module system was introduced in Go 1.11 and is the official dependency management solution for Go. A module version is defined by a tree of source files, with a go.mod file in its root.More information about the go.mod file.

• Redistributable license. Redistributable licenses place minimal restrictions on how software can be used, modified, and redistributed. For more information on how pkg.go.dev determines if a license is redistributable, see ourlicense policy.

• Tagged version. When the go get command resolves modules by default it prioritizes tagged versions. When no tagged versions exist, go get looks up the latest known commit. Modules with tagged versions give importers more predictable builds. Seesemver.org andKeeping Your Modules Compatible for more information.

• Stable version. Projects at v0 are assumed to be experimental. When a project reaches a stable version – major version v1 or higher – breaking changes must be done in a new major version. Stable versions give developers the confidence that breaking changes won’t occur when they upgrade a package to the latest minor version. SeeGo Modules: v2 and Beyond for more information.

Creating a badge

The pkg.go.dev badge provides a way for Go users to learn about the pkg.go.dev page associated with a given Go package or module. You can create a badge using thebadge generation tool. The tool will generate html and markdown snippets that you can use on your project website or in a README file.

Adding links

You can add links to your README files and package documentation that will be shown on the right side of the pkg.go.dev page. For details, seethis issue.

Keyboard Shortcuts

There are keyboard shortcuts for navigating package documentation pages. Type ‘?’ on a package page for help.

Bookmarklet

The pkg.go.dev bookmarklet navigates from pages on source code hosts, such as GitHub, Bitbucket, Launchpad, etc., to the package documentation. To install the bookmarklet, click and drag the following link to your bookmark bar:Pkg.go.dev Doc

License policy

Information for a given package or module may be limited if we are not able to detect a suitable license. See ourlicense policy for more information.

Feedback

Share your ideas, feature requests, and bugs on theGo Issue Tracker. For questions, please post on the #tools slack channel on theGophers Slack, or email thegolang-dev mailing list.