Skip to main content

Ask AI chatbot widget for MadCap Flare

Add an AI chatbot or AI search widget to your MadCap Flare documentation using Biel.ai's web components.

Prerequisites​

  • A Biel.ai account. If you don't have one, sign up for free.
  • A project created in your Biel.ai dashboard. Follow the Quickstart guide to create one.
  • MadCap Flare installed on your computer.
  • A Flare project ready to modify.

Add the chatbot widget​

Chatbot widget for docs

Step 1: Modify the master page​

  1. Open your Flare project in MadCap Flare.

  2. In the Project Organizer, navigate to Content/Resources/MasterPages.

  3. Open the master page you're using (typically Home.flmsp or Other Topics.flmsp). If your project uses multiple master pages, repeat these steps for each one.

  4. Switch to the Text Editor view (bottom-left button).

  5. Add the Biel.ai initialization scripts in the <head> section:

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.css" />
    <script type="module" src="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.esm.js"></script>

  6. Just before the closing </body> tag, add the chatbot widget:

    <biel-button project="<YOUR_PROJECT_ID>"
        header-title="Biel.ai chatbot"
        button-position="bottom-right"
        modal-position="bottom-right"
        button-style="dark">
            Ask AI
    </biel-button>

    Replace <YOUR_PROJECT_ID> with your project's ID from the Biel.ai dashboard.

  7. Save the master page.

Step 2: Build and test​

  1. Build your target:

    • Select Project > Build Primary from the menu (or press F6).
    • Alternatively, build a specific target from the Project Organizer.

  2. Once the build completes, open the generated output in your default browser:

    • Select View > Open Output Folder.
    • Navigate to the HTML5 output folder.
    • Open index.htm or Default.htm in a web browser.

  3. Verify that the chatbot appears and works correctly on your pages.

Example master page snippet​

Your master page <head> section should look something like this:

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>
        <MadCap:variable name="System.Title" />
    </title>
    <link href="../Skins/Default/Stylesheets/Slideshow.css" rel="stylesheet" type="text/css" />
    <link href="../Skins/Default/Stylesheets/TextEffects.css" rel="stylesheet" type="text/css" />

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.css" />
    <script type="module" src="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.esm.js"></script>
</head>

And before the closing </body> tag:

    <biel-button project="<YOUR_PROJECT_ID>"
        header-title="Biel.ai chatbot"
        button-position="bottom-right"
        modal-position="bottom-right"
        button-style="dark">
            Ask AI
    </biel-button>
</body>

Working with multiple targets​

If your Flare project has multiple targets (HTML5, Top Navigation, etc.):

  1. Ensure each target uses a master page with the Biel.ai code added.
  2. You can use the same project ID across all targets.
  3. Build and test each target separately to verify the chatbot appears correctly.

Troubleshooting​

Chatbot not appearing after build

  • Verify the code was added to the correct master page
  • Check that your topics are using the modified master page
  • Clear your browser cache and reload the page
  • View the page source to confirm the scripts are included

Build warnings or errors

  • Flare may show warnings about external scripts (this is normal)
  • The chatbot will still work correctly in the output
  • You can safely ignore warnings about CDN-hosted scripts

Chatbot conflicts with Flare's built-in search

  • Biel.ai uses different positioning and won't interfere with Flare's search
  • If needed, adjust the button-position attribute (e.g., bottom-left, center-right)
  • You can also customize the appearance through CSS

Styling issues with Top Navigation output

  • Top Navigation skins may have different styling
  • See the customization section for CSS overrides
  • Consider adjusting button positioning for better visual integration

Next steps​