Document local troubleshooting for the Hugo and Docsy upgrade

Why is this change being made?

Related rollout issue: Docsy and Hugo upgrade #51.

Local previews can fail after the Hugo 0.166.0 and Docsy 0.17.0 upgrade when developers still use an older Hugo executable or an outdated container environment. Add a dedicated troubleshooting page that connects recognizable terminal errors to recovery commands for each editing workflow.

The page starts with a #handbook Slack support tip and a dated Hugo requirement linked to the upgrade MRs in all three projects. An Upgrade Hugo or refresh the environment section groups the commands for local installations, Docker Compose, and Docker without Compose. Normal local commands remain make view and hugo version; mise exec is reserved for diagnosing executable selection. Docker guidance makes clear that Hugo and npm dependencies are handled inside the container.

The error sections cover incompatible Hugo versions, hugo.Data template failures, missing Hugo or incorrect PATH selection, missing Sass/npm dependencies, unexpected EOF, and static-file permission errors. They link back to the appropriate recovery workflow instead of repeating setup commands. The guide explains that preview commands refresh npm dependencies and generated output automatically, while container recreation does not repair ownership of files in the mounted checkout.

Move reusable troubleshooting guidance from Running locally while preserving its existing heading links. Keep mise shell activation in Running locally, and add a prominent 2026-09-14: Hugo 0.166.0 required note to the development overview.

Validation

• Markdownlint and Vale passed for the changed documentation; both were rerun on the final troubleshooting-page restructuring.
• git diff --check passed.
• Reproduced the incompatible-version warning and hugo.Data failure with Hugo 0.151.0 in a minimal site.
• Reproduced the missing Dart Sass error with Hugo 0.164.0 and no Sass executable on PATH.
• Hugo 0.155.0 compatibility is explained using the documented introduction of hugo.Data in 0.156.0; a full handbook build with 0.155.0 was not performed.
• Recovery commands were checked against the repository's Makefile, Compose configuration, and container entrypoint. A full local handbook build and every recovery workflow were not rerun for this documentation change.

Author and Reviewer Checklist

Please verify the check list and ensure to tick them off before the MR is merged.

• Provided a concise title for this Merge Request (MR)
• Added a description to this MR explaining the reasons for the proposed change, per say why, not just what
  • Copy/paste the Slack conversation to document it for later, or upload screenshots. Verify that no confidential data is added, and the content is SAFE
• Assign reviewers for this MR to the correct Directly Responsible Individual/s (DRI)
  • If the DRI for the page/s being updated isn’t immediately clear, then assign it to one of the people listed in the Maintained by section on the page being edited
  • If your manager does not have merge rights, please ask someone to merge it AFTER it has been approved by your manager in #mr-buddies
  • The when to get approval handbook section explains the workflow in more detail
• For transparency, share this MR with the audience that will be impacted.
  • Team: For changes that affect your direct team, share in your group Slack channel
  • Department: If the update affects your department, share the MR in your department Slack channel
  • Division: If the update affects your division, share the MR in your division Slack channel
  • Company: If the update affects all (or the majority of) GitLab team members, post an update in #whats-happening-at-gitlab linking to this MR
    • For high-priority company-wide announcements work with the internal communications team to post the update in #company-fyi and align on a plan to circulate in additional channels like the "While You Were Iterating" Newsletter

Commits

Document local handbook troubleshooting and Hugo upgrade requirement.

---