Should <h4> tags get direct linkified?

[tannerdolby]

I see that the heading-highlight implementation stops after <h3>. I remember when this utility was implemented but I can't immediately think of a reason why we didn't choose to highlight past <h3>.

I bring this up because sometimes when including links in a blog post (or sharing them), we might be referencing the same page in a single paragraph or even in the same sentence. So if I'm providing a link to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#field_declarations for example and then want to show the private field declarations the only direct link I have is ..#field_declarations which doesn't take me directly to the desired subheading. This isn't a problem, but more a question. I can foresee it looking a bit wonky with so many links, but I want to be able to replace this (which uses the same subheading direct link as the <h4> tags are linkified):

I am writing about Field declarations in JavaScript and also Private field declarations but want the private field declarations to directly link to that subheading within field declarations.

with this (where the private field declarations link will directly link to that subheading /Classes#private_field_declarations rather than having to scroll down a bit from field declarations and providing two of the same subheading links with /Classes#field_declarations:

I am writing about Field declarations in JavaScript and also Private field declarations and both links are unique linking to the specified subheading.

As a developer its pretty easy to open devtools and grab the id and replace the last component of the URL with the desired ID (to create your own direct link) but this isn't always ideal.

What do you think about <h4> tags getting direct linkified? @peterbe

[peterbe]

What do you think about <h4> tags getting direct linkified?

It certainly would be nice! I've many times found that there's a specific portion of the page I'd like to link to but the nearest h2/h3 is so far away/up that the anchor link doesn't make much sense. I'd have to say "Go to the link Examples section and scroll down down to the section about polyfills".

But we'd have to be a bit careful. Perhaps h4s aren't as neatly used. It might be on the Tier 1 docs (i.e. popular en-US JS and CSS docs) but not on the long tail. Perhaps worth a shot and see how it feels and behaves. But we would need to browser a lot of samples to make sure it works OK.

For example, you can't have HTML within a h2 or h3 because the whole heading becomes a link. So if you had:

<h4 id="google-example">Google <a href="google.com/example">example</a></h4>

it will become:

<h4 id="google-example"><a href="#google-example">Google <a href="google.com/example">example</a></a></h4>

Also, I don't remember what does Yari do when there's a <h3> that doesn't have an ID? I think the kumascript rendering automatically generates on making <h3>Foo bar</h3> into <h3 id="foo-bar">Foo bar</h3>, first. But that'd need to be applied to all h4 too.

[tannerdolby]

But we'd have to be a bit careful. Perhaps h4s aren't as neatly used. It might be on the Tier 1 docs (i.e. popular en-US JS and CSS docs) but not on the long tail. Perhaps worth a shot and see how it feels and behaves. But we would need to browser a lot of samples to make sure it works OK.

Agreed, although this added functionality will be nice. We definitely need to browse many samples and test plenty of pages to make sure it works as we expect and without introducing any negative side effects.

Also, I don't remember what does Yari do when there's a <h3> that doesn't have an ID? I think the kumascript rendering automatically generates on making <h3>Foo bar</h3> into <h3 id="foo-bar">Foo bar</h3>, first. But that'd need to be applied to all h4 too.

I'm a bit foggy on how Yari handles a subheading without an ID, but I think your right the the KS rendering generates the id in kebab-case like <h3>Foo bar</h3> into <h3 id="foo-bar>..</h3> (have to check). But it seems the current ID casing is snake_case like <h3>Strict mode</h3> into <h3 id="strict_mode">..</h3> so maybe thats what the KS rendering should do too. Regardless, I do agree that the KS rendering from document-extractor.js would need to apply to all h4 tags so they get IDs generated if they don't initially have one. Then once the <h4> tags have IDs, we can make sure they get direct linkified and start browsing/testing some pages.

[escattone]

Re-opening, since #4388 was reverted.

[tannerdolby]

Yeah, it does seem that that PR broke some things. Its curious to me that the PR was a passing build without any obvious conflicting code and caused this much fuss. It did update all of the DisplayH2/H3 and (proposed) H4 logic for rendering heading elements. Looks like its back to the drawing board to figure out where the issue stemmed from.

[schalkneethling]

Yeah, it does seem that that PR broke some things. Its curious to me that the PR was a passing build without any obvious conflicting code and caused this much fuss. It did update all of the DisplayH2/H3 and (proposed) H4 logic for rendering heading elements. Looks like its back to the drawing board to figure out where the issue stemmed from.

I think this is because are still many, many permutations that exist across MDN and this is especially true of translated content. But yes, we should see what we need to do to ensure CI fails in future so we do not only pick this up in production 😱

[escattone]

@tannerdolby Thanks for all of your work on this! Can you find out why #4388 fails on some documents, and fix that? I would recommend running a full build of all of the content (English and translated) to see which docs the code fails on.

Then we can get #4388 re-opened, reviewed, and merged.

The real failure was in our production worklow, but that should be fixed now. See https://github.com/mdn/yari/issues/4570.

[tannerdolby]

@tannerdolby Thanks for all of your work on this! Can you find out why #4388 fails on some documents, and fix that? I would recommend running a full build of all of the content (English and translated) to see which docs the code fails on.

Your welcome! Yeah sure thing. I will try running a full build on all of the content like you suggested and see which docs are causing things to fail.

Ok excellent, sounds like a plan to me.

Ah I see, that makes more sense. After having a look at the changes in #4571, I better understand how this happened and that the underlying failure was within the production workflow.

[ghost]

I see that the heading-highlight implementation stops after <h3>. I remember when this utility was implemented but I can't immediately think of a reason why we didn't choose to highlight past <h3>.

I bring this up because sometimes when including links in a blog post (or sharing them), we might be referencing the same page in a single paragraph or even in the same sentence. So if I'm providing a link to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#field_declarations for example and then want to show the private field declarations the only direct link I have is ..#field_declarations which doesn't take me directly to the desired subheading. This isn't a problem, but more a question. I can foresee it looking a bit wonky with so many links, but I want to be able to replace this (which uses the same subheading direct link as the <h4> tags are linkified):

I am writing about Field declarations in JavaScript and also Private field declarations but want the private field declarations to directly link to that subheading within field declarations.

with this (where the private field declarations link will directly link to that subheading /Classes#private_field_declarations rather than having to scroll down a bit from field declarations and providing two of the same subheading links with /Classes#field_declarations:

I am writing about Field declarations in JavaScript and also Private field declarations and both links are unique linking to the specified subheading.

As a developer its pretty easy to open devtools and grab the id and replace the last component of the URL with the desired ID (to create your own direct link) but this isn't always ideal.

What do you think about <h4> tags getting direct linkified? @peterbe HJFDGTTJ4W3 2 aaw4ghjhjhjuwe432333336y978t44896+9a9+7+9a9a79a79a746464a-*-*a946a