Skip to content

Add Google search forms

Sarah German requested to merge sarahg/1369-gps-basic-forms into main

What does this MR do and why?

First MR towards replacing Algolia DocSearch with Google Programmable Search. 🚀

This MR:

  • Renames Algolia components to make it clearer they're specific to Algolia. Even after we retire Algolia, we'll have multiple search backends (Google and Lunr), so components should be named in a way that makes it clear if they're specific to a particular search engine or shared.
  • Adds conditionals in templates to include Google search assets if SEARCH_BACKEND is set to google.
  • Adds handling in the CI pipeline to set Google as the search backend for review apps if the branch contains the string "gps".
  • Modifies the existing Lunr search form component to also work with Google search. While Algolia provided embedded forms, both Google and Lunr will use GitLab UI components.
  • Adds a Google search results component for making the API request and rendering results output on the /search page.

Closes #1369 (closed)

Not in scope yet:

  • Visual design beyond GitLab UI defaults
  • Results pagination
  • Enhanced results
  • Autocomplete/modal search forms

Screenshots, screen recordings, or links to review app

Homepage form Interior form Results page
image image image

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

  1. Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md.
  2. Generate a build that runs Google:
make clean && GOOGLE_SEARCH_KEY="AIzaSyAUCkVNs7JsHYKISjVrVv1PGXg9WQr1MCQ" SEARCH_BACKEND="google" bundle exec nanoc compile

(This key is scoped to our review app domain and localhost:3000; it's OK to share publicly. When we go live with this we will use different keys for production and testing.)

  1. View the build (bundle exec nanoc view) and try searching from the homepage, an interior page, and the /search page. Try terms that will have results as well as terms that won't.
  2. Generate a Google build that won't be able to connect to Google:
make clean && GOOGLE_SEARCH_KEY="abc" SEARCH_BACKEND="google" bundle exec nanoc compile

Verify that a search returns a human-friendly error message.

  1. Generate a build that runs Lunr:
make clean && SEARCH_BACKEND="lunr" bundle exec nanoc compile
make build-lunr-index
  1. Run searches with Lunr. These forms should look the same as the Google forms, but the results will only show titles (and the results will likely be different than Google's).
  2. Generate a build that runs Algolia:
make clean && bundle exec nanoc compile
  1. Verify Algolia search renders our DocSearch form components and still returns results.

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Sarah German

Merge request reports