Add version prefixes in frontend files
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 |
---|---|
![]() |
![]() |
How to set up and validate locally
- 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. - Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md.
- Check out this branch, run
make clean
, then compile the site (bundle exec nanoc compile
). - 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.
- 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 frompublic/$VERSION/assets
instead (if you don't do this, you won't see 404s like you would on the archives site). - 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.) - 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/
- 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)
- 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.
- 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.
-
I have evaluated the MR acceptance checklist for this merge request.