Search styles

[jeffmaher]

Stories

• As a reader of a guide, I want to search a guide's text so that I can quickly find the information I want without having to manually navigate through the entire guide.

Notes

• See the component doc for more information
• This ticket covers both design and development tasks. Change assignee of the ticket based on who has the next action, and remove the person or people that no longer have an action. It's expected that a ticket will get passed back and forth a few times.

Done When

• [ ] UX: Component design is drafted and shared for review
• [ ] Dev: Component design is reviewed and approved
• [ ] Peer UX: Compontent design is reviewed and approved
• [ ] Dev: Component style and markup is developed and shared for PR review
• [ ] Dev: Documentation on how to use component is drafted
• [ ] UX: Component style and markup is reviewed and approved
• [ ] Peer Dev: Component style and markup is reviewed and approved
• [ ] Dev: Infrastructure is configured to support search
• [ ] Dev: Documentation is written on how to setup search
• [ ] Component is available for use

[jrubenoff]

The search provider we choose will dictate the design here. So, last week, I researched static site search engines.

Here's what I came up with.

Algolia

This provider has a free plan that would give us 10K searches per month. StorybookJS and Tailwind use Algolia for their docs.

They have a search widget that seems to have some nice aria- attributes built in (although I haven't tested it in screen readers.) Here's what that looks like:

Alternatively, this tutorial for setting up Algolia on 11ty Serverless and Netlify offers a server-side approach that might be more performant.

To be honest, the Algolia docs seem a little intimidating for a project of this scope.

PageFind

I noticed that 11ty's docs use PageFind for client-side search. Unlike Algolia, I found it insanely easy to set up and customize. It took me half an hour to bootstrap an 11ty instance, install PageFind, and make this demo:

A few big caveats:

• PageFind hasn't paid a lot of attention to accessibility. No aria- attributes for live updates of results, no <label> tag for the search input, etc. The library doesn't let you customize its markup, so we'd be stuck with its output.
• We'd need to add a post-build command to Netlify to re-index any content changes.
• It's a ~50KB client-side JS library. To reduce overall page weight, it probably makes sense to link to a dedicated search page, rather than embed a search field on each page of the guide.

Google / DuckDuckGo / etc.

The laziest approach would be to add an input that performs a site-specific search on a commercial search engine.

For example, if you were to search for "government", the Submit button could take you here:

This approach technically "works" but there are a few big issues:

• The visitor would have to leave our site, removing them from the reading experience
• If the search engine's results are subpar or undesirable, we have no way to quickly tweak the index

---

@jeffmaher @SMakaiTakori Let me know what approach you think makes the most sense for this project!

[jrubenoff]

Just remembered a fourth option: Lunr

Here's a tutorial on setting it up with 11ty and Netlify Serverless.

The setup process seems similar to Algolia, but it's open source.

[admoorgit]

@jrubenoff capturing notes I took from convo with Jeff about search:

• While Page Find is appealing due to its ease of setup, it's a no-go from an accessibility standpoint. Thanks for flagging. - We think Netlify has a built-in (or easily to access) search engine — maybe Algolia? Suggest we start there. The caveat is if it comes in the format shown in your previous post, we'll likely need to do some configuring as the presentation of results is a little funky, imo
• Duck Duck Go is a viable backup, though no need to set this up unless things go south (but check with us first)

@jeffmaher feel free to add anything else that comes to mind

[jeffmaher]

@jrubenoff Continuing on Algolia prototype.

[jrubenoff]

Progress update:

• Algolia has this crawler for Netlify that creates a search index for the site, but you still have to manually integrate it with your static site and build the front-end.
• I tried and failed to get this tutorial working due to various CLI errors. Maybe it's a problem with my dev environment because web searches on the issues I'm seeing turn up zero results.
• If I have time, I'll create a non-functional markup / style pattern for search results in a branch.

[bglw]

Sneaking into this issue from Pagefind 👀

If it helps I'm happy to prioritize any accessibility work on the default UI. There's also a modular UI that does let you control the markup. Happy to help in any case.

[SMakaiTakori]

• Algolia has this crawler for Netlify that creates a search index for the site, but you still have to manually integrate it with your static site and build the front-end.
• I tried and failed to get this tutorial working due to various CLI errors. Maybe it's a problem with my dev environment because web searches on the issues I'm seeing turn up zero results.
• If I have time, I'll create a non-functional markup / style pattern for search results in a branch.

Thank you for looking into this @jrubenoff , I reviewed the tutorial you shared and it does look like you have to do a good amount of manual setup for the results, which I feel shouldn't be a problem once we get there. If you have time, a style pattern for this would be great. Thanks!

[jeffmaher]

Josh is pushing up styles for the future search implementation, but Algolia didn't work out.

Also, switching the focus of this ticket to just be on styles and not the actual search tool itself. This helps us prioritize look and feel while Josh is around this week, and then the dev team can pick back up later.

[jeffmaher]

Thanks for the note @bglw ! We'll ping back in the issue if we wind up going with PageFind.

[jeffmaher]

Status update:

• Draft PR is up for this
• ^ Just has the styles

[jeffmaher]

Styles are in a PR, but we just need to figure ou the search engine to put it on top of.