Resolve broken links from shortcodes
What does this MR do and why?
Hugo has a bug where some render hooks won't work as expected when called from shortcode content: https://github.com/gohugoio/hugo/issues/9692
For us, this means that many links inside alert boxes and version history notes are not transformed from their markdown link to a web/HTML link (because we use a render hook to do this), and so they 404.
So, to work around this, we need to not rely on markdownify
when we might need to rewrite links from shortcode content, and instead use $.Page.RenderString
(at least until https://github.com/gohugoio/hugo/issues/9692 is resolved).
While troubleshooting this, I found that we no longer need our own link render hook, and can instead now use a built-in one that was introduced in Hugo 0.123. Nice!
Closes #108 (closed)
Screenshots, screen recordings, or links to review app
A few examples of fixed links:
- Page: https://new.docs.gitlab.com/user/group/manage/
- Link text: links in the alert box at the top, like "Value stream analytics"
- Fixed version: http://localhost:1313/user/group/manage/
--
- Page: https://new.docs.gitlab.com/administration/settings/rate_limit_on_groups_api/
- Link text: "flag" in the History notes component
- Fixed version: http://localhost:1313/administration/settings/rate_limit_on_groups_api/
How to set up and validate locally
We can also validate this fix using Lychee, which we already have set up as a project dependency:
- On the
main
branch, run a new site compile:yarn run build && hugo
- Run Lychee on the compiled files, ignoring broken image links (that's a separate issue):
lychee --offline public | grep "\[ERR\]" | grep -vE "\.(png|jpg)"
- This returns 323 broken links
☹
- This returns 323 broken links
- Check out this branch (
108-index-links-rewrite
), and run a new compile:yarn run build && hugo
- Run Lychee again (
lychee --offline public | grep "\[ERR\]" | grep -vE "\.(png|jpg)"
), and output should look like this:
111364/111364 ━━━━━━━━━━━━━━━━━━━━ Finished extracting links ✗ [ERR] file:///Users/sarahg/dev/gdh/gitlab-docs-hugo/public/runner/install/linux-repository/gpg-keys/9CE45ABC880721D4.pub.gpg | Failed: Cannot find file
✗ [ERR] file:///Users/sarahg/dev/gdh/gitlab-docs-hugo/public/runner/install/linux-repository/gpg-keys/A674BF8135DFA027.pub.gpg | Failed: Cannot find file
✗ [ERR] file:///Users/sarahg/dev/gdh/gitlab-docs-hugo/public/omnibus/development/new-software-definition/examples/simple.rb | Failed: Cannot find file
These last few links are legitimately broken and are also broken on the Nanoc site. I've opened other MRs to fix those: gitlab-org/gitlab-runner!4936 (merged), gitlab-org/omnibus-gitlab!7853 (merged)
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.
-
I have evaluated the MR acceptance checklist for this merge request.