Skip to content

Prevent invalid links from throwing errors on build

Sarah German requested to merge borked-links-no-crash-plz into main

What does this MR do and why?

After we introduced !13 (merged), malformed links cause the build to fail with a fatal error like this:

Error: error building site: "/builds/gitlab-org/technical-writing-group/charts-gitlab/doc/charts/registry/metadata_database.md:1:1": "/builds/gitlab-org/technical-writing-group/gitlab-docs-hugo/themes/gitlab-docs/layouts/_default/_markup/render-link.html:5:15": execute of template failed: template: _default/_markup/render-link.html:5:15: executing "_default/_markup/render-link.html" at <urls.Parse>: error calling Parse: parse "(https://gitlab.com/gitlab-org/charts/gitlab/-/issues/5293)": first path segment in URL cannot contain colon

Another one: gitlab-org/gitlab!141666 (merged)

To avoid this, we need to check if relative URLs are valid before trying to rewrite them.

Screenshots, screen recordings, or links to review app

before after
image image

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. On the main branch: Add a malformed link to a page (see examples above), and run a build: hugo.
    • Hugo will crash with an error like this: execute of template failed: template: _default/_markup/render-link.html:5:15...
  3. Check out this branch: git fetch origin borked-links-no-crash-plz && git checkout borked-links-no-crash-plz
  4. Try the build again: hugo
  5. Build should complete without errors

We should also validate that the intended change from !13 (merged) still works:

  • Links between pages should not point to the original page.md URL, but rather its Hugo-processed page, page.html
    • Note: links that end in index.md do not work yet, see #62 (closed)

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