Skip to content

Add page ranking capabilities for Algolia search

Sarah German requested to merge 1130-algolia-custom-ranking into main

What does this MR do and why?

This MR adds a mechanism to set an Algolia pageRank metatag on a per-page or per-section basis. This tag is crawled by Algolia and used to boost (or un-boost) the page from search results (Algolia docs).

The metatag looks like this: <meta name="docsearch:pageRank" content="100">

  • 100 is the default value and set on all pages except those overridden in the CUSTOM_PAGERANKS hash.
  • Pages with a value >100 are boosted in search results
  • Values < 100 will drop in results

This MR also adds a docsearch:level tag that notes the page hierarchy based on the URL (how many levels deep is it nested?). Pages that are nested less deep should be favored in search results.

Closes #1130 (closed). We will continue to fine-tune search (probably forever), but I think this MR does close the investigation into how to weight/rank results.

Screenshots, screen recordings, or links to review app

Before After
image image
image image
image image
image image

Examples

The new metatags can be validated by inspecting the page source and finding the docsearch:pageRank and docsearch:level meta tags (in the <head> section of the document).

Default page weight of 100:

API docs with a weight of 50:

Developer docs with a weight of 20:

Testing actual search behavior

The review app includes the new tags and is configured to search our test index. This should give us different behavior than what we see on the production site.

  1. Run a search on http://1130-algolia-custom-ranking.35.193.151.162.nip.io/
  2. Compare your results to what you see on https://docs.gitlab.com/
  3. Tip: Using the standalone search page for testing allows for sharing results more easily (you can link directly to a search query like this)

How to set up and validate locally (optional)

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. Add a path and weight to the CUSTOM_PAGERANKS hash in lib/helpers/algolia_rank.rb (or modify an existing one)
  3. Recompile the site (bundle exec nanoc compile)
  4. Verify the docsearch:pagerank metatag has the appropriate value

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