AI Chat Assistant

Configure the AI chat assistant safely for GitHub Pages using a proxy endpoint.

• Amr
• Published Jun 12, 2026
• Features
• Intermediate
• ai chatbot openai github-pages proxy
• View source

Estimated reading time: 20 minutes

• Share on Reddit
• Share on LinkedIn
• Share on X

• ---

• Page Improvements

• Improve Page Polish content, structure, and presentation of this page
• Expand Page Add depth, examples, and missing sections to this page
• Update Page Refresh outdated content, versions, links, and screenshots
• Fix Page Issue Report a typo, broken link, layout glitch, or content bug
• SEO Optimize Improve discoverability, metadata, and structured data
• Accessibility Audit Audit this page for WCAG 2.1 AA compliance

• ---

• Site Improvements

• UI/UX Improvement Propose a design or UX refinement for the theme
• New Feature Propose a new site-wide feature or capability
• Component Enhancement Improve a Jekyll layout, include, or shared component
• Performance Optimization Improve load time, Core Web Vitals, and asset delivery

Edit on GitHub

Table of Contents

AI Chat Assistant

Use the AI chat assistant with page-aware responses while keeping your GitHub Pages site static and secure.

Why Proxy Mode

GitHub Pages cannot run server-side code. If you call the OpenAI API directly from browser JavaScript, your key is exposed and CORS can fail.

The recommended approach is:

1. Keep the site static on GitHub Pages.
2. Send chat requests to your own proxy endpoint.
3. Let the proxy hold the OpenAI key server-side.

Configuration

Add this to your production config:

ai_chat:
  enabled: true
  auth_mode: 'proxy'
  proxy_ready: true
  endpoint: 'https://your-proxy.example.com/v1/chat/completions'
  strict_context: true
  out_of_scope_message: "I can only answer from the content on this page."

Important Defaults

• auth_mode: 'proxy' is the recommended mode.
• proxy_ready: false keeps the widget hidden unless your proxy is deployed.
• strict_context: true reduces hallucinations by grounding answers to the current page.

GitHub Pages Compatible Deployment Flow

1. Deploy your proxy endpoint first.
2. Set proxy_ready: true and endpoint to that proxy URL.
3. Build and publish your Jekyll site as usual.

Example build command:

jekyll build --config _config.yml

No client-side OpenAI key is required in proxy mode.

Optional Direct Mode (Not Recommended)

Direct mode sends requests from the browser to the provider API and may expose secrets in static output.

ai_chat:
  auth_mode: 'direct'
  api_key: 'sk-...'
  endpoint: 'https://api.openai.com/v1/chat/completions'

Use direct mode only for temporary local experiments.

Response Quality Improvements Included

The assistant now includes:

• Strict grounding: answers are constrained to page metadata and excerpt context.
• Out-of-scope fallback: returns a configured fallback message when context is missing.
• Safe markdown rendering: assistant output supports basic markdown formatting without unsafe HTML execution.

Troubleshooting

Widget does not appear

Check:

1. ai_chat.enabled is true.
2. If using proxy mode, proxy_ready is true.
3. Your endpoint is reachable from the browser.

Requests fail in browser

Check:

1. Proxy endpoint URL is correct.
2. Proxy returns CORS headers for your site origin.
3. Proxy can reach OpenAI and has a valid server-side API key.

Replies are too generic

Check:

1. strict_context is true.
2. context_max_length is high enough for your page content.
3. system_prompt still emphasizes page-only grounding.

Next Steps

• PostHog Analytics
• Site Search
• Features Index