1479817 - Anchor links on MDN scroll the page too far down to see linked `h3` section headers

Status: RESOLVED FIXED

(developer.mozilla.org Graveyard :: Design, enhancement, P1)

Description

[Rory O’Kane]

What did you do?
================
Short version: visit the link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach#Using_thisArg

Long version:

1. In Firefox 61, visit a page with some content I want to share, such as https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach

2. Find an <h3> (not an <h2>) section with the content I want to share, for example the “Using `thisArg`” section within the Examples section.

3. Use Firefox’s Inspector to select the <h3> and find its `id`. Double-click the `id` attribute to select its contents and then copy its value, “Using_thisArg”.

4. Edit the location bar by adding '#' and that ID to generate a link to that section. The link generated in this example: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach#Using_thisArg

5. Visit that link.

What happened?
==============
The page scrolls so that at the top of the page I see the floating “Jump to:” toolbar, and underneath that I see the first paragraph *within* the linked section.

> The following (contrived) example updates an object's properties from each entry in the array:

What should have happened?
==========================
The page should scroll far up enough that the floating “Jump to:” toolbar does not block the section header.

That is, the page should scroll so that at the top of the page I see the floating “Jump to:” toolbar, and underneath that I see the header for the linked section, “Using `thisArg`”. Then underneath that I would still see the rest of the content in that section.

Is there anything else we should know?
======================================
The Stack Overflow question [Fixed page header overlaps in-page anchors](https://stackoverflow.com/questions/4086107/fixed-page-header-overlaps-in-page-anchors) explains how to fix this bug. Copying this CSS from that page seems to work:

~~~css
:target:before {
  content: "";
  display: block;
  height: 60px; /* fixed header height*/
  margin: -60px 0 0; /* negative fixed header height */
}
~~~

Considerations when adding this CSS to MDN:

- The `toc` sticky header on MDN is 47px tall, so the above value of `60px` leaves 13px of margin above the header, which looks about right. You might have a more principled way of choosing the value. If you preprocess your CSS, you should probably calculate the value based on a variable representing the height of the sticky header.

- This rule will need to be put in the same media query that controls whether the `toc` header has `position: sticky`, so that the padding is only applied when necessary.

- Different variations of that rule may have to be used for `h2` and `h3` elements, since `h2` elements already have a `:before` pseudo-element whose styles may be changed by the above. `h4` and other elements may need unique margin values too.

Comment 1

[Rory O’Kane]

I just noticed that the header is not always 47px tall. If the window is narrow enough, the links in it can wrap to another line, making the header 94px tall. Ideally, the above CSS rule should make the added padding match the sticky header’s height.

I don’t think CSS can detect whether the header’s height changed, so you probably need to use a JavaScript solution based on the one in that Stack Overflow question (https://stackoverflow.com/a/28824157/578288). When the page is loaded or when the URL changes with a fragment in the URL, first read the height of the fixed header, then scroll the page up by that amount.

If you follow the principles of graceful degradation you might still add the CSS styles in addition to a JavaScript solution.

Comment 2

[Rory O’Kane]

Attachment: current scroll position after following link to "Using thisArg" section

Comment 3

[Rory O’Kane]

Attachment: desired scroll position after following link to "Using thisArg" section

Comment 4

[[github robot]]

Commit pushed to master at https://github.com/mozilla/kuma

https://github.com/mozilla/kuma/commit/8ade76fa90923ad212fed3dc0e6d55a86d58e0b7
bug 1479817, anchor link headings are obscured by toc (#4954)

* bug 1479817, anchor link headings are obscured by toc
* Fix remaining bugs

Comment 5

[John Whitlock [:jwhitlock]]

Fix deployed a month ago, working in production