x/pkgsite: redesign - the pkg.go.dev/<path> page

[julieqiu]

We'll be redesigning pkg.go.dev based on feedback received over the last year. This is the first in a series of issues about plans for the pkgsite/design-2020 milestone. Comment below with any feedback or suggestions related to this issue!

Overview

We will redesign the pkg.go.dev/<path> page such that information is organized around a path. A path represents a directory in a particular version of a module. A path may be a package, the root of a module, and/or contain subdirectories.

Currently, the landing page for a given path differs for each of these cases, even when a path fits into more than one case. For example, golang.org/x/tools (a module) has two landing pages - pkg.go.dev/mod/golang.org/x/tools shows the overview tab and pkg.go.dev/golang.org/x/tools shows the subdirectories tab. golang.org/x/tools/go (a subdirectory) shows the subdirectories tab and golang.org/x/tools/go/packages (a package) shows the doc tab.

These different pages will become a single page in the new design.

Design

The changes to the pkg.go.dev/<path> page described below are motivated by wanting to make the page consistently useful and predictable. Here's a preview of what that page will look like:

Note: The images shown in this issue are mocks, so the data may not accurately represent the exact contents of a given package.

1. Single URL for all paths

Each pkg.go.dev/<path> page will display information for that path, regardless of its type.

The existing “/mod” namespace will be deprecated. Requests to pkg.go.dev/mod/<path>[@version] will be redirected to pkg.go.dev/<path>.

The default page will not have a tab query param.

2. Consistent landing page

To create a consistent landing page, content on the doc, overview and subdirectories tabs will be consolidated into a single page. A pkg.go.dev/<path> page will always display at least one of the following:

• README
• Documentation
• Source Files
• Directories

If a path does not have content for one of these sections, that section will be omitted from the page.

3. README section

Currently, the overview tab only shows the README if present at the module root. By organizing information around a path, we plan to display the README section, only if a README is present at that path.

For example, pkg.go.dev/go-hep.org/x/hep@v0.27.0 will display github.com/go-hep/hep/blob/v0.27.0/README.md, and pkg.go.dev/go-hep.org/x/hep/hplot@v0.27.0 will display https://github.com/go-hep/hep/blob/v0.27.0/hplot/README.md in the README section.

On the other hand, pkg.go.dev/net/http will not display a README section, because one does not exist at that path. The first section displayed on that page will be the documentation section.

4. Documentation section

The documentation section will be described in more detail in #41587.

5. Source Files and Directories sections

The UI for source files and directories will be similar to the existing layout. The Directories section will display both subdirectories and nested modules relative to the current path.

We are also exploring using a tree structure in the directories section, since some pages have lots of subdirectories (example: subdirectories tab for cloud.google.com/go). This will be discussed in a later issue.

Related Issues

• x/pkgsite: modules with no package at the root directory are shown awkwardly #36791: modules with no package at the root directory are shown awkwardly
• x/pkgsite: ?tab=doc is added automatically #37351: ?tab=doc is added automatically
• x/pkgsite: add import / imported by counts #37912: add import / imported by count
• x/pkgsite: rethink module page #38087: rethink module page
• x/pkgsite: show README.md of "subpackages" in overview tab #38513: show README of subpackage in overview tab
• x/pkgsite: add repository link on documentation page #39218: add repository link on documentation page
• x/pkgsite: support versions tab for directory view #40942: support versions tab for directory view
• x/pkgsite: subdirectories are missing for nested modules #38596: subdirectories are missing for nested modules

[mvdan]

If a path is also the root of a module, could you clarify how the UI would look for that case? What if it's both the root of a module and the package - which information would show up by default?

Also, I assume you're using the term "directory" to mean either "package" or "module". I think that might be confusing to users, because some/module/v2 might not actually be a directory anywhere, since the /v2 would just be a product of semantic import versioning. There, the directory would just be some/module. So I still think that talking about "paths" is the simplest and most well understood; the distinction then is whether paths are for packages, or for modules. And you still have the concept of sub-paths.

[julieqiu]

If a path is also the root of a module, could you clarify how the UI would look for that case? What if it's both the root of a module and the package - which information would show up by default?

Regardless of whether the path is a package or a module, we'll be displaying the contents as described under 2. Consistent landing page. Label(s) will be displayed next to the title in the header to indicate what the path type is.

To give a few examples:

• pkg.go.dev/mvdan.cc/sh/v3 (a module), will show the README and Directories sections, with a module label in the header.

• pkg.go.dev/github.com/russross/blackfriday/v2 (a package and a module) will show the README, Documentation, and Source files sections, with a module and a package label in the header. It doesn't have any subdirectories, otherwise the Directories section would be shown as well.

• pkg.go.dev/golang.org/x/tools/cmd/godoc (a command) will show the Documentation and Source files sections, with a command label in the header. It doesn't have a README or subdirectories, otherwise those sections would be shown as well.

So I still think that talking about "paths" is the simplest and most well understood; the distinction then is whether paths are for packages, or for modules. And you still have the concept of sub-paths.

Thanks for the suggestion! Edited the issue above to use "path" instead of "directory" where applicable.

[julieqiu]

A preview of the redesign is now available on beta.pkg.go.dev! Give it a try, and please file an issue for any bugs.

See #41585 (comment) also for instructions on how to run the beta site locally.