Add functions for determining site version
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:
- Nanoc version: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/lib/helpers/versions.rb?ref_type=heads
- Nanoc version docs: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/versions.md?ref_type=heads)
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/technical-writing-group/gitlab-docs-hugo/-/blob/main/doc/setup.md. -
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.
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.
-
I have evaluated the MR acceptance checklist for this merge request.