Website Widget - Gurubase

You’re already seeing the widget in action! Click the “Ask AI” button on this page to try it out.

You can add your Guru directly to your website using our widget. The widget adds an “Ask AI” button that opens a chat interface when clicked.

Prerequisites

Before adding the widget, make sure you have:

A Guru on Gurubase (either on Gurubase Cloud or self-hosted with Enterprise plan)
A Widget ID from your Guru’s settings

Go to Gurubase platform
Click the Guru you want to add the widget to
Click “Integrations” and then “Web Widget”
Click “New Widget ID”, enter your website’s domain and click “Generate”
The widget settings open. Adjust them, click Save, then copy the Widget ID or the script from the Install section

The copy icon next to each Widget ID on the Web Widget page copies the ID without opening its settings. Each Widget ID is restricted to work only on the specific domain it was created for. For example:

A Widget ID created for https://www.example.com will only work on that exact domain.
- It won’t work on subdomains like https://docs.example.com
- It won’t work on different domains like https://example.org
For local development, you need to create a separate Widget ID using your development URL (e.g., http://localhost:3000)
Domain input supports wildcard (*) expression:
- *.example.com will match any subdomain of example.com
- http://localhost:* will match any port of localhost
- * will match any domain, so be careful with this option! Anyone who knows your Widget ID can send requests to your Guru.

Make sure to create Widget IDs for each domain where you want to use the widget. The domain can be changed later in the widget’s settings, for example to narrow a * widget to your production domain, and the Widget ID keeps working. Click Settings next to a Widget ID to open its settings. Everything here is saved on the Widget ID itself, so a change applies to every page that embeds it as soon as you click Save, with no change to the page or redeploy. This is what lets platforms that cannot edit script attributes use the full set of options; on SharePoint this needs package 1.7.0 or later.

Edits are a draft until you click Save. The Preview on the right already shows the draft, and you can open the widget there and try it. Discard returns to the saved settings, and closing the panel with unsaved changes asks before throwing them away. An empty field means “not set”. The grey text inside it is what the widget will show in that case, in the selected language. A setting is resolved in this order:

The value saved on the Widget ID
The matching data-* attribute on the page’s script tag, if any (see Configuration Options)
The default shown in grey

Click Default next to a field to clear it.

Section	Settings
Access	Domain, Attachments (let visitors attach images, logs and PDFs), Require signed-in Zendesk users
Language and name	Language (English or Turkish), Display name (replaces the Guru name in every default text)
Launcher button	Button text, Color, Tooltip and its position, Distance from bottom and right
Chat window	Opens as (Sidebar or Floating), Theme (Auto, Light, Dark), Logo URL, Header, Assistant name, Welcome heading, Input placeholder, Welcome message, Highlight color, Show sources, Show trust score, Show “Powered by Gurubase” (self-hosted only)

Supported attachment file formats

Category	Accepted extensions
Images	`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`
Logs & text	`.txt`, `.log`, `.out`, `.err`, `.json`, `.jsonl`, `.ndjson` (plus rotated variants like `.log.1`, `.log.2`)
Documents	`.pdf`, `.docx`

Default per-question limits (configurable per guru):

Type	Max files	Max size per file
Images	5	5 MB
Logs & text	5	5 MB
PDFs	3	5 MB
DOCX	3	5 MB

Compressed archives (.gz, .zip, .bz2) are not supported; decompress before uploading. Default texts, with {name} being the Display name or else the Guru name:

Setting	English	Turkish
Button text	`Ask AI`	`AI'a Sor`
Header	`Ask {name} Guru`	`{name} Guru'ya Sor`
Input placeholder, Welcome heading	`Ask anything about {name}`	`{name} hakkında herhangi bir şey sor`
Welcome message	`{name} Guru uses the latest data from {name} sources to answer your questions.`	`{name} Guru, {name} kaynaklarından en son verileri kullanarak sorularınıza cevap verir.`
Assistant name	`{name} Guru`	`{name} Guru`

Install

The Install section has the Widget ID and the script to add to your website. The script carries only the Widget ID (and, on self-hosted, your backend address), because everything else comes from the settings above.

Copy ID: the Widget ID alone, for SharePoint, Zendesk and other packaged installs that ask for it.
Copy script: the script tag for your site’s HTML.
Copy prompt for AI coding assistants: a prompt for Cursor, Claude Code and similar tools that detects your framework, follows its guide in these docs and adds the script.

Options only the page can set adds attributes that belong to one page rather than to the Widget ID, so they change the copied script and are not saved:

Full screen (data-window-mode="embedded"): the widget fills the page and opens at once, with no close button. For pages that exist only to host the assistant, such as one opened inside a mobile app.
Open on load (data-auto-open="true"): opens the chat when the page loads.
Pass user email (data-pass-user-info and data-user-email-source, the newer name of data-user-info-source; both work): see User Identification.

Basic Installation

Add this script to your website’s HTML:

<!-- Gurubase Widget -->
<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  id="guru-widget-id"
></script>

Configuration Options

Settings saved on the Widget ID take precedence over these attributes. An attribute applies only where the Widget ID leaves that setting empty, except data-window-mode="embedded", which only the page can request.

Option	Description	Default
`data-widget-id`	Your Widget ID (required)	-
`data-text`	Button text	”Ask AI”
`data-margins`	Button positioning	`{"bottom": "1rem", "right": "1rem"}`
`data-light-mode`	Light mode toggle. Possible values are `"light"`, `"dark"`, `"auto"`. Auto mode syncs the widget theme with the website’s theme	`"dark"`
`data-window-mode`	Display mode for the chat window. Options: `"sidebar"`, `"floating"`, `"embedded"` (fills the page, already open, no close button)	`"sidebar"`
`data-auto-open`	`"true"` opens the chat when the page loads	`"false"`
`data-bg-color`	Primary color	Fetched from Gurubase
`data-shimmer-color`	Color for the animated shimmer effect on example questions. Accepts hex color values (e.g., “#0000FF”). If not set, uses `data-bg-color`. Falls back to red if neither is available.	Uses `data-bg-color` or red fallback
`data-icon-url`	Custom logo URL	Fetched from Gurubase
`data-name`	Custom name	Fetched from Gurubase
`data-base-url`	URL to your Gurubase backend. Only for self-hosted Gurubase (Enterprise plan).	Gurubase Cloud
`data-tooltip`	Tooltip text	null
`data-tooltip-side`	`"top"`, `"bottom"`, `"left"`, `"right"`, `"top left"`, `"top right"`, `"bottom left"`, `"bottom right"`	`"left"`
`data-overlap-content`	Whether to overlap the main content or shrink its width with the sidebar	`"false"`
`data-language`	Language of the widget interface. Supported values are `"en"` and `"tr"`; any other value falls back to English.	`"en"`
`data-example-questions`	JSON array of strings that replaces the example questions configured for the Guru, on this page only. See Example Questions.	Fetched from Gurubase
`data-pass-user-info`	Enable passing user identifier to the server and displaying the user’s name in chat. On Zendesk Help Center pages, automatically uses `HelpCenter.user.email` for identification and `HelpCenter.user.name` for display. Falls back to localStorage via `data-user-info-source`.	false
`data-user-info-source`	localStorage path to user info (supports dot notation, e.g., “ajs_user_traits.email”). Only needed for non-Zendesk sites.	null
`data-end-user-auth`	`"zendesk-hc"` on a Zendesk Help Center that requires sign-in. Sends the signed-in user’s Help Center token with every request. See Require signed-in Help Center users.	null

Window Modes

The widget supports two display modes for the chat window:

Sidebar Mode (Default)

The traditional sidebar experience where the chat window slides in from the right edge of the screen.

Floating Mode

A modern modal-style experience where the chat opens as a centered floating window.

Floating Mode Example

<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-window-mode="floating"
  id="guru-widget-id"
></script>

Self-hosted Installation (Enterprise Only)

Self-hosted installations are exclusively available under the Enterprise plan. To request access, contact us at [email protected].If you’re using self-hosted Gurubase, you must set the Gurubase instance URL using the data-base-url attribute. The default URL of Self-hosted Gurubase instance is http://localhost:8029/api/.

<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-base-url="http://localhost:8029/api/"
  id="guru-widget-id"
></script>

Customization Examples

Custom Button Text and Position

<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-text="Need Help?"
  data-margins='{"bottom": "2rem", "right": "2rem"}'
  id="guru-widget-id"
></script>

Light Mode with Custom Colors

<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-light-mode="auto"
  data-bg-color="#0D9373"
  id="guru-widget-id"
></script>

Exposed Functions

The widget exposes the following functions via window.chatWidget:

switchTheme(lightMode = null) Sync the theme of the widget with your website’s theme. Accepts an optional lightMode parameter:
- switchTheme(): Toggle the theme
- switchTheme(true): Force light mode
- switchTheme(false): Force dark mode
Example: window.chatWidget.switchTheme(true); See the MkDocs example for theme syncing implementation.
destroy() Remove the widget from the DOM and clean up all event listeners. Useful for SPAs where you want to conditionally show/hide the widget based on the current route. Example: window.chatWidget.destroy(); See Path-Based Widget Loading for a complete example.

Example Questions

You can display custom example questions in your widget to help guide users on what they can ask. These questions appear when users open the widget, providing helpful prompts to get started.

To configure example questions:

Go to your Guru’s settings page
Scroll to Advanced Settings
Add up to 3 example questions (100 characters max each)
Save your changes

When users click an example question in the widget, it populates the input field so they can submit it directly or modify it first.

Per-page example questions

Example questions are configured on the Guru, so every page that embeds the widget shows the same list. If you embed the same Guru on pages in different languages or sections, pass data-example-questions to override the list for that page:

<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-language="en"
  data-example-questions='["What is Gurubase?","How do I add a data source?"]'
  id="guru-widget-id"
></script>

The value is a JSON array of strings. Pair it with data-language so the interface and the questions are in the same language. If the value is missing, empty, or not valid JSON, the widget logs a warning and falls back to the questions configured for the Guru.

Learn More

See the full Example Questions guide for best practices and tips

User Identification

The widget can automatically identify users and include their information in API requests as external_user_id. It also displays the user’s name in chat messages instead of the default “You” label. This supports two methods: automatic detection on Zendesk Help Center pages and manual configuration via localStorage.

How It Works

When data-pass-user-info="true" is set, the widget:

Checks for Zendesk’s HelpCenter.user.email for user identification (automatic, no extra config needed)
Falls back to reading from localStorage via data-user-info-source if HelpCenter is not available
Sends the extracted value as external_user_id to the backend
Displays the user’s name in chat messages using this fallback order:
- HelpCenter.user.name (Zendesk only)
- HelpCenter.user.email (Zendesk only)
- data-user-info-source value from localStorage
- “You” (default if none of the above are available)
Fails silently if data is unavailable (won’t break widget functionality)

Zendesk Help Center (Automatic)

On Zendesk Help Center pages, the widget automatically detects the logged-in user’s email for identification and their name for display. No data-user-info-source is needed:

<script async src="https://widget.gurubase.io/widget.latest.min.js"
    data-widget-id="YOUR_WIDGET_ID"
    data-pass-user-info="true"
    id="guru-widget-id">
</script>

localStorage (Other Sites)

For non-Zendesk sites, configure data-user-info-source to read from localStorage. Supports dot notation for nested JSON objects.

<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-pass-user-info="true"
  data-user-info-source="ajs_user_traits.email"
  id="guru-widget-id"
></script>

Common Use Cases

Segment Analytics:

data-pass-user-info="true" data-user-info-source="ajs_user_traits.email"

Extracts email from Segment’s user traits object stored as:

localStorage['ajs_user_traits'] = '{"email": "[email protected]", "name": "John Doe"}'

Mixpanel:

data-pass-user-info="true" data-user-info-source="mp_user_properties.email"

Custom User Data:

data-pass-user-info="true" data-user-info-source="userData.userId"

Top-level localStorage key (no nesting):

data-pass-user-info="true" data-user-info-source="user_id"

If you want to load the widget only on specific paths (e.g., only on /docs/ pages), you can use a conditional loading approach. This is especially useful for Single Page Applications (SPAs) where you need to handle client-side navigation. The following script can be adapted to any SPA framework (Docusaurus, Next.js, Remix, etc.):

(function () {
  var widgetInitialized = false;

  function isDocsPath(pathname) {
    return pathname === "/docs" || pathname.startsWith("/docs/");
  }

  function initWidget() {
    if (widgetInitialized) return;
    // Only show on /docs pages - modify this path as needed
    if (!isDocsPath(window.location.pathname)) return;

    var existingScript = document.getElementById("guru-widget-id");
    if (existingScript) return;

    var script = document.createElement("script");
    script.src = "https://widget.gurubase.io/widget.latest.min.js";
    script.setAttribute("data-widget-id", "YOUR_WIDGET_ID");
    script.setAttribute("data-text", "Ask AI");
    script.setAttribute("data-margins", '{"bottom": "20px", "right": "20px"}');
    script.setAttribute("data-light-mode", "auto");
    script.setAttribute("data-overlap-content", "true");
    script.defer = true;
    script.id = "guru-widget-id";
    document.body.appendChild(script);
    widgetInitialized = true;
  }

  function destroyWidget() {
    if (!widgetInitialized) return;

    // Use widget's destroy method if available
    if (window.chatWidget && typeof window.chatWidget.destroy === "function") {
      window.chatWidget.destroy();
    }

    // Remove the script tag
    var script = document.getElementById("guru-widget-id");
    if (script) script.remove();

    // Remove widget instance
    if (window.chatWidget) delete window.chatWidget;
    if (window.ChatWidget) delete window.ChatWidget;

    // Remove all widget-related DOM elements
    ["#guru-widget-id", "#gurubase-chat-widget-container"].forEach(
      function (selector) {
        try {
          document.querySelectorAll(selector).forEach(function (el) {
            el.remove();
          });
        } catch (e) {}
      },
    );

    widgetInitialized = false;
  }

  function handleRouteChange() {
    if (isDocsPath(window.location.pathname)) {
      initWidget();
    } else {
      destroyWidget();
    }
  }

  function setup() {
    // Check on initial page load
    handleRouteChange();

    // Hook into History API for SPA client-side navigation
    var originalPushState = history.pushState;
    history.pushState = function () {
      originalPushState.apply(this, arguments);
      setTimeout(handleRouteChange, 0);
    };

    var originalReplaceState = history.replaceState;
    history.replaceState = function () {
      originalReplaceState.apply(this, arguments);
      setTimeout(handleRouteChange, 0);
    };

    // Handle browser back/forward buttons
    window.addEventListener("popstate", function () {
      setTimeout(handleRouteChange, 0);
    });
  }

  // Wait for DOM to be ready before accessing document.body
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", setup);
  } else {
    setup();
  }
})();

Key points:

The isDocsPath() helper matches both /docs and /docs/* paths (modify this function to match your desired paths)
The initWidget() function checks the current path before loading the widget
The destroyWidget() function cleans up all widget-related DOM elements when navigating away
History API hooks (pushState, replaceState, popstate) handle SPA navigation

Docusaurus Plugin Example

For Docusaurus, you can wrap this in a plugin. Create plugins/gurubase-widget.js:

module.exports = (_context) => ({
  name: "docusaurus-plugin-gurubase-widget",
  injectHtmlTags() {
    return {
      postBodyTags: [
        {
          tagName: "script",
          innerHTML: `
            (function() {
              var widgetInitialized = false;

              function isDocsPath(pathname) {
                return pathname === '/docs' || pathname.startsWith('/docs/');
              }

              function initWidget() {
                if (widgetInitialized) return;
                if (!isDocsPath(window.location.pathname)) return;

                var existingScript = document.getElementById('guru-widget-id');
                if (existingScript) return;

                var script = document.createElement('script');
                script.src = "https://widget.gurubase.io/widget.latest.min.js";
                script.setAttribute("data-widget-id", "YOUR_WIDGET_ID");
                script.setAttribute("data-light-mode", "auto");
                script.setAttribute("data-overlap-content", "true");
                script.defer = true;
                script.id = "guru-widget-id";
                document.body.appendChild(script);
                widgetInitialized = true;
              }

              function destroyWidget() {
                if (!widgetInitialized) return;
                if (window.chatWidget && typeof window.chatWidget.destroy === 'function') {
                  window.chatWidget.destroy();
                }
                var script = document.getElementById('guru-widget-id');
                if (script) script.remove();
                if (window.chatWidget) delete window.chatWidget;
                if (window.ChatWidget) delete window.ChatWidget;
                ['#guru-widget-id', '#gurubase-chat-widget-container'].forEach(function(selector) {
                  try { document.querySelectorAll(selector).forEach(function(el) { el.remove(); }); } catch (e) {}
                });
                widgetInitialized = false;
              }

              function handleRouteChange() {
                if (isDocsPath(window.location.pathname)) {
                  initWidget();
                } else {
                  destroyWidget();
                }
              }

              handleRouteChange();

              var originalPushState = history.pushState;
              history.pushState = function() {
                originalPushState.apply(this, arguments);
                setTimeout(handleRouteChange, 0);
              };

              var originalReplaceState = history.replaceState;
              history.replaceState = function() {
                originalReplaceState.apply(this, arguments);
                setTimeout(handleRouteChange, 0);
              };

              window.addEventListener('popstate', function() {
                setTimeout(handleRouteChange, 0);
              });
            })();
          `,
        },
      ],
    };
  },
});

Then register in docusaurus.config.js:

module.exports = {
  plugins: ["./plugins/gurubase-widget.js"],
};

Platform-Specific Integrations

Archbee

To add the Gurubase widget to your Archbee documentation:

Go to Space Settings > Custom Code
Under the “Include Headers” text area, paste the Gurubase widget script that you received from the Gurubase platform:

For security reasons, scripts are only included on a custom domain in Archbee. Make sure you have set up a custom domain for your documentation to use the widget.

GitBook

GitBook offers an official integration that makes it easy to add Gurubase to your documentation:

In your GitBook space, go to Integrations and search for Gurubase
Click Install to add the integration
Click Install on a docs site and select a site to install
Enter your Widget ID from Gurubase platform
Configure additional options (optional)

After a few minutes, you will see the “Ask AI” button in your GitBook documentation.

Mintlify

To add the Gurubase widget to your Mintlify documentation with automatic theme syncing, create a JavaScript file (e.g., gurubase.js) in your docs content folder with the following content:

// Customize widget settings
const widgetSettings = {
  widgetId: "YOUR_WIDGET_ID", // Replace with your Widget ID from https://app.gurubase.io/my-gurus
  overlapContent: true,
  // Optional configurations:
  // text: "Ask AI",
  // margins: { bottom: "20px", right: "20px" },
  // lightMode: "auto",
  // bgColor: "#000000",
};

function initGurubaseWidget() {
  // Guard against double initialization
  if (document.getElementById("guru-widget-id")) return;

  // Load the Gurubase widget
  const guruScript = document.createElement("script");
  guruScript.src = "https://widget.gurubase.io/widget.latest.min.js";
  guruScript.defer = true;
  guruScript.id = "guru-widget-id";

  // Add widget settings as data attributes
  Object.entries(widgetSettings).forEach(([key, value]) => {
    const dataKey = `data-${key.replace(/([A-Z])/g, "-$1").toLowerCase()}`;
    const dataValue = typeof value === "object" ? JSON.stringify(value) : value;
    guruScript.setAttribute(dataKey, dataValue);
  });

  // Initialize theme handling
  guruScript.addEventListener("load", () => {
    const initWidget = setInterval(() => {
      if (window.chatWidget?.switchTheme) {
        clearInterval(initWidget);

        // Handle theme changes
        const syncTheme = () => {
          const isDark = document.documentElement.classList.contains("dark");
          window.chatWidget.switchTheme(!isDark);
        };

        // Watch for theme changes
        new MutationObserver(syncTheme).observe(document.documentElement, {
          attributes: true,
          attributeFilter: ["class"],
        });

        // Set initial theme
        syncTheme();
      }
    }, 1000);

    // Stop checking after 20 seconds
    setTimeout(() => clearInterval(initWidget), 20000);
  });

  document.body.appendChild(guruScript);
}

// Wait for DOM to be ready before accessing document.body
if (document.readyState === "loading") {
  document.addEventListener("DOMContentLoaded", initGurubaseWidget);
} else {
  initGurubaseWidget();
}

Any .js file in your Mintlify content directory is automatically included on every page - no additional configuration needed. The widget will automatically sync its theme (light/dark) with your Mintlify documentation.

Docusaurus

Add the widget to your docusaurus.config.js:

module.exports = {
  scripts: [
    {
      src: "https://widget.gurubase.io/widget.latest.min.js",
      "data-widget-id": "YOUR_WIDGET_ID",
      "data-light-mode": "auto",
      id: "guru-widget-id",
      async: true,
    },
  ],
};

For path-based loading (showing the widget only on specific pages like /docs/), see Path-Based Widget Loading.

MkDocs (Material)

For MkDocs with the Material theme, you can add theme syncing so the widget matches your documentation’s light/dark mode.

Add the widget script to your mkdocs.yml:

extra_javascript:
  - js/gurubase-widget.js

Create docs/js/gurubase-widget.js:

(function () {
  function initWidget() {
    // Guard against double initialization
    if (document.getElementById("guru-widget-id")) return;

    // Load the widget
    var script = document.createElement("script");
    script.src = "https://widget.gurubase.io/widget.latest.min.js";
    script.setAttribute("data-widget-id", "YOUR_WIDGET_ID");
    script.setAttribute("data-light-mode", "auto");
    script.defer = true;
    script.id = "guru-widget-id";
    document.body.appendChild(script);

    // Theme sync for Material theme
    script.onload = function () {
      var checkWidget = setInterval(function () {
        if (window.chatWidget && window.chatWidget.switchTheme) {
          clearInterval(checkWidget);

          function syncTheme() {
            // Material theme uses data-md-color-scheme on body
            var scheme = document.body.getAttribute("data-md-color-scheme");
            var isLight = scheme === "default" || scheme === "light";
            window.chatWidget.switchTheme(isLight);
          }

          // Watch for theme changes
          new MutationObserver(syncTheme).observe(document.body, {
            attributes: true,
            attributeFilter: ["data-md-color-scheme"],
          });

          syncTheme();
        }
      }, 500);

      setTimeout(function () {
        clearInterval(checkWidget);
      }, 20000);
    };
  }

  // Wait for DOM to be ready before accessing document.body
  if (document.readyState === "loading") {
    document.addEventListener("DOMContentLoaded", initWidget);
  } else {
    initWidget();
  }
})();

Sphinx / Read the Docs

For Sphinx documentation (including Read the Docs), you can add the widget using either a static JavaScript file or a template override.

Important: Choose only ONE of the following approaches. Using both will cause the widget to load twice.

Option A: Static JavaScript File (Recommended)

Use this approach for a cleaner setup with all widget configuration in a single JavaScript file.

Create _static/gurubase-widget.js:

document.addEventListener("DOMContentLoaded", function () {
  // Customize widget settings
  const widgetSettings = {
    widgetId: "YOUR_WIDGET_ID", // Replace with your Widget ID from https://app.gurubase.io/my-gurus
    text: "Ask AI", // Optional - Button text
    margins: { bottom: "20px", right: "20px" }, // Optional
    lightMode: "auto", // Optional - "light", "dark", or "auto"
    bgColor: "#0D9373", // Optional - Widget background color
    iconUrl: "YOUR_ICON_URL", // Optional - Widget icon URL
    name: "YOUR_NAME", // Optional - Widget name
    // baseUrl: "http://localhost:8029/api/", // Optional - For self-hosted Gurubase (Enterprise only)
  };

  // Load the Gurubase widget
  const guruScript = document.createElement("script");
  guruScript.src = "https://widget.gurubase.io/widget.latest.min.js";
  guruScript.defer = true;
  guruScript.id = "guru-widget-id";

  // Add widget settings as data attributes
  Object.entries({
    "data-widget-id": widgetSettings.widgetId,
    "data-text": widgetSettings.text,
    "data-margins": JSON.stringify(widgetSettings.margins),
    "data-light-mode": widgetSettings.lightMode,
    "data-bg-color": widgetSettings.bgColor,
    "data-icon-url": widgetSettings.iconUrl,
    "data-name": widgetSettings.name,
    "data-base-url": widgetSettings.baseUrl,
  }).forEach(([key, value]) => {
    if (value) {
      // Only set if value is defined
      guruScript.setAttribute(key, value);
    }
  });

  // Append the script to the document
  document.body.appendChild(guruScript);
});

Add the script to your conf.py:

# Static files directory
html_static_path = ['_static']

# Add the widget script to all pages
html_js_files = [
    'gurubase-widget.js',
]

Option B: Template Override

Use this approach if you prefer to add the widget directly in HTML templates.

Create or edit _templates/layout.html:

{% extends "!layout.html" %} {% block extrahead %} {{ super() }}
<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-light-mode="auto"
  id="guru-widget-id"
></script>
{% endblock %}

Make sure your conf.py includes the templates path:

templates_path = ['_templates']

Theme Sync for Dark Mode

For themes with dark mode support (like Furo or PyData), add theme syncing to automatically match the widget theme with your documentation. Using static JS file (_static/gurubase-widget.js):

document.addEventListener("DOMContentLoaded", function () {
  const widgetSettings = {
    widgetId: "YOUR_WIDGET_ID",
  };

  const guruScript = document.createElement("script");
  guruScript.src = "https://widget.gurubase.io/widget.latest.min.js";
  guruScript.defer = true;
  guruScript.id = "guru-widget-id";
  guruScript.setAttribute("data-widget-id", widgetSettings.widgetId);
  document.body.appendChild(guruScript);

  // Theme sync for Sphinx themes with dark mode
  guruScript.onload = function () {
    var checkWidget = setInterval(function () {
      if (window.chatWidget && window.chatWidget.switchTheme) {
        clearInterval(checkWidget);

        function syncTheme() {
          var isDark =
            document.body.dataset.theme === "dark" ||
            document.documentElement.dataset.theme === "dark";
          window.chatWidget.switchTheme(!isDark);
        }

        new MutationObserver(syncTheme).observe(document.documentElement, {
          attributes: true,
          attributeFilter: ["data-theme"],
        });

        new MutationObserver(syncTheme).observe(document.body, {
          attributes: true,
          attributeFilter: ["data-theme"],
        });

        syncTheme();
      }
    }, 500);

    setTimeout(function () {
      clearInterval(checkWidget);
    }, 20000);
  };
});

Using template override (_templates/layout.html):

{% block extrahead %} {{ super() }}
<script>
  document.addEventListener("DOMContentLoaded", function () {
    var script = document.createElement("script");
    script.src = "https://widget.gurubase.io/widget.latest.min.js";
    script.setAttribute("data-widget-id", "YOUR_WIDGET_ID");
    script.defer = true;
    script.id = "guru-widget-id";
    document.body.appendChild(script);

    script.onload = function () {
      var initWidget = setInterval(function () {
        if (window.chatWidget && window.chatWidget.switchTheme) {
          clearInterval(initWidget);

          function syncTheme() {
            var isDark =
              document.body.dataset.theme === "dark" ||
              document.documentElement.dataset.theme === "dark";
            window.chatWidget.switchTheme(!isDark);
          }

          new MutationObserver(syncTheme).observe(document.documentElement, {
            attributes: true,
            attributeFilter: ["data-theme"],
          });

          syncTheme();
        }
      }, 500);
    };
  });
</script>
{% endblock %}

Zendesk Knowledge Base

For Zendesk Help Center themes (like Copenhagen), add the widget to your theme’s script.js file.

Navigate to your Zendesk Help Center (e.g., https://<your-subdomain>.zendesk.com/hc/en-us)
Open Knowledge Admin
Select Customize design from the left sidebar (Eye icon)
Click Customize on the Live theme
Click Edit code to open the theme editor
Open the script.js file
Add the following code just before the closing })(); at the end of the file:

// Gurubase Widget
window.addEventListener("DOMContentLoaded", () => {
  // Guard against double initialization
  if (document.getElementById("guru-widget-id")) return;

  // Customize widget settings
  const widgetSettings = {
    widgetId: "YOUR_WIDGET_ID", // Replace with your Widget ID from https://app.gurubase.io/my-gurus
    text: "Ask AI", // Optional - Button text
    margins: { bottom: "20px", right: "20px" }, // Optional
    lightMode: "light", // Optional - "light", "dark", or "auto"
    passUserInfo: true, // Pass user identifier from Zendesk HelpCenter.user.email (automatic for Zendesk)
    // endUserAuth: "zendesk-hc", // Optional - Answer only signed-in Help Center users (see below)
    // bgColor: "#0D9373", // Optional - Widget background color
    // iconUrl: "YOUR_ICON_URL", // Optional - Widget icon URL
    // name: "YOUR_NAME", // Optional - Widget name
    // baseUrl: "https://gurubase.yourcompany.com/api/", // Optional - For self-hosted Gurubase (Enterprise only)
  };

  // Load the Gurubase widget
  const guruScript = document.createElement("script");
  guruScript.src = "https://widget.gurubase.io/widget.latest.min.js";
  guruScript.defer = true;
  guruScript.id = "guru-widget-id";

  // Add widget settings as data attributes
  Object.entries({
    "data-widget-id": widgetSettings.widgetId,
    "data-text": widgetSettings.text,
    "data-margins": JSON.stringify(widgetSettings.margins),
    "data-light-mode": widgetSettings.lightMode,
    "data-pass-user-info": widgetSettings.passUserInfo,
    "data-end-user-auth": widgetSettings.endUserAuth,
    "data-bg-color": widgetSettings.bgColor,
    "data-icon-url": widgetSettings.iconUrl,
    "data-name": widgetSettings.name,
    "data-base-url": widgetSettings.baseUrl,
  }).forEach(([key, value]) => {
    if (value) {
      // Only set if value is defined
      guruScript.setAttribute(key, value);
    }
  });

  // Append the script to the document
  document.body.appendChild(guruScript);
});

Click Save and then Publish to make the changes live

Make sure to create a Widget ID for your Zendesk Help Center domain (e.g., yourcompany.zendesk.com or your custom domain) in the Gurubase platform.

Alternative: Using document_head.hbs Template

If you prefer to add the widget via the template, edit templates/document_head.hbs and add the script tag:

<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-text="Ask AI"
  data-light-mode="auto"
  data-pass-user-info="true"
  id="guru-widget-id"
></script>

For self-hosted Gurubase (Enterprise plan), add data-base-url="https://gurubase.yourcompany.com/api/" to point to your instance.

Require signed-in Help Center users

A Widget ID and the page’s address are public. On a Help Center that requires sign-in they do not stop someone from calling the assistant directly and reading your knowledge base. Turn on this setting to answer only visitors who are signed in to your Help Center.

Add data-end-user-auth="zendesk-hc" to the widget script in your theme (or set endUserAuth: "zendesk-hc" in the script.js example above) and publish the theme. Nothing changes for visitors yet.

<script
  async
  src="https://widget.gurubase.io/widget.latest.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-end-user-auth="zendesk-hc"
  id="guru-widget-id"
></script>

In Gurubase, open your Guru’s Integrations > Web Widget page and click Show </> next to the Widget ID for your Help Center.
Under Sign-in, turn on Require signed-in Zendesk Help Center users and enter your Zendesk subdomain, the part before .zendesk.com (for https://acme.zendesk.com it is acme). Use it even if your Help Center has its own domain. Click Save. From now on only signed-in visitors are answered.

The Widget ID’s domain must be exact, not a wildcard: Gurubase refuses to turn the setting on for a wildcard Widget ID. If your Help Center has its own domain, use exactly that domain (for example https://help.example.com). A token is accepted only when it was issued for https://<subdomain>.zendesk.com or for the Widget ID’s exact domain. How it works:

The widget asks your Help Center for a token for the signed-in user (/api/v2/help_center/integration/token.json) and sends it as the X-End-User-Token header. The token is a short-lived JWT that Zendesk signs.
Gurubase checks the signature against your account’s public keys, the expiry, and that the token was issued for this Help Center. Every widget endpoint refuses a request without a valid token, including direct calls with only the Widget ID.
Follow-up suggestions and answer votes are shared with the Gurubase web app and API. They require the token when the call carries the Widget ID; without it they apply their usual rules (for example, anonymous votes on a public Guru, which need the answer’s slug).
Signed-out visitors see Sign in to use the assistant in the widget instead of an error.
The Zendesk user from the token is the external_user_id for analytics, per-user rate limits and End-User Memory. Their Zendesk primary email, as the token carries it, reaches Custom Actions as GURUBASE_USER_EMAIL and is the requester of tickets filed from the widget. Anything the page itself claims about the user is ignored.
A Custom Action that makes authorization decisions should use external_user_id (the stable Zendesk user id), not the email.
“Signed in” means whatever your Help Center allows: with open sign-up, anyone who registers counts as signed in. Restrict sign-up in Zendesk if the assistant is for existing customers only.
The live preview in Gurubase keeps working without a Help Center session.

Help Center tokens are available on Zendesk Guide Enterprise and Suite Enterprise plans. Publish the script change before turning the setting on: a widget without data-end-user-auth sends no token, so every visitor would see the sign-in message.

Self-hosted behind a CDN or proxy (for example Amazon CloudFront): the origin request policy must forward the X-End-User-Token header to Gurubase, and the browser’s OPTIONS preflight must reach Gurubase rather than be answered from cache. Otherwise the header is dropped and every visitor reads as signed out.

Astro / Starlight

For Astro with Starlight documentation theme:

Important: Choose only ONE of the following approaches. Using both will cause the widget to load twice since both methods add a script with the same id='guru-widget-id'.

Option A: Component Approach (Recommended for Theme Sync)

Use this approach if you need automatic theme synchronization with Starlight’s dark/light mode. Create src/components/GurubaseWidget.astro:

<script>
  // Guard against double initialization
  if (!document.getElementById('guru-widget-id')) {
    const script = document.createElement('script');
    script.src = 'https://widget.gurubase.io/widget.latest.min.js';
    script.setAttribute('data-widget-id', 'YOUR_WIDGET_ID');
    script.setAttribute('data-light-mode', 'auto');
    script.defer = true;
    script.id = 'guru-widget-id';
    document.body.appendChild(script);

    // Starlight theme sync
    script.onload = () => {
      const initWidget = setInterval(() => {
        if (window.chatWidget?.switchTheme) {
          clearInterval(initWidget);

          const syncTheme = () => {
            const isDark = document.documentElement.dataset.theme === 'dark';
            window.chatWidget.switchTheme(!isDark);
          };

          new MutationObserver(syncTheme).observe(document.documentElement, {
            attributes: true,
            attributeFilter: ['data-theme']
          });

          syncTheme();
        }
      }, 500);

      setTimeout(() => clearInterval(initWidget), 20000);
    };
  }
</script>

Then import and use this component in your layout. Do not add the widget to astro.config.mjs head if using this approach.

Option B: Config Approach (Simpler Setup)

Use this approach for a simpler setup without theme synchronization. Add to astro.config.mjs:

import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";

export default defineConfig({
  integrations: [
    starlight({
      // ... other config
      head: [
        {
          tag: "script",
          attrs: {
            src: "https://widget.gurubase.io/widget.latest.min.js",
            "data-widget-id": "YOUR_WIDGET_ID",
            "data-light-mode": "auto",
            id: "guru-widget-id",
            defer: true,
          },
        },
      ],
    }),
  ],
});

Do not create or use the GurubaseWidget.astro component if using this approach.

Retype

For Retype documentation: Add the widget script to your retype.yml:

integrations:
  custom:
    head: |
      <script async src="https://widget.gurubase.io/widget.latest.min.js" 
          data-widget-id="YOUR_WIDGET_ID"
          data-light-mode="auto"
          id="guru-widget-id">
      </script>

Troubleshooting

Widget not appearing

Widget appears twice

Theme not syncing with website

Ensure you’re using data-light-mode="auto" for automatic detection - For custom theme sync, verify your MutationObserver is watching the correct element and attribute - Check that window.chatWidget.switchTheme() is being called after the widget loads

Widget not working on localhost

Next Steps

Example Questions

Configure example questions for your widget

API Reference

Explore our API documentation

​Prerequisites

​Getting Your Widget ID

​Widget Settings

​Install

​Basic Installation

​Configuration Options

​Window Modes

Sidebar Mode (Default)

Floating Mode

​Floating Mode Example

​Self-hosted Installation (Enterprise Only)

​Customization Examples

​Custom Button Text and Position

​Light Mode with Custom Colors

​Exposed Functions

​Example Questions

​Per-page example questions

Learn More

​User Identification

​How It Works

​Zendesk Help Center (Automatic)

​localStorage (Other Sites)

​Common Use Cases

​Path-Based Widget Loading

​Platform-Specific Integrations

​Archbee

​GitBook

​Mintlify

​Docusaurus

​MkDocs (Material)

​Sphinx / Read the Docs

​Option A: Static JavaScript File (Recommended)

​Option B: Template Override

​Theme Sync for Dark Mode

​Zendesk Knowledge Base

​Alternative: Using document_head.hbs Template

​Require signed-in Help Center users

​Astro / Starlight

​Option A: Component Approach (Recommended for Theme Sync)

​Option B: Config Approach (Simpler Setup)

​Retype

​Troubleshooting

​Next Steps

Example Questions

API Reference

Prerequisites

Getting Your Widget ID

Widget Settings

Install

Basic Installation

Configuration Options

Window Modes

Floating Mode Example

Self-hosted Installation (Enterprise Only)

Customization Examples

Custom Button Text and Position

Light Mode with Custom Colors

Exposed Functions

Example Questions

Per-page example questions

User Identification

How It Works

Zendesk Help Center (Automatic)

localStorage (Other Sites)

Common Use Cases

Path-Based Widget Loading

Platform-Specific Integrations

Archbee

GitBook

Mintlify

Docusaurus

MkDocs (Material)

Sphinx / Read the Docs

Option A: Static JavaScript File (Recommended)

Option B: Template Override

Theme Sync for Dark Mode

Zendesk Knowledge Base

Alternative: Using document_head.hbs Template

Require signed-in Help Center users

Astro / Starlight

Option A: Component Approach (Recommended for Theme Sync)

Option B: Config Approach (Simpler Setup)

Retype

Troubleshooting

Next Steps