Skip to content

Refactor path handling for self-hosted archive sites

Sarah German requested to merge archives-relative-urls into main

What does this MR do and why?

Refactors how we determine if a site is an archived version or not. Our previous logic incorrectly assumed that archived versions always run on archives.docs.gitlab.com, which neglected to account for self-hosted docs sites.

Self-hosted docs sites are likely run in air-gapped/offline environments, so we also needed to use a method for determining archive status that works offline (so, no remote querying of versions.json or archive_versions.json).

This refactor addresses a few issues:

  1. Lunr search result links did not include the version prefix on self-hosted docs instances.
  2. Links to the latest docs from the "archived version" banner were incorrect when viewing a site on archives.docs.gitlab.com. The base URL for this link should always be docs.gitlab.com. Closes #1755 (closed).
  3. The link on the logo in the top-right corner should point to the version-prefixed site homepage. Closes #1768 (closed).

I've bundled these fixes in the single MR for (hopefully) easier backporting.

Feature table:

Version versions dropdown menu "archived version" banner Search
Pre-release (16.10) Shows the same options as docs.gitlab.com. Local links will not work; this is expected since you do not have all the versions available locally. No banner Google, non-prefixed result URLs
Stable (16.9) Shows the same options as docs.gitlab.com. Local links will not work; this is expected since you do not have all the versions available locally. No banner Google, non-prefixed result URLs
Archive (16.6) Shows only the active version (16.6) and a link back to docs.gitlab.com/archives. Banner (interior pages only) Lunr with prefixed URLs
Offline archive (16.6, sans wifi) Shows only the active version (16.6) and a link back to docs.gitlab.com/archives. Banner (interior pages only) Lunr with prefixed URLs

Screenshots, screen recordings, or links to review app

No visual changes. Can't validate these on the review app. See below for testing steps.

How to set up and validate locally

1. Test the pre-release

  1. Run a fresh compile: make clean && make view
  2. Browse the site at http://localhost:3000 and verify version-related features* (see below) work as expected.

Validation:

  • Shows the same options as docs.gitlab.com. Local links will not work; this is expected since you do not have all the versions available locally.
  • No banner.
  • Google search, non-prefixed result URLs.

2. Test the latest stable release

  1. Stop the server (CTRL+C) and set yourself an env var: export VER="16.9"
  2. Create a "release" version (this runs the same steps as we do through single.Dockerfile): ./scripts/normalize-links.sh public $VER && mkdir $VER && scripts/minify-assets.sh $VER/ public/ && mkdir dest && mv $VER dest/
  3. Move this into the public directory so we can browse it locally: mv dest/$VER public
  4. Run the local server: bundle exec nanoc view
  5. Browse the site at http://localhost:3000/16.9 and verify version-related features* work as expected.

Validation:

  • Shows the same options as docs.gitlab.com. Local links will not work; this is expected since you do not have all the versions available locally.
  • No banner.
  • Lunr search with prefixed URLs.

3. Test an online archived release

  1. Clean up the last test (rm -rf dest) and hit CTRL+C to quit the last nanoc view process.
  2. Set a new env var: export VER="16.6"
  3. New compile: make clean && SEARCH_BACKEND="lunr" CI_COMMIT_REF_NAME=$VER make compile
  4. Create a "release" version (this runs the same steps as we do through single.Dockerfile): ./scripts/normalize-links.sh public $VER && mkdir $VER && scripts/minify-assets.sh $VER/ public/ && mkdir dest && mv $VER dest/
  5. Move this into the public directory so we can browse it locally: mv dest/$VER public
  6. Run the local server: bundle exec nanoc view
  7. Browse the site at http://localhost:3000/16.6 and verify version-related features* work as expected.

Validation:

  • Shows only the active version (16.6) and a link back to docs.gitlab.com/archives.
  • Banner (interior pages only)
  • Lunr search with prefixed URLs.

4. Test an offline archived release

Turn off your wifi (😱) and browse the test online archived release from above. This should work the same as before, but the "Archived version" banner will not appear in this scenario.

You may need to do a hard refresh or use an incognito window if your browser has cached the banner data from the previous test.

Validation:

  • Shows only the active version (16.6) and a link back to docs.gitlab.com/archives.
  • Banner (interior pages only)
  • Lunr search with prefixed URLs.

5. Test the Docker build

In theory the test case above works the same as it would built through Docker, but it would be helpful to double-check this since I could not get the Docker builds to work locally (#1765 (closed)).

  1. docker build -f dockerfiles/single.Dockerfile . --build-arg VER=16.6 --build-arg SEARCH_BACKEND="lunr" --tag docs:16.6
  2. Run the site using this image: docker run -it --rm -p 4000:4000 docs:16.6
  3. Visit the site http://localhost:4000/16.6 and verify version-related features* work as expected.

Validation:

  • Shows only the active version (16.6) and a link back to docs.gitlab.com/archives.
  • Banner (interior pages only)
  • Lunr search with prefixed URLs.

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