Add a metatag with page trail
What does this MR do and why?
In !4011 (merged), we added a JSON-LD schema to each page that defines its breadcrumb trail, based on the global nav. Google uses this to show a breadcrumb trail alongside search results.
However, this data is not included in responses from the Google Programmable Search JSON API as expected. Turns out that Programmable Search Engine (PSE) only passes a very limited subset of these schemas to search results when using PSE.
We can work around this by including the breadcrumb trail in a metatag. Custom metatags are passed alongside search results from the API (we use the metatag approach for the section filters on the results page).
This MR uses output from the function added in the previous breadcrumb MR, just formatted as a string, and adds that to a metatag which is included site-wide.
References:
- JSON-LD limitations: https://developers.google.com/custom-search/docs/structured_data#using-json-ld
- Metatags FTW: https://developers.google.com/custom-search/docs/structured_data#using-meta-tags
Screenshots, screen recordings, or links to review app
View HTML source of pages and look for the gitlab-docs-breadcrumb
metatag. Each page in the hierarchy should be separated with a comma. For example, the tag should look like this for a 6th-level page:
<meta name="gitlab-docs-breadcrumbs" content="Use GitLab, Build your application, CI/CD, Auto DevOps, Customize, Multiple Kubernetes clusters">
- level 1: https://gps-breadcrumbs-metatags.docs.gitlab-review.app/ee/user/ai_features.html
- level 2: https://gps-breadcrumbs-metatags.docs.gitlab-review.app/ee/administration/get_started.html
- level 3: https://gps-breadcrumbs-metatags.docs.gitlab-review.app/ee/administration/feature_flags.html
- level 4: https://gps-breadcrumbs-metatags.docs.gitlab-review.app/ee/tutorials/container_scanning/
- level 5: https://gps-breadcrumbs-metatags.docs.gitlab-review.app/ee/user/application_security/dast/checks/
- level 6: https://gps-breadcrumbs-metatags.docs.gitlab-review.app/ee/topics/autodevops/multiple_clusters_auto_devops.html
How to set up and validate locally
Numbered steps to set up and validate the change are strongly suggested.
-
Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md. -
Compile the site: make compile
-
Verify nothing crashes during compilation -
Verify pages include the gitlab-docs-breadcrumbs
metatag. On a page that is not in the nav (e.g, the homepage), the tag should exist, but its content will be empty.
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.
-
I have evaluated the MR acceptance checklist for this merge request.