Skip to content

Enable uglyUrls setting

What does this MR do and why?

Enables uglyUrls for the site. This change also requires additional adjustments:

  • Modify the navigation.yaml migration script to rewrite menu links accordingly. We are no longer dropping the .html suffix from links.
  • Adjust sidebar_menu.vue so that the active menu item logic handles both the Hugo-generated "real" URL (e.g, /user.html) and also the GitLab Pages-provided "extensionless URL" (e.g, /user/).

Ugly URLs? Why???

We have to use "ugly URLs" in order to not break links when we launch the new site. Nanoc generated most pages with a .html suffix, and we cannot provide a redirect for these using GitLab Pages due to how extensionless URLs are handled: https://docs.gitlab.com/ee/user/project/pages/introduction.html#resolving-ambiguous-urls (see also comments in #88 (closed)).

In the future, if we want to switch over to "pretty URLs," we will need some sort of reverse proxy in front of the site (e.g, Cloudflare) to handle redirects.

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. Follow the new steps in development.md to emulate an environment like GitLab Pages where extensionless URLs are supported.
  3. Click around the site, and verify that menu links still work, and the active menu trail is highlighted.

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

Loading