Make impl section headers sticky

[GuillaumeGomez]

View all comments

Fixes #133506.

It makes impl sections headings sticky, allowing users to know what impl items they are currently going through.

You can test it here.

Some technical details: to make it work (because summary use both ::before and ::after pseudo-elements), I needed to give some left margin and padding so that the other collapse/expand toggles of children items would not appear on the sticky heading's toggle. Hence why the GUI tests new values look so weird.

r? @notriddle

[rustbot]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @jsha

[GuillaumeGomez]

Forgot to push the second commit updating GUI tests...

[joshtriplett]

I love it! https://rustdoc.crud.net/imperio/sticky-headings/std/primitive.slice.html looks great.

I can confirm that it works as expected in Firefox on both desktop and mobile.

[notriddle]

It's messed up when the sidebar is hidden. Otherwise, seems fine.

[GuillaumeGomez]

Kinda fixed the mess up with the sidebar button. Not perfect but sadly, we can't set an element position based on the page scroll without JS, and with JS, having a listener on the page scroll is terrible for performance. So instead, I simply make the button above the heading. It'll prevent to collapse the heading if the button is present, but I think it's ok.

[GuillaumeGomez]

@rfcbot fcp merge

[rfcbot]

@GuillaumeGomez has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @camelid
• @jsha
• @notriddle

Concerns:

• mobile hidden persistent navigation bar (Make impl section headers sticky #133717 (comment))
• scroll after collapse (Make impl section headers sticky #133717 (comment))
• scroll-margin-top (Make impl section headers sticky #133717 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[notriddle]

The trouble with this sort of thing is that it's really hard to get all the interaction features right. Here's a few cases that act weird:

• If I click an item in the sidebar, it gets lost underneath the impl header.

  

  Normally, the solution to this one is scroll-margin-top, as in rustdoc mobile: fix scroll offset when jumping to internal id #93067, but, unfortunately, we don't know how tall the impl header is:

  

• If I collapse an impl block while I'm scrolled some distance into it, I wind up at some arbitrary point in the document. I don't know how to fix this one without JS.

  

• Hidden navigation bar is still a mess on mobile:

  

[notriddle]

@rfcbot concern scroll-margin-top

@rfcbot concern scroll after collapse

@rfcbot concern mobile hidden persistent navigation bar

[Manishearth]

(In favor of this general design, but echo notriddle's concern that this is really tricky to get right, so we should spend some time experimenting and ensuring it works in all scenarios)

[bors]

☔ The latest upstream changes (presumably #136292) made this pull request unmergeable. Please resolve the merge conflicts.

[kpreid]

I'm interested in seeing this happen to make impls more comprehensible, but I would like to recommend that this sticky header should be optional. I know that optional UI features are a cost in themselves, but I have two specific reasons that unconditional stickiness could be problematic:

• If the sticky header is tall enough, relative to the viewport (yes, I do use rustdoc on my phone) then there may not be enough remaining space to comfortably read the documentation text.
  • And how much space that is will depend not just on the viewport size but also the content and style of the documentation itself — how tall the function signatures, body text, code examples, etc. are, and how much context is needed from one part to understand another. So, a size threshold would not completely solve the problem.
• Some people find sticky headers and other content-overlapping fixed elements inherently distressing to view (I have a little bit of this myself) — it's something about losing the consistency that the entire content scrolls as a single unit within a well-defined boundary, combined with the shrinking of the effective usable viewport. Being able to avoid sticky headers should be considered an accessibility feature.

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[GuillaumeGomez]

I took a slightly different approach. You can give it a try here. It works mostly nicely without JS although it's a very big improvement for anchor jumping.

What do you think of this new version?

[rust-log-analyzer]

The job test-tidy failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

linting javascript files
Running eslint on rustdoc JS files

/checkout/src/librustdoc/html/static/js/main.js
  2260:21  error  'onEach' is not defined  no-undef
  2264:21  error  'onEach' is not defined  no-undef
  2271:21  error  'onEach' is not defined  no-undef
  2284:82  error  Missing trailing comma   comma-dangle

✖ 4 problems (4 errors, 0 warnings)
  1 error and 0 warnings potentially fixable with the `--fix` option.

rerun with `--bless` to apply esplint suggestion: `./x.py test tidy --extra-checks=js:lint --bless`
tidy [extra_checks:js_lint]: checks with external tool 'eslint' failed
tidy [extra_checks:js_lint]: FAIL
typechecking javascript files
../src/librustdoc/html/static/js/main.js(2261,25): error TS2345: Argument of type 'HTMLCollectionOf<Element>' is not assignable to parameter of type 'any[]'.
  Type 'HTMLCollectionOf<Element>' is missing the following properties from type 'any[]': pop, push, concat, join, and 33 more.
../src/librustdoc/html/static/js/main.js(2265,25): error TS2345: Argument of type 'HTMLCollectionOf<Element>' is not assignable to parameter of type 'any[]'.
  Type 'HTMLCollectionOf<Element>' is missing the following properties from type 'any[]': pop, push, concat, join, and 33 more.
../src/librustdoc/html/static/js/main.js(2272,25): error TS2345: Argument of type 'NodeListOf<Element>' is not assignable to parameter of type 'any[]'.
  Type 'NodeListOf<Element>' is missing the following properties from type 'any[]': pop, push, concat, join, and 29 more.
tidy [extra_checks:js_typecheck]: checks with external tool 'tsc' failed
tidy [extra_checks:js_typecheck]: FAIL
tidy: The following checks failed: extra_checks:js_lint, extra_checks:js_typecheck
Bootstrap failed while executing `test src/tools/tidy tidyselftest --extra-checks=py,cpp,js,spellcheck`
Currently active steps:
test::Tidy {  } at src/bootstrap/src/core/build_steps/test.rs:1665
Command `/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-tools-bin/rust-tidy --root-path=/checkout --cargo-path=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo --output-dir=/checkout/obj/build --concurrency=4 --npm-path=/node/bin/yarn --ci=true --extra-checks=py,cpp,js,spellcheck` failed with exit code 1
Created at: src/bootstrap/src/core/build_steps/tool.rs:1627:23
Executed at: src/bootstrap/src/core/build_steps/test.rs:1747:29

Command has failed. Rerun with -v to see more details.
Build completed unsuccessfully in 0:02:21
  local time: Wed Oct  7 18:51:20 UTC 2026
  network time: Wed, 07 Oct 2026 18:51:20 GMT
##[error]Process completed with exit code 1.
##[group]Run echo "disk usage:"