Open mattt opened 4 years ago
Related to #44
I'm using lunr.js on https://kean.blog/nuke/guides/welcome and can build something similar for swift-doc. I built it using plain JS without any dependencies.
@mattt, do you have any preferences in terms of the implementation or design? I'm not entirely sure where to add it. I have a couple of options in mind (these are just mockups).
f
Add it to a header and (optionally) make the header fixed.
Add it to the contents. I think this one looks nice, but there are a couple of potential issues.
Cons:
f
for search, we will have to scroll (?) to the top of the page. Not the end of the world.It could also go somewhere above the ToC.
Pros: looks nice and is always visible without messing with the header size.
I think it would be nice if the search results would simply appear on the page using the same design as currently used for the main content. (Highlighting a selected item for programmatic navigation).
To collect additional data and to get an idea what is expected and familiar for users, I did a short benchmark (see details below). Search bar in the header seems to be the most used pattern by now used in developer documentations.
And I completely agree with your reasoning, @kean. I think you described the pros and cons of the different approaches really well. Option 2 definitely looks like it searches on the current page only. Personally, I like the visuals of Option 3 with the search in the side bar the most. But there I also see the problem that users could think that it only searches for the current page, especially because it's very close to the "on this page" element.
Stripe has the search bar in the header.
Apple has a super small search icon in the header which expands to a search bar
Github has the search bar in the header
React has the search bar in the header
Twilio has a search bar with rather bad contrast in the header
Thanks, @Lukas-Stuehrk. I also think the header is the most reasonable choice. Just to add to your list:
As for the search results, maybe it's best not to re-invent the wheel and add a dropdown with search results. I can come up with something basic and it can be improved later if needed.
Most likely using Lunr and a pre-built JSON index.