docs: update Gurubase widget to handle SPA navigation

[fatihbaltaci]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://voltagent.dev/docs/community/contributing/#commit-convention

Bugs / Features

• Related issue(s) linked
• Tests for the changes have been added
• Docs have been added / updated
• Changesets have been added https://voltagent.dev/docs/community/contributing/#creating-a-changeset

What is the current behavior?

The Gurubase widget only initializes on initial page load. When navigating within the Docusaurus SPA (Single Page Application):

• Navigating from home (/) or other pages to docs (/docs/...) does not show the widget
• Navigating away from docs pages does not remove the widget
• Browser back/forward navigation does not properly show/hide the widget

This happens because Docusaurus uses client-side routing, and the widget initialization only runs once on page load, not on route changes.

What is the new behavior?

The widget now properly handles SPA navigation:

• Widget appears when navigating to docs pages from any route (home, blog, etc.)
• Widget is removed when navigating away from docs pages
• Browser back/forward buttons correctly show/hide the widget

Implementation details:

• Added initWidget() and destroyWidget() functions with proper cleanup
• Hooked into History API (pushState, replaceState) to detect route changes
• Added popstate event listener for browser navigation
• Widget state tracking prevents duplicate initialization
• Comprehensive DOM cleanup removes all widget-related elements

fixes (issue)

Notes for reviewers

---

Summary by cubic

Make the Gurubase widget handle SPA navigation in Docusaurus so it appears on /docs pages and is removed elsewhere. Fixes missing widget after in-app navigation and stale widget when leaving docs, including back/forward.

• Bug Fixes
  • Detect route changes via history.pushState, history.replaceState, and popstate.
  • Add initWidget and destroyWidget with full cleanup (script, DOM, globals).
  • Track widget state to prevent duplicate initialization.

^{Written for commit fc4b5d1. Summary will update on new commits.}

[changeset-bot]

⚠️ No Changeset found

Latest commit: fc4b5d1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[cubic-dev-ai]

No issues found across 1 file

[omeraplak]

Thank you @fatihbaltaci