Restore scroll position when going back in the docs

[marknesh]

Summary

When you scroll down a docs page, click an in-site link, then hit Back, the page jumps to the top instead of where you left off.

Mintlify (almond theme) does not scroll the window. It scrolls an inner container (#content-container). The browser only restores window scroll, so it cannot put you back where you were.

This adds a small script that:

• Saves your scroll position for each page
• Restores it when you go back or forward
• Stops restoring if you start scrolling yourself

Mintlify loads .js files in the repo root on every page, so no docs.json change is needed.

Test plan

• Open a long docs page, scroll down, click an in-site link, then hit Back. You should return to the same scroll position.
• Repeat with Forward.
• Click an in-page heading (hash link). Back/forward should still work as expected.

[benitav]

Yeah, I've at least once been annoyed by this behavior too. I'm seeing now that Mintlify's docs site does jump back to the section you were in, and by you pointing out the Almond theme specifically, I'm assuming a different theme might come with this feature built-in? If a different theme doesn't come with other quirks and solves this I think we'd rather switch to it than add a workaround like this.

[marknesh]

Hi @benitav, I have been testing the aspen theme (kind of similar to almond 👀) and the scroll restoration works well, but I think there is a bug in the mintlify themes whereby a hash navigation still breaks the back navigation.

Here is the repro of the bug with the theme set to aspen:

1. Open a docs page
2. Click a heading so the URL gets a hash (/page#section)
3. Navigate to another page
4. Press Back

Expected: return to the previous page, at that heading.
Actual: Back does not return to the hashed page. It stays on the current page and just scrolls down.

The most likely cause is when you click a heading, mintlify is calling history.replaceState to set the fragment, but drops Next.js App Router state (history.state.__NA). That history entry is then invalid, so back is not treated as a route change. Maybe we write a custom script to solve this issue?

mintlify-bug.mp4

[benitav]

Thanks for that - bummer. I reached out to Mintlify to hear if they could fix it at the theme level. Ideally we don't have to deploy this kind of workaround. Will keep you posted.