Skip to content

Add functions for determining site version

Sarah German requested to merge versions-logic into main

What does this MR do and why?

Adds Hugo template functions that determine the site version.

This MR also includes some developer documentation about writing template functions in Hugo.

The MR implements a lot of the same logic we use on the Nanoc site:

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

  1. Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/technical-writing-group/gitlab-docs-hugo/-/blob/main/doc/setup.md.
  2. Run test builds described below. Verify that the site version shown in the gitlab-docs-version metatag (this is in the <head> of every page) matches the expected version.

🎩 If you're fancy you can check this quickly in your browser JS console with this line of JS: document.querySelector('meta[name="gitlab-docs-version"]').content

Build without any CI environment variables

  • Build command: make view
  • Expected version: 17.1 (via versions.json)

Build with a stable version branch

  • Build command: CI_COMMIT_REF_NAME="16.10" make view
  • Expected version: 16.10 (via CI_COMMIT_REF_NAME)

Build with some other branch that is not a stable version

  • Build command: CI_COMMIT_REF_NAME="100" make view
  • Expected version: 17.1 (via versions.json)

Build with no branch and an unreachable JSON

Change the URL on line 21 of themes/gitlab-docs/layouts/partials/functions/site-version.html to something invalid before running this one.

  • Build command: make view
  • Expected version: "" (empty)

Warning appears on build, but is not fatal.

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