Add migration for alerts
What does this MR do and why?
Migrates alert boxes to shortcode format.
This covers these alert types: note
, warning
, flag
, disclaimer
. We are deprecating the info
alert type, and the details
alert type is a separate issue.
The disclaimer
alert has some special handling as we now populate that text from a template rather than having writers copy/paste it from the style guide.
See https://gitlab-org.gitlab.io/technical-writing-group/gitlab-docs-hugo/shortcodes/#alert-boxes for examples of the new format.
Closes #9 (closed).
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 and checkout this branch, migrate-alert-boxes
-
Pull down fresh docs, but don't run migrations yet: REMOVE_BEFORE_CLONE=true go run cmd/gldocs/main.go clone
(clone script is unchanged) -
Run just the alert migration against the GitLab docs: go run cmd/gldocs/main.go migrate alerts ../gitlab/doc
- You should see ~3 warnings about invalid disclaimer content.
-
Look at the diff. Alerts are now in the new format: git -C ../gitlab/doc diff
- Indention should be unchanged.
-
Pull down fresh docs again and run the end-to-end clone + migrate: REMOVE_BEFORE_CLONE=true make clone-docs-projects
-
Run make view
and visit a few pages with alert boxes, such as:
- Alerts should display similarly to how they do on the Nanoc site.
- Disclaimers flagged as invalid content are not transformed (e.g, http://localhost:1313/integration/arkose/).
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.
Edited by Sarah German