Headers with links break TOC formatting and behave unintuitively
I noticed that when a header contains a link, some odd things happen in the TOC:
- The formatting is inconsistent (see screenshot below)
- When you click on the TOC element, it takes you to the link in the header, and not to that section on the current page
I noticed this when viewing What it’s like to work here at GitLab. In the TOC in the sidebar, part of the element is not link-formatted:
And when you click the TOC element, it takes you to the linked page So that’s what it’s like to work at GitLab… and not the actual section on the current page. I think this is unintuitive behavior, since I would never expect a TOC element to take me to a different page.
I'm not sure where this bug originates, (Hugo, us, etc.), so I'm not sure how to approach a fix.
As a workaround, we may be able to add a temporary linter item that checks for links-in-headers and discourages them (but doesn't block them), and cites this issue for more info.