Client-Side Search

[mattt]

Most likely using Lunr and a pre-built JSON index.

[mattt]

Related to #44

[kean]

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.

[kean]

@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).

Features

• Search on the site
• And search on the page (?)
• Keyboard navigation
• Start searching by pressing f
• Generated index should be served as a plain json file so that it could be used on other websites (use-case: cross-site search from https://kean.blog/nuke/guides/welcome)

Input Position

Option 1

Add it to a header and (optionally) make the header fixed.

Option 2

Add it to the contents. I think this one looks nice, but there are a couple of potential issues.

Cons:

• It can give the wrong impression that it search on the current page instead of the site. To mitigate it, we can do both and provide two sections with search results: "On this page" and "On the site."
• Keyboard navigation. If the user presses f for search, we will have to scroll (?) to the top of the page. Not the end of the world.

Option 3

It could also go somewhere above the ToC.

Pros: looks nice and is always visible without messing with the header size.

Search Results

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).

[Lukas-Stuehrk]

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.

Benchmark details

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

[kean]

Thanks, @Lukas-Stuehrk. I also think the header is the most reasonable choice. Just to add to your list:

• Microsoft – search in the header and they don't even worry about fixing it, which I think makes sense for an API Reference where pages are not too long
• Google – also header, this time fixed. swift-doc doesn't really have a header currently.

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.