[8.x] Improve linkability of docs by adding named anchors to h4 tags #6506
Conversation
A selection of h4 tags already had anchor tags so this is really just filling in the gaps (of which there is many!) This makes it much easier to share a specific subsection of the docs in blog posts, PRs, chat, etc.
|
I have wanted this sooooooo many times. Thank you 🙌 |
| <a name="fluent-strings"></a> | ||
| <a name="fluent-strings-method-list"></a> |
There was a problem hiding this comment.
Are we worried that this will break existing links to this header in existing blog posts and what not
There was a problem hiding this comment.
This was an existing duplicate anchor name, so it will have already been broken to some extent, depending on which of the two "Fluent Strings" headings they were attempting to link to.
One was a h2 and one was a h3, so I changed the h3, because the h2 outranked it 🤣. However, this h3 comes first in the document, and it seems like that one "wins" when there are duplicates on the page, at least with Firefox. So I may have been better off changing the h2, although to what I'm not sure.
The TOC on this page is also missing a lot of the h3 links and could probably do with a bit of attention.
|
Nice work! |
|
To be honest, I wonder if these are manually maintained. It makes more sense to leave it to the converter that converts markdown to HTML, or generate them on load with JavaScript. |
Some h4 tags already had named anchors, but the majority didn't. This made it hard to link to specific subsections of the documentation in blog posts, peer reviews, chats, etc. I have often found myself linking to a h3 tag and then telling the recipient to "scroll until you reach X". This PR aims to fix that by:
This PR does not change the TOC or visual appearance. The only UX change is that the h4 tags are now focusable and have a pointer cursor as they are links, but they do not have the red "#" that the other headings have (I can PR this to the website repo if that is a welcome addition though).
I have also only done this for the 8.x branch.
The process
I mostly automated this by writing a script that searched for lines beginning with
####that weren't already preceded by a named anchor, and then automatically prepended a named anchor with a slugified version of the heading text. ThanksStr::slug()!This created a few duplicate anchor names within the same page, so I wrote another script to find any duplicates within the same file so that I could manually add some extra context to uniquely distinguish them. In doing so I found one preexisting duplicate that I also fixed.
It's not a perfect process, but given there ended up being 674 new anchors, it was too much to do by hand. I have had a quick glance over every added anchor and they all seem good to me.