Skip to content

Add shortcode for alert boxes

Sarah German requested to merge 9-alert-boxes into main

What does this MR do and why?

This MR ports Alert boxes to the Hugo site.

This MR also adds a new content page (shortcodes.md). We'll use this page as a reference during development of the Hugo site as we add shortcodes and compare them to their counterparts in our existing style guide. Ideally what we document as we go will be useful for when we eventually update the real style guide as part of launching the new site.

This intentionally does not include the "Details" alert type. That comes later in #11 (closed).

TBD on if we'll keep the "Info" type: #9 (comment 1823229443)

Part 1 of 2 to close #9 (closed).

How to set up and validate locally

⚠ You should clone this project to a separate directory from your regular GitLab projects, as it will overwrite docs content files in the gitlab, gitlab-runner, etc directories at the same level.

  1. Configure a local GitLab Docs Hugo environment and start the preview server: https://gitlab.com/gitlab-org/technical-writing-group/gitlab-docs-hugo/-/blob/main/doc/setup.md.
  2. Review the Shortcode reference page: http://localhost:1313/shortcodes/.
  3. Edit or add a regular page, and try creating a few alert boxes or modifying existing ones.

For example, on this page:

Old format:

NOTE:
A [Critical Security release](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) will reset runner registration tokens for your group and projects. If you use an automated process (scripts that encode the value of the registration token) to register runners, this update will break that process. However, it should have no affect on previously registered runners.

New format:

{{< alert type="note" >}}
A [Critical Security release](https://about.gitlab.com/releases/2022/02/25/critical-security-release-gitlab-14-8-2-released/) will reset runner registration tokens for your group and projects. If you use an automated process (scripts that encode the value of the registration token) to register runners, this update will break that process. However, it should have no affect on previously registered runners.
{{< /alert >}}

If you're running make view from the project directory to run the preview server, you can see this page here: http://localhost:1313/runner/faq/

Things to look for:

  • Do the alert boxes display properly and have the same styling as the current site?
  • Do we have all the right alert options? Do we want to add any new ones or modify what we have?
  • Is the shortcode syntax acceptable? The {{< whatever >}} style syntax with the brackets is required for Hugo, but we can name the shortcode (alert) or its parameters (type, in this case) however we think makes the most sense.
    • We want to be consistent in naming and syntax as we add any custom elements for authors to use. In Nanoc, our custom elements really varied in syntax (e.g, the way you add SVGs vs alert boxes), and I think we can improve that experience this time around. But also it will be easier on everyone to not go too wild with renaming things.
  • Do you get an actionable, clear error from the build if you do something wrong? (e.g, forget the type property)

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