Text of github.com › golang › go › issues › 41587 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

x/pkgsite: redesign - the documentation section · Issue #41587 · golang/go · GitHub

Skip to content You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert x/pkgsite: redesign - the documentation section #41587 New issue Copy link New issue Copy link Closed Closed x/pkgsite: redesign - the documentation section #41587 Copy link Labels FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.

The path to resolution is known, but the work has not been done. pkgsite Milestone pkgsite/design-2020 Description julieqiu opened on Sep 23, 2020 Issue body actions We'll be redesigning pkg.go.dev based on feedback received over the last year. This is the second 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 The documentation section of the pkg.go.dev/<path> page will have the following changes: Documentation index section will be added back Top level heading for each section will always be present New features for copying and viewing source code Design Here's a preview of what the documentation section 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.

Documentation Index Based on feedback that we've received, we understand that users find viewing the full package API useful, so the documentation index will be added back. At the same time, we’ve heard that having a sidenav is useful for navigating the documentation, especially when the documentation is very long. We plan to keep this feature as well. In the new design, the function and type sections will be closed by default, since having everything expanded can be overwhelming.

When a user clicks on a function or type from the index, that section will auto-expand. Empty Sections We want to create a consistent structure across different packages in the documentation section. Therefore, when a section in the documentation is empty, we will still display the section header (for example, "Variables"), along with a message indicating it is empty ("There are no variables in this pacakge."): We believe that doing so allows users to become familiar with the structure of this section over time.

More importantly, UX research has shown that consistent documentation is important for accessibility. For screen reader users, having a consistent documentation structure allows them to predict the page structure. This means, for instance, if they know “Variables” is the fourth header, and they’re looking for variables, they can bounce to the fourth header without listening to each of the first three. New Features Copy Next to each code block, we will be adding a copy button, so that users can easily copy and paste the code in that block.

View Source Code We also want to make jumping to the source identifier a more discoverable feature. To do so, if a block of code corresponds to a function, type or method, we will also include a source code widget. Clicking on that link will take users to the source code. Related Issues x/pkgsite: LHS navigation panel is "lossy" #40612 : LHS navigation panel is "lossy" x/pkgsite: landing page for docs provides no structural information at a glance. #40715 : landing page for docs provides no structural information at a glance x/pkgsite: auto-expand left sidebar #40577 : auto-expand left sidebar x/pkgsite: malformed function signature on LHS index #41486 : malformed function signature on LHS index x/pkgsite: confusing scrolling (and header scrolls off the top) #40773 : confusing scrolling (and header scrolls off the top) Reacted by Ilia Choly, Alan D.

Salewski, Matt Holt, Alex Hamlin and Swastik Baranwal Reacted by Tom Thorogood, Matt Holt, Swastik Baranwal and Arctic Ice Studio Reacted by Tom Thorogood, Swastik Baranwal and Arctic Ice Studio Activity julieqiu closed this as completed on Sep 23, 2020 gopherbot added pkgsite on Sep 23, 2020 gopherbot added this to the Unreleased milestone on Sep 23, 2020 julieqiu changed the title [-] x/pkgsite: <this issue is a placeholder for a future issue> [/-] [+] x/pkgsite: redesign - the documentation section [/+] on Sep 23, 2020 julieqiu reopened this on Sep 23, 2020 julieqiu added NeedsFix The path to resolution is known, but the work has not been done.

The path to resolution is known, but the work has not been done. on Sep 23, 2020 julieqiu modified the milestones: Unreleased , pkgsite/design-2020 on Sep 23, 2020 tooolbox commented on Sep 24, 2020 tooolbox on Sep 24, 2020 More actions Thanks for posting, @julieqiu , my 2 cents: Based on feedback that we've received, we understand that users find viewing the full package API useful, so the documentation index will be added back.

Great!! 🎉 At the same time, we’ve heard that having a sidenav is useful for navigating the documentation, especially when the documentation is very long. We plan to keep this feature as well. In the new design, the function and type sections will be closed by default, since having everything expanded can be overwhelming. When a user clicks on a function or type from the index, that section will auto-expand. This sounds good and the mock GIF looks good as well.

Initial reaction is that it's cool that the README is in the sidebar as well, and I feel like the header (with package version, refresh date, license, etc.) seems improved. We want to create a consistent structure across different packages in the documentation section. Therefore, when a section in the documentation is empty, we will still display the section header (for example, "Variables"), along with a message indicating it is empty ("There are no variables in this pacakge.") I think this is a great idea.

Next to each code block, we will be adding a copy button, so that users can easily copy and paste the code in that block. Sounds neat; not major, but neat. We also want to make jumping to the source identifier a more discoverable feature. To do so, if a block of code corresponds to a function, type or method, we will also include a source code widget. Clicking on that link will take users to the source code. Sounds good; it would be cool to have an example as well.

Linking into appropriate source locations is a very useful aspect of the docs, so expanding this is capability sounds like a move in the right direction, although it could perhaps be overdone with links in every nook and cranny. Thanks again! Reacted by Julie Qiu julieqiu commented on Sep 24, 2020 julieqiu on Sep 24, 2020 Member Author More actions Thanks @tooolbox ! That's great to hear :) Sounds good; it would be cool to have an example as well.

Linking into appropriate source locations is a very useful aspect of the docs, so expanding this is capability sounds like a move in the right direction, although it could perhaps be overdone with links in every nook and cranny. Clicking on <> in screenshot under New Features would take you to the source code. On hover, both <> and copy icon will display a tooltip that provides context on what that icon does. Reacted by Matt Mc Delta456 commented on Oct 3, 2020 Delta456 on Oct 3, 2020 More actions The redesign looks amazing!

Can we also show how many downloads or go get s were there for the module as NPM, PIP etc also show it? I most of the time have to see git clones. PS: I didn't want to open a separate issue for this. julieqiu commented on Oct 6, 2020 julieqiu on Oct 6, 2020 Member Author More actions @Delta456 , glad to hear! If you don't mind, could you please raise a separate issue for this? While the feature you suggest sounds interesting, it doesn't fit under the umbrella of this design issue. julieqiu commented on Oct 28, 2020 julieqiu on Oct 28, 2020 Member Author More actions A preview of the redesign is now available on beta.pkg.go.dev !

Give it a try, and please fi

The rest of this page is on the live site.