Skip to content

Add version prefixes in frontend files

Sarah German requested to merge sarahg-fe-asset-paths into main

What does this MR do and why?

Adds missing version prefixes to frontend assets and search result links.

We need these fixes in order for the site to work properly on domains that include a version prefix (e.g, archives.docs.gitlab.com/15.6).

Closes:

Screenshots, screen recordings, or links to review app

Before After
image image

How to set up and validate locally

  1. Add this line to the /etc/hosts file on your computer: 127.0.0.1 archives.docs.gitlab.com. This will allow you to preview the site using the archives domain, which we'll need for validating search result links.
  2. Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md.
  3. Check out this branch, run make clean, then compile the site (bundle exec nanoc compile).
  4. Pull down an archived version for testing:
docker create -it --name gitlab-docs-lunr-15.9 registry.gitlab.com/gitlab-org/gitlab-docs/archives:15.9
docker cp gitlab-docs-lunr-15.9:/usr/share/nginx/html/15.9 public/
docker rm -f gitlab-docs-lunr-15.9

This will put a full 15.9 build with Lunr search in your public directory.

  1. Rename or remove public/assets/. This will make it clearer if there are assets loading from this directory when viewing a page; assets should load from public/$VERSION/assets instead (if you don't do this, you won't see 404s like you would on the archives site).
  2. Turn on the local web server: bundle exec nanoc view and visit the 15.9 homepage: http://archives.docs.gitlab.com:3000/15.9. You will see missing assets (e.g, no background image or icons), and search won't work. This is our bug. (Note that you need "http" and not "https" in the URL for testing here as we don't have HTTPS available locally.)
  3. Backport the Lunr search fix from this branch into our 15.9 test site: cp public/frontend/search/lunrsearch.js public/15.9/frontend/search/
  4. Run the updated normalize-links script from the gitlab-docs root: ./scripts/normalize-links.sh "public" "15.9"

(Note: You can't run the script on a Mac due to differences with sed unless you install gnu-sed and change your PATH like this: https://medium.com/@bramblexu/install-gnu-sed-on-mac-os-and-set-it-as-default-7c17ef1b8f64)

  1. Reload the 15.9 site and check the browser console for 404s. You should no longer see missing assets (PNGs, SVGs, JSON, etc). Be sure to minimize the window to small-width to make sure assets for mobile breakpoints load as well.
  2. Run a search from the homepage, an interior page, and the standalone search page (/15.9/search). You should get results back from Lunr that point to the correct archives site version.

When you're done testing, don't forget to revert the change you made to /etc/hosts in step 1. 😄

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