docs: implement deep re-routing, pagination, and migration banner

[dishaprakash]

Description

1. Version Deep Re-routing

• Upgraded the version dropdown menu with deep-routing JavaScript.
• When a user switches versions, the script now dynamically strips the base URL and preserves their current page path, seamlessly dropping them onto the exact same page in the selected version (or displays 404 error is the same page doesn't exist in the destination version).

2. Pagination

• Pagination: Implemented pagination across the docs to improve navigation and readability for longer lists/sections.

3. Banner

• Migration Banner: Added a global migration banner to Github Pages docsite with a redirection URL

PR Checklist

Thank you for opening a Pull Request! Before submitting your PR, there are a
few things you can do to make sure it goes smoothly:

• Make sure you reviewed
  CONTRIBUTING.md
• Make sure to open an issue as a
  bug/issue
  before writing your code! That way we can discuss the change, evaluate
  designs, and agree on the general idea
• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)
• Make sure to add ! if this involve a breaking change

🛠️ Fixes #<issue_number_goes_here>

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the documentation site's user experience by introducing advanced navigation features and important user notifications. It implements a "deep re-routing" mechanism for version switching, allowing users to maintain their current page context across different documentation versions. Additionally, it integrates a comprehensive pagination system to improve content discoverability and readability for extensive sections. Finally, a prominent migration banner has been added to guide users from older, archived documentation to the most current version.

Highlights

• Version Deep Re-routing: Implemented JavaScript to preserve the current page path when switching documentation versions, ensuring users land on the exact same page in the selected version. Includes a fallback for dynamic releases file loading.
• Pagination: Introduced pagination across documentation pages to enhance navigation and readability, particularly for longer sections and lists.
• Migration Banner: Added a global, sticky migration banner for GitHub Pages deployments, alerting users to an archived version and directing them to the latest documentation.

Changelog

• .hugo/hugo.toml
  • Added configuration parameters for 'releases_url' and 'global_logo_url'.
• .hugo/layouts/docs/section.html
  • Created a new layout for documentation sections, incorporating a pager.
• .hugo/layouts/docs/single.html
  • Created a new layout for single documentation pages, incorporating a pager.
• .hugo/layouts/partials/hooks/body-end.html
  • Added JavaScript to dynamically set the 'href' attribute of the navbar brand logo.
• .hugo/layouts/partials/hooks/head-end.html
  • Updated the 'w3.js' script inclusion to use 'relURL' and conditionally included 'migration-banner.js'.
• .hugo/layouts/partials/navbar-version-selector.html
  • Refactored the version dropdown to include deep-routing JavaScript logic, allowing users to switch versions while staying on the same relative page path.
  • Updated the 'w3-include-html-default' fallback to use 'global_logo_url'.
• .hugo/layouts/partials/pager.html
  • Added a new partial template to calculate and render "Previous" and "Next" navigation links based on page hierarchy and weight.
• .hugo/static/js/migration-banner.js
  • Added a new JavaScript file to create and inject a sticky migration banner with dynamic styling and dark mode support.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces several significant improvements to the documentation site, including deep-routing for version switching, pagination, and a migration banner. The implementation is generally solid, but I've identified a few areas for improvement to enhance robustness and maintainability. My feedback focuses on using Hugo's relURL function consistently for asset paths, preventing a potential race condition in the version-switching JavaScript, and refining the migration banner script to remove redundant code and brittle logic.

[github-actions]

Link Resolution Note

Local links and directory changes work differently on GitHub than on the docsite. You must ensure fixes pass the GitHub check and also work with hugo server.
See Link Checking and Fixing with Lychee for more details.

Summary

Status	Count
🔍 Total	1030
✅ Successful	775
⏳ Timeouts	0
👻 Excluded	57
❓ Unknown	0
🚫 Errors	6
⛔ Unsupported	0

Errors per input

Errors in DEVELOPER.md

• [ERROR] https://play.dgraph.io/ | Network error: Connection failed. Check network connectivity and firewall settings (error sending request for url (https://play.dgraph.io/)): Connection failed. Check network connectivity and firewall settings

Errors in docs/en/integrations/alloydb-admin/alloydb-create-cluster.md

• [ERROR] https://console.cloud.google.com/apis/library/alloydb.googleapis.com | Network error: HTTP/2 protocol error. Server may not support HTTP/2 properly (error sending request for url (https://console.cloud.google.com/apis/library/alloydb.googleapis.com)): HTTP/2 protocol error. Server may not support HTTP/2 properly

Errors in docs/en/integrations/alloydb-admin/alloydb-create-instance.md

• [ERROR] https://console.cloud.google.com/apis/library/alloydb.googleapis.com | Error (cached)

Errors in docs/en/integrations/alloydb-admin/alloydb-create-user.md

• [ERROR] https://console.cloud.google.com/apis/library/alloydb.googleapis.com | Error (cached)

Errors in docs/en/user-guide/connect-to/client-sdks/javascript-sdk/core/index.md

• [404] https://langchain-ai.github.io/langgraphjs/reference/functions/langgraph_prebuilt.createReactAgent.html | Rejected status code: 404 Not Found (configurable with "accept" option)

Errors in docs/en/user-guide/connect-to/mcp-client/_index.md

• [404] https://docs.windsurf.com/windsurf/mcp | Rejected status code: 404 Not Found (configurable with "accept" option)

Full Github Actions output

[github-actions]

🔎 Preview at https://googleapis.github.io/genai-toolbox/previews/PR-2664/

[github-actions]

🔎 Preview at https://googleapis.github.io/genai-toolbox/previews/PR-2664/

[github-actions]

🔎 Preview at https://googleapis.github.io/genai-toolbox/previews/PR-2664/

[averikitsch]

Will this work with our new doc organization ie if I'm on https://googleapis.github.io/genai-toolbox/v0.29.0/integrations/clickhouse/ and click on an older version that doc path might not exist.

[averikitsch]

how is the pagination showing up in the docsite?

[dishaprakash]

Will this work with our new doc organization ie if I'm on https://googleapis.github.io/genai-toolbox/v0.29.0/integrations/clickhouse/ and click on an older version that doc path might not exist.

Yes, it will work on both docsites. If the link doesn't exist it shows a 404 error. If we want instead of error, we can redirect them to the root of that version.

how is the pagination showing up in the docsite?

This PR Preview contains the pagination - https://googleapis.github.io/genai-toolbox/previews/PR-2664/
You can find it at the bottom of all screens

[dishaprakash]

Will this work with our new doc organization ie if I'm on https://googleapis.github.io/genai-toolbox/v0.29.0/integrations/clickhouse/ and click on an older version that doc path might not exist.

@averikitsch I have added the fix for this. Now between if a user want to go to from https://googleapis.github.io/genai-toolbox/v0.29.0/integrations/clickhouse/ to v0.10.0 where it doesnt exist, instead of showing a 404 error, it directs it back to root of v0.10.0.

[github-actions]

🔎 Preview at https://googleapis.github.io/genai-toolbox/previews/PR-2664/

[github-actions]

🧨 Preview deployments removed.