Fix anchor offset overlap blocking UI interactions

[alikhere]

Description:
The Docsy theme uses invisible :before pseudo-elements on headings (h2[id], h3[id], etc.) to create anchor offsets that prevent headings from being hidden behind the fixed navigation bar. However, these invisible elements create "dead zones" that block interactions with elements above them, such as:

• Scrollbars in code blocks positioned above headings
• Other interactive UI elements near headings

Solution:
Replace the legacy :before pseudo-element approach with modern CSS scroll-margin-top property, which achieves the same anchor offset functionality without blocking user interactions.
Changes Made:

• Added CSS override in assets/scss/_custom.scss
• Disabled problematic :before pseudo-elements using display: none !important
• Implemented scroll-margin-top: 5rem on headings for proper anchor offset

Fixes: #51923
For more reference see #32695 #744

Screenshot

Before

After

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign natalisucks for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	2e43471
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/68a27356ce9f6c0009cc0438
😎 Deploy Preview	https://deploy-preview-51954--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[shurup]

Thanks for this improvement, @alikhere!

Actually, I can't reproduce that existing CSS rules block interactions with elements above headings' scrollbars. E.g., I can easily scroll the kubectl create secret docker-registry NAME code block on the abovementioned page in two browsers (Chrome and Firefox). However, anyway, I fully agree that scroll-margin-top brings a much more elegant solution (compared to the existing hX[id]:before hack).

The only thing that I want to clarify is: why do we need the display: none hack for existing hX[id]:before blocks? Wouldn't it be better to get rid of these :before rules instead?

[alikhere]

@shurup
I initially tried just adding:

@media (min-width: 768px) {
 h2[id],
 h3[id],
 h4[id],
 h5[id] {
   scroll-margin-top: 5rem;
 }
}

However, the ::before pseudo-elements still persist because they're defined in the compiled Docsy theme CSS (main.min.[hash].css), which we can't modify/ delete directly as it comes from the Docsy submodule.
see below:

Since we can’t delete those rules at the source, we need to override them to:

• Disable the old ::before behavior (to prevent double-offsets or invisible overlaps).
• Apply scroll-margin-top as the modern replacement.

Without display: none, the ::before elements still exist in the DOM and could interfere with layout or interactions. This override ensures a smooth transition to the new method.

You can see the difference how h2 of "synopsis" of overlapping with h1 of "kubectl create secret docker-registry" before.

before

after made changes

[shurup]

Thanks a lot for this detailed clarification! Now it totally makes sense to me, and I'm happy with the solution provided.

/lgtm

P.S. What do you think about suggesting this fix to Docsy itself? As far as I can see, here's the place in the upstream project we want to improve.

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: f88c7793f0a91c8a0681999d4e1f7b076eec78de

[alikhere]

Thanks a lot for this detailed clarification! Now it totally makes sense to me, and I'm happy with the solution provided.

/lgtm

P.S. What do you think about suggesting this fix to Docsy itself? As far as I can see, here's the place in the upstream project we want to improve.

Thank you for the approval! I completely agree - fixing this at the source in the Docsy upstream project is the ideal long-term solution. This would benefit all projects using Docsy (not just Kubernetes),
The changes should be something like below here to fix the issue.

 // Replace the old ::before hack with modern scroll-margin
-    h2[id]:before,
-    h3[id]:before,
-    h4[id]:before,
-    h5[id]:before {
-        display: block;
-        content: " ";
-        margin-top: -5rem;
-        height: 5rem;
-        visibility: hidden;
+  h2[id],
+  h3[id],
+  h4[id],
+  h5[id] {
+   scroll-margin-top: 5rem;

Once that upstream change is merged and released, later we could eventually remove our override in Kubernetes

[milinddethe15]

lgtm
/cc @divya-mohan0209

[SayakMukhopadhyay]

Not adding an explicit hold in here, but we might want to wait a bit on this PR, as the linked issue is not reproducible by me. See #51923 (comment)

@shurup are you able to reproduce this?

[shurup]

@shurup are you able to reproduce this?

While I wasn't able to reproduce it in terms of non-working scrolling (in Linux), I could see the actual overlap. After checking what scroll-margin-top does, I was in favour of this change anyway, since it makes things "right."

[alikhere]

@SayakMukhopadhyay

The scrolling functionality also works on my side too- that's not the issue. The problem is the visual overlap and invisible blocking elements created by the ::before pseudo-elements.

As you can see in the screenshots, the ::before elements create a 5rem invisible block above each heading that:

• Visually overlaps with content above (confirmed by both maintainers)
• Creates invisible "dead zones" that can interfere with precise interactions
• Uses outdated CSS techniques when scroll-margin-top is the modern standard

The scroll-margin-top approach eliminates these unnecessary invisible blocks while providing the same anchor offset functionality.
This is a code quality and layout cleanliness improvement, not just a functional bug fix.

Either way, I'm fine with whatever decision you all reviewer make. Just wanted to modernize the CSS approach.

[SayakMukhopadhyay]

The scrolling functionality also works on my side too- that's not the issue.

Yeah, that's what I was checking in macOS, and there doesn't seem to be an issue functionality-wise.

The reason why I am a bit hesitant on this PR is cause right now we are working towards making the site as close to Docsyy as possible (see #41171), and while this PR makes the stylesheet better, it will be one more thing to keep in mind while working on the Docsy upgrade.

[divya-mohan0209]

@alikhere Thanks for the changes proposed through this PR.

Sayak - Reg. your comment, when aligning it with the Docsy upgrade work, would it be prudent to track it all over an issue and perhaps add this as a note? Would that help with the reminder bit since this does introduce a style improvement?

[SayakMukhopadhyay]

would it be prudent to track it all over an issue and perhaps add this as a note? Would that help with the reminder bit since this does introduce a style improvement?

We do have a tracking issue #41171 for the upgrade work.

My primary concern is that this PR isn't fixing anything that's broken right now. Don't get me wrong, the change in this PR is technically the correct thing to do, but this change might get reverted in the next bump to Docsy 0.7.0, as that version too won't have the current best practices. I haven't checked, but I believe that Docsy itself doesn't incorporate this change until the latest 2-3 releases or such.

My suggestion would be to keep this PR open as things to track when we are almost up to date on Docsy. But I am flexible on that opinion and won't mind if it gets merged either, it will be just another item for me to keep in mind 😅.