fix: disable navigation.instant (unstyled pages on in-site navigation)#2704
Conversation
…igation navigation.instant swaps <body> via XHR instead of doing a full page load, so the theme's custom scripts and third-party embeds (docs-theme.js, CookieYes, Zendesk) that initialize on DOMContentLoaded never re-run on navigation, leaving navigated pages unstyled until a manual refresh. Reverting to full page loads until the customizations are made instant-safe (re-init on Material's document$ observable). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request removes the "navigation.instant" feature from the MkDocs theme configuration in mkdocs.yml. I have no feedback to provide as there are no review comments.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Up to standards ✅🟢 Issues
|
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull Request Overview
This pull request addresses the issue of unstyled pages during internal navigation by disabling the navigation.instant feature in mkdocs.yml. This ensures that JavaScript and third-party embeds are properly re-initialized on each page load.
The changes are up to standards according to Codacy, and the implementation aligns perfectly with the stated intent and acceptance criteria. No security or logic flaws were identified.
Test suggestions
- Verify mkdocs.yml no longer contains the 'navigation.instant' feature
- Confirm 'navigation.path' remains in the features list
TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback
2 participants
Problem
After the theme change, pages render unstyled when navigating between links — first full page load is fine, clicking to another page (e.g. Getting Started) breaks the layout, and a manual refresh fixes it. Reproduced in Safari and matches reports of "a refresh does the trick, but it happens on every first-visit link and on back-navigation."
Cause
Production has
navigation.instantenabled (confirmed in the live__configblock). With instant loading, in-site clicks fetch the target page over XHR and swap only the<body>— no full document load. The theme's custom scripts and third-party embeds (docs-theme.js, CookieYes, Zendesk) initialize onDOMContentLoaded, which only fires on a real page load, so they never re-run on the swapped-in content → unstyled pages. A refresh is a full load, which re-runs everything, which is why it "fixes" it.Fix
Remove
navigation.instantfromtheme.featuresso navigation goes back to full page loads.navigation.path(breadcrumbs) is kept — it's independent of instant loading and isn't involved in the breakage.This restores correct rendering immediately. Keeping instant loading would instead require re-initializing the custom scripts and embeds on Material's
document$observable (which re-fires per instant navigation) — a larger, riskier change that can be tackled separately if the page-load speedup is wanted back.🤖 Generated with Claude Code