> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Help Widget

Embed a help widget on your website that provides search, AI chat, and article suggestions from your documentation.

## Overview

The HolyDocs help widget is a lightweight, embeddable panel that gives your users instant access to documentation search, AI-powered chat, and suggested articles -- without leaving your application. It floats in the corner of your site and connects directly to your HolyDocs project.

## What the Widget Provides

**Search**

Full-text and semantic search across your entire documentation.
  **AI Chat**

Conversational AI assistant trained on your docs content.
  **Article Browsing**

Suggested articles and direct links to relevant pages.

## Quick Start

Add the widget to any webpage with a single script tag:

```html
<script
  src="https://api.holydocs.com/api/v1/widget/v1/widget.js"
  data-project-id="YOUR_PROJECT_ID"
  async
></script>
```

That's it. The widget appears in the bottom-right corner of your page with default styling.

Find your project ID in the dashboard under **Settings > General** or on the **Widget** page.

## Configuration

Customize the widget using `data-*` attributes on the script tag:

```html
<script
  src="https://api.holydocs.com/api/v1/widget/v1/widget.js"
  data-project-id="YOUR_PROJECT_ID"
  data-position="bottom-right"
  data-accent-color="#FBBF24"
  data-features="search,chat"
  async
></script>
```

### Available Attributes

| Attribute | Type | Default | Description |
|---|---|---|---|
| `data-project-id` | string | Required | Your HolyDocs project ID |
| `data-position` | `bottom-right` \| `bottom-left` | `bottom-right` | Widget launcher position |
| `data-accent-color` | hex color | `#FBBF24` | Primary color for the widget UI |
| `data-features` | comma-separated | `search,chat` | Enabled features: `search`, `chat` |

## Dashboard Configuration

You can also configure the widget from the dashboard without changing embed code:

**Open Widget settings**

Navigate to your project and click **Widget** in the sidebar.
  **Toggle features**

Enable or disable **Search** and **AI Chat** tabs. At least one must be enabled.
  **Set accent color**

Choose a color that matches your application's brand. The widget launcher button, links, and active states will use this color.
  **Customize greeting**

Set a custom greeting message that appears when the widget opens. The default is "Hi! How can I help you?"
  **Add suggested questions**

Add up to 4 suggested questions that appear when the chat tab opens. These help guide users toward common topics.
  **Copy embed code**

Click **Copy Embed Code** to get the configured script tag ready to paste into your site.

## Widget Features

### Search

The search tab provides the same full-text and semantic search available on your doc site. Results link directly to the relevant documentation page, opening in a new tab by default.

Search results include:
- Page titles and descriptions
- Section headings with deep links
- API endpoint paths (if you have OpenAPI docs)
- Code snippet matches

### AI Chat

The AI chat tab provides a conversational interface powered by the same AI assistant that runs on your doc site. It:

- Answers questions using your documentation as context
- Provides source citations with links to relevant pages
- Remembers context within a single conversation session
- Respects RBAC access controls (authenticated users only see content they can access)

### Suggested Questions

Pre-configure up to 4 suggested questions that appear as quick-action buttons in the chat tab:

```json
{
  "widget": {
    "suggestedQuestions": [
      "How do I authenticate API requests?",
      "What are the rate limits?",
      "How do I set up webhooks?",
      "What SDKs are available?"
    ]
  }
}
```

### Branding

By default, the widget displays a small "Powered by HolyDocs" badge. On **Pro** plans and above, you can disable this branding:

```html
<script
  src="https://api.holydocs.com/api/v1/widget/v1/widget.js"
  data-project-id="YOUR_PROJECT_ID"
  data-branding="false"
  async
></script>
```

## Theming

The widget automatically adapts to the user's system color scheme (light or dark mode). The accent color you set is used for interactive elements in both themes.

To force a specific theme:

```html
<script
  src="https://api.holydocs.com/api/v1/widget/v1/widget.js"
  data-project-id="YOUR_PROJECT_ID"
  data-theme="dark"
  async
></script>
```

| `data-theme` value | Behavior |
|---|---|
| `system` (default) | Follows `prefers-color-scheme` |
| `light` | Always light theme |
| `dark` | Always dark theme |

## Plan Requirements

The help widget is available on **Starter** plans and above. AI chat requires a **Pro** plan or higher. The free plan does not include widget access.

| Feature | Free | Starter | Pro | Business |
|---|---|---|---|---|
| Widget embed | -- | Yes | Yes | Yes |
| Search tab | -- | Yes | Yes | Yes |
| AI Chat tab | -- | -- | Yes | Yes |
| Custom branding | -- | -- | Yes | Yes |
| Suggested questions | -- | -- | Yes | Yes |

## Single-Page App Integration

For SPAs (React, Vue, Angular), load the widget script once and it handles route changes automatically. If you need to programmatically control the widget:

```javascript
// Open the widget
window.HolyDocsWidget?.open();

// Close the widget
window.HolyDocsWidget?.close();

// Open directly to the chat tab
window.HolyDocsWidget?.open('chat');

// Open directly to search with a pre-filled query
window.HolyDocsWidget?.search('how to authenticate');
```

## Content Security Policy

If your site uses a Content Security Policy, add these domains to allow the widget to load:

```
script-src: https://api.holydocs.com
connect-src: https://api.holydocs.com
style-src: 'unsafe-inline' https://api.holydocs.com
frame-src: https://api.holydocs.com
```

## Performance

The widget script is loaded asynchronously and weighs under 15 KB gzipped. It does not block page rendering. The launcher button renders immediately; the full panel is lazy-loaded on first open.

Widget API requests are served from Cloudflare's edge network, so search and chat responses are fast regardless of where your users are located.

## Troubleshooting

**Widget does not appear**

Verify your `data-project-id` is correct and that the project has at least one successful deployment. Check the browser console for errors.
  **Search returns no results**

Search requires a completed deployment with indexed content. Trigger a new deployment from the dashboard if your content has changed.
  **AI chat is disabled**

AI chat requires a Pro plan or higher. Upgrade your plan in **Settings > Plans & Billing**.
  **Widget blocked by CSP**

Add `https://api.holydocs.com` to your Content Security Policy directives. See the Content Security Policy section above.