Skip to content

Make missing icons a warning and not a fatal error

What does this MR do and why?

Make the condition of an unknown icon a build warning, rather than a build error. We should do this for two reasons:

  • We often use perfectly valid icons in the docs, but Docker image might use a stale gitlab-docs which causes unnecessary pipeline errors. The only way to fix these errors is to republish fresh Docker images and make them available in pipelines.
  • We might use completely invalid references of icons (for example, edit instead of pencil). It's useful to be able to catch these on build, however the cost of failing to render this incorrect icons is very small (they render as a blank space) and they should be easily detectable no more than one month later, as part of monthly chores: https://gitlab.com/gitlab-org/technical-writing/-/blob/bd435ef2359e7f682cf460b66e0b34845fc570bd/.gitlab/issue_templates/tw-monthly-tasks.md#L12. Rather than just Kramdown warnings, we search for any warnings.

The implementation here marks the entire warning yellow, so it should be easy to spot!

For more context, see: !4702 (comment 1858486582).

Screenshots, screen recordings, or links to review app

  • Example build output:

    Screenshot_2024-04-15_at_4.21.47_PM

  • Example rendering of invalid icon:

    Screenshot_2024-04-15_at_4.31.51_PM

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/gitlab-docs/-/blob/main/doc/setup.md.
  2. Checkout out this branch.
  3. In a related gitlab checkout, change reference to an icon to something with an invalid name (not available from: https://gitlab-org.gitlab.io/gitlab-svgs/)
  4. Run make view, you should see a warning and not an error.

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 Evan Read

Merge request reports