Thoughts on adding direct-links to heading tags within article content?

@tannerdolby commented on Wed Oct 07 2020

URL(s)

Content Categories - MDN

Request type

• Correction or update

Details

Hello, MDN team. I’m not so sure this is an issue or problem but something I wanted to ask your team about.

I originally noticed it on this page Content Categories - MDN but I think it applies to all pages within /docs/Web/. I wanted to click on the section heading, Palpable content to get a direct link to this section without having to scroll down from Content Categories. I inspected the page and copied the corresponding id selector #Palpable_content and pasted it to the end of the page URL to provide a “direct-link” to that sections content.

I do recognize the “On this page” section containing direct links to main headings of the page in that unordered list which is very helpful. But for sections with more content that require the user to scroll further down the page, this is where I think potentially having direct links on some of the subheadings in long categories could be useful for people sharing links to specific sections within MDN docs.

Proposed update:

1. Create direct links for section headings that are further down from the “On this page” direct links. Allowing for a direct link to that section heading to be produced in the browsers address bar upon clicking the .direct-link element nested in the heading for fast internal linking. I used the hashtag character as the anchors value (which could also be an SVG if there is a specific icon wanting to be used) within the direct link screen shot I attached below.

The .direct-link anchor elements could be fully visible or visually hidden from the screen with good ole visibility: hidden or potentially a fancier way of visually hiding using absolute positioning and translate.

The .direct-link element could then become visible upon hovering the heading element and allow for a quick click to update the page URL with a direct link to that specific section heading.

<h3 id="Palpable_content">Palpable content <a class="direct-link" href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#Palpable_content">#</a></h3>

Screenshot with direct link visible for Palpable content heading: (no styling or margins currently applied)

Let me know your thoughts!

---

@chrisdavidmills commented on Wed Oct 07 2020

Hi @tannerdolby !

Yes, I agree this would be nice, and in fact we did have this at some point, but I think it was disabled in the “viewer” front-end because of some kind of performance reason. If you look at the “wiki”/“edit” version of the page (https://wiki.developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories), you’ll see the feature active there.

I think it’d be good for us to have this feature sorted out again at some point soon in the final UI, therefore I’m going to move your issue over to the platform (kuma) repo so I can add your voice to the discussion. Thanks for speaking up.

[peterbe]

Before I forget, one realistic input is:

<h3>123 IDs can't start with numbers</h3>

This can’t become

<h3 id="123_ids_cant_start_with_numbers"><a href="123_ids_cant_start_with_numbers">123 IDs can't start with numbers</a></h3>

Perhaps the simplest solution is to inject a _ if the first character of the generated ID starts with a character that isn’t [a-z]. E.g.

<h3 id="_123_ids_cant_start_with_numbers"><a href="_123_ids_cant_start_with_numbers">123 IDs can't start with numbers</a></h3>

See if you can research up the current rules about what a valid ID has to be for a DOM.

[peterbe]

I haven’t carefully read your comment yet. But I skimmed it and something that stood out is that it might that the sample input HTML is not realistic. If the input HTML is:

<h3 id="metadata_content">Some other example</h3>
<h3 id="metadata_content">Some cool text</h3>
<h3 id="metadata_content">Some blue text</h3>

I think nothing should be done. Yes, it’s nuts that the same id value is repeated and that’s something we need to deal with, but it’s a story for another day. We have a system called “flaws” which deals with finding things like that.

A more realistic input would be:

<h3>Some other example</h3>
<h3>Same text</h3>
<h3 id="blabla">I already have an ID</h3>
<h3>Same text</h3>

With an input like that, your output should something like:

<h3 id="some_other_example"><a href="#some_other_example">Some other example</a></h3>
<h3  id="same_text"><a href="#same_text">Same text</a></h3>
<h3 id="blabla"><a href="#blabla">I already have an ID</a></h3>
<h3 id="same_text_2"><a href="#same_text_2">Same text</a></h3>

I.e. If the h3 has an id already, keep it. Don’t touch it. If the h3 texts are repeated, increment the normalized ID.

Stay away from the name attribute entirely. Pretend it doesn’t exist. As Ryan pointed out, it’s a relic of the past but it was ultimately just there to help set the id.

Does that simplify the task a bit?