Dashboard

Documentation

GitHub Pages Integration Guide

Learn how to integrate Demeterics into your workflows with step-by-step guides and API examples.

GitHub Pages Integration Guide

Add the Demeterics AI Chat widget to your GitHub Pages site. GitHub Pages fully supports HTTPS and is perfectly secure for hosting the widget!

Requirements

  • A GitHub Pages site (public or private repository)
  • A Demeterics AI Chat widget (get your widget key from the AI Chat dashboard)
  • Basic knowledge of HTML (or your static site generator)

Security Confirmation

Yes, GitHub Pages is secure for the Demeterics widget!

  • ✅ HTTPS Everywhere: All GitHub Pages sites use HTTPS (via Let's Encrypt)
  • ✅ Custom Domains: Your custom domain gets a free SSL certificate
  • ✅ No Mixed Content: The widget loads over HTTPS, ensuring no security warnings
  • ✅ Domain Validation: Demeterics validates your GitHub Pages domain just like any other site

Installation (Plain HTML)

If your GitHub Pages site uses plain HTML files:

Step 1: Get Your Widget Code

  1. Log into your Demeterics dashboard
  2. Go to AI Chat
  3. Click on your widget
  4. Copy your Agent Key (e.g., DEM-A4E4OWSVGHBN)

Step 2: Edit Your HTML Files

  1. Open your HTML file(s) in a text editor or GitHub's web editor
  2. Find the </body> closing tag (usually near the bottom of the file)
  3. Add this code just before </body>:
<!-- Demeterics AI Chat Widget -->
<script src="https://demeterics.com/widget/embed.js?k=DEM-YOUR-KEY-HERE" async></script>
<dem-agent name="default" title="Need help?" state="minimized"></dem-agent>
  1. Replace DEM-YOUR-KEY-HERE with your actual Agent Key
  2. Save the file

Step 3: Add to All Pages

Option 1: Manual - Repeat Step 2 for every HTML file in your site

Option 2: Template - If you use a template/layout file:

  1. Add the widget code to your main template/layout
  2. All pages using that template will automatically include the widget

Step 4: Commit and Push

  1. Commit your changes to Git:
git add .
git commit -m "Add Demeterics AI Chat widget"
git push origin main
  1. Wait 1-2 minutes for GitHub Pages to rebuild
  2. Visit your live site - the widget should appear!

Installation (Jekyll)

If you're using Jekyll (GitHub Pages' default static site generator):

Step 1: Edit Your Layout File

  1. Open _layouts/default.html (or your main layout file)
  2. Find the </body> tag
  3. Add this code just before </body>:
<!-- Demeterics AI Chat Widget -->
<script src="https://demeterics.com/widget/embed.js?k={{ site.demeterics_key }}" async></script>
<dem-agent name="default" title="Need help?" state="minimized"></dem-agent>

Step 2: Add Your Widget Key to Config

  1. Open _config.yml
  2. Add this line:
demeterics_key: "DEM-YOUR-KEY-HERE"
  1. Replace DEM-YOUR-KEY-HERE with your actual Agent Key

Step 3: Commit and Deploy

git add _layouts/default.html _config.yml
git commit -m "Add Demeterics AI Chat widget"
git push origin main

Wait for GitHub Pages to rebuild (1-2 minutes), then check your site!

Installation (Hugo, Gatsby, Next.js, etc.)

If you're using a modern static site generator:

General Approach

  1. Find your layout component or base template (e.g., layout.html, App.js, _app.js, base.html)
  2. Add the widget script to the <head> or before </body>
  3. Make sure the script loads on all pages

Hugo Example

Add to layouts/_default/baseof.html:

<!-- In the <body> section, before </body> -->
<script src="https://demeterics.com/widget/embed.js?k={{ .Site.Params.demeterics_key }}" async></script>
<dem-agent name="default" title="Need help?" state="minimized"></dem-agent>

In config.toml:

[params]
  demeterics_key = "DEM-YOUR-KEY-HERE"

Gatsby Example

Add to gatsby-browser.js:

export const onClientEntry = () => {
  const script = document.createElement('script');
  script.src = 'https://demeterics.com/widget/embed.js?k=DEM-YOUR-KEY-HERE';
  script.async = true;
  document.head.appendChild(script);

  const widget = document.createElement('dem-agent');
  widget.setAttribute('name', 'default');
  widget.setAttribute('title', 'Need help?');
  widget.setAttribute('state', 'minimized');
  document.body.appendChild(widget);
};

Next.js Example

Add to pages/_app.js or app/layout.tsx:

import Script from 'next/script';

export default function App({ Component, pageProps }) {
  return (
    <>
      <Component {...pageProps} />
      <Script src="https://demeterics.com/widget/embed.js?k=DEM-YOUR-KEY-HERE" strategy="lazyOnload" />
      <dem-agent name="default" title="Need help?" state="minimized"></dem-agent>
    </>
  );
}

Configure Allowed Domains

After adding the widget to your site:

For Default GitHub Pages Domain

  1. Go to your Demeterics dashboard → AI Chat → Your Widget
  2. Add to Allowed Domains:
    • yourusername.github.io (if using default GitHub Pages URL)

For Custom Domain

If you've set up a custom domain for your GitHub Pages site:

  1. Add your custom domain to Allowed Domains:
    • yoursite.com
    • www.yoursite.com (if applicable)
  2. GitHub Pages automatically provides HTTPS for custom domains via Let's Encrypt

For Project Pages

If using project pages (e.g., yourusername.github.io/projectname):

  1. Add to Allowed Domains:
    • yourusername.github.io

Important: Do not include the /projectname path in Allowed Domains - just the domain.

Customization Options

Change the Widget Title

<dem-agent name="default" title="Chat with us!"></dem-agent>

Use Different Prompts on Different Pages

If you've created multiple prompts in Demeterics:

Homepage (in index.html or homepage layout):

<dem-agent name="home" title="Welcome!"></dem-agent>

Documentation (in docs layout):

<dem-agent name="docs" title="Documentation Help"></dem-agent>

Support (in support pages):

<dem-agent name="support" title="How can we help?"></dem-agent>

Start the Widget Open

<dem-agent name="default" title="Need help?" state="open"></dem-agent>

Embedded Widget (Inline on Page)

To place the widget inline (not floating):

<dem-agent mode="embedded" name="default" title="Support Assistant"></dem-agent>

Troubleshooting

Widget doesn't appear

Check these:

  1. Did you wait for GitHub Pages to rebuild after your commit? (Check the Actions tab)
  2. Is your widget key correct?
  3. Is your GitHub Pages domain added to Allowed Domains in your Demeterics widget settings?
  4. Clear your browser cache and hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
  5. Check browser console for errors (F12 → Console tab)

"Domain not allowed for this agent"

  1. Go to your Demeterics dashboard → AI Chat → Your Widget
  2. Add your GitHub Pages domain to Allowed Domains:
    • Default: yourusername.github.io
    • Custom: yoursite.com (and www.yoursite.com if applicable)
  3. Do not include the repository path (e.g., /my-project)
  4. Save and refresh your website

HTTPS Mixed Content Warnings

If you see HTTPS warnings:

  1. Make sure the widget script uses https:// (not http://)
  2. Check that all your site's assets (images, CSS, JS) use HTTPS
  3. GitHub Pages enforces HTTPS automatically, so this should not be an issue

If you still see warnings, check your HTML for any http:// references and change them to https://.

Widget not working with SPA (Single Page Apps)

If your site is a Single Page Application (React, Vue, etc.):

  1. Make sure the widget script loads after the DOM is ready
  2. For client-side routing, ensure the widget reinitializes on route changes
  3. Check the framework-specific examples above (Gatsby, Next.js)

Build fails after adding widget code

If your site fails to build:

  1. Make sure you're not using invalid HTML in your template
  2. Check that you've closed all tags properly
  3. Ensure Jekyll/Hugo/etc. doesn't treat <dem-agent> as a template tag (use {% raw %} in Jekyll if needed)

Advanced: Environment Variables for Multiple Environments

If you deploy to multiple environments (dev, staging, production):

Jekyll Example

In _config.yml:

demeterics_key: "DEM-DEV-KEY"

In _config.production.yml:

demeterics_key: "DEM-PROD-KEY"

Build for production:

JEKYLL_ENV=production bundle exec jekyll build --config _config.yml,_config.production.yml

GitHub Actions Example

Use GitHub Secrets to store your widget key securely:

  1. Go to your repo → Settings → Secrets → Actions
  2. Add a secret named DEMETERICS_WIDGET_KEY with your key
  3. In your build workflow (.github/workflows/deploy.yml):
- name: Build site
  env:
    DEMETERICS_KEY: ${{ secrets.DEMETERICS_WIDGET_KEY }}
  run: npm run build

Then reference process.env.DEMETERICS_KEY in your code.

GitHub Pages + Open Source Projects

If you're using GitHub Pages for an open-source project:

Security Note: Your widget key will be visible in your HTML source code. This is expected and secure because:

  1. The widget key is not a secret - it's meant to be public
  2. Domain validation prevents others from using your widget on their sites
  3. Rate limiting prevents abuse

Best Practice: Always set Allowed Domains to only your GitHub Pages domain.

Need Help?

Email us: support@demeterics.com

We can help with:

  • Setting up the widget with your static site generator
  • Configuring custom domains with GitHub Pages
  • Writing documentation-specific prompts for developer sites
  • Advanced integration for SPAs
  • Troubleshooting build issues

Additional Resources