Help Widget

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

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:

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 widgetwindow.HolyDocsWidget?.open();// Close the widgetwindow.HolyDocsWidget?.close();// Open directly to the chat tabwindow.HolyDocsWidget?.open('chat');// Open directly to search with a pre-filled querywindow.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:

text
script-src: https://api.holydocs.comconnect-src: https://api.holydocs.comstyle-src: 'unsafe-inline' https://api.holydocs.comframe-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