x/pkgsite: search in page is made less useful by hidden content

[mvdan]

Steps to reproduce the good godoc.org behavior:

1. Go to https://godoc.org/github.com/dgraph-io/badger
2. Press Ctrl-F (or whichever "search in page" shortcut)
3. Type "NewIterator"
4. Get taken straight to "func (txn *Txn) NewIterator(opt IteratorOptions) *Iterator", its first occurrence - in the index

Now, on pkgsite:

1. Go to https://pkg.go.dev/github.com/dgraph-io/badger/v2@v2.2007.2
2. Press Ctrl-F (or whichever "search in page" shortcut)
3. Type "NewIterator"
4. The first result is about a quarter of the page in, but I don't see a match. Weird. Press enter again for the next match.
5. Still an invisible/hidden match. I have to press enter a few more times to get taken to the index, the visible result I want.

Another way to look at it is that the search on godoc.org results in 6 matches, but the same search results in 10 matches on pkgsite. The first four matches are hidden, which make up for the difference with godoc.org.

Can we get rid of those four hidden matches altogether? Especially since they somehow match before the index, which is very close to the top.

[mvdan]

The reason I find this issue pretty significant is that I heavily rely on Ctrl-F to quickly find an item in godoc's index. This does not work well on pkgsite, as shown above.

[gopherbot]

Change https://golang.org/cl/272608 mentions this issue: content/static: expand readme when browser text search is activated

[mvdan]

I don't think the fix above is what we want, though. When I search the page, I want the first hits to match the page index, not the README.

[jamalc]

There isn't a simple way to get rid of the hidden matches but I think the best solution here is to make the hidden content visible because it does contain the text from the search. For your particular use case using the jump to Identifier feature by pressing the 'F' key would get you to the function right away.

[mvdan]

Hm. I can live with using F instead of ^F, though I admit that will be fairly painful as it's hard to retrain muscle memory. It's unfortunate that the plain page search is less useful in pkgsite compared to godoc - I'm surprised that there is no way to make hidden content not match page search, or to just not have the hidden text be present in the HTML at all.

[jamalc]

I like being able to search through all the text without having to expand the readme but do see your point. I'd like to merge this for now so that the experience doesn't feel completely broken and add @Joanne881107 @fflewddur for product / UX input.

We could keep the hidden content out of text search by picking a split point within the readme (maybe the second heading for markdown files and N characters/words/lines for text files) then rendering the two sections in separate elements with the second hidden from the page. This would mean the collapsed section size will vary but it would create a cleaner break within the readme section.

[mvdan]

Here's another reason why the expanded README shouldn't show by default: it makes skimming the page much harder. For example, where is the IsNull variable defined in https://pkg.go.dev/github.com/frankban/quicktest?

The answer is under the Checker type, but because the expanded README also contains a heading/description for it, it's confusing.

Forcing all users to use the F shortcut to ignore the README is an option, but not a very good one. I still think that mixing in the entire README with the rendered docs isn't a very good idea. At minimum, if I'm looking at the README, it should be entirely clear that it's not rendered godoc. Ideally, the README should only render in full if I explicitly expand it.