Docusaurus docs

Add a Docusaurus AI chatbot
to your docs site

Import the public HTML Docusaurus already builds, then load Heeya's embed script on that site. There is no npm package and no Docusaurus plugin. You scrape deployed pages over HTTPS, add one script in docusaurus.config.js, and refresh those URLs yourself after you ship.

Create a chatbot for your docs

This is the Docusaurus install path. The broader product page is AI customer support for SaaS.

Docs assistant

Illustrative conversation

How do I version docs without publishing /docs/next?
From the versioning guide: set lastVersion: 'current' so the docs/ folder is the version visitors see. That reply is only as current as the page you last imported.

Import public Docusaurus docs

Docusaurus is a static site generator. A production build writes one HTML file per route. Heeya does not read your docs/*.md files from GitHub. It fetches the live pages, the same way a visitor's browser would, then stores the extracted text in that agent's knowledge base.

  1. Create a Heeya agent and open its files screen.
  2. Paste the public HTTPS URL of the deployed docs site, not http://localhost:3000.
  3. Heeya discovers URLs from /sitemap.xml, /sitemap_index.xml, and any Sitemap: lines in robots.txt. If none of those exist, it falls back to /llms.txt or /llms-full.txt.
  4. Select the pages that should answer questions. Then scrape and train.
  5. Ask the questions your users actually ask in the dashboard chat before you embed anything.

Use the production sitemap, not localhost

The official sitemap plugin, shipped with @docusaurus/preset-classic, is inactive in development. It only writes sitemap.xml from a production build. That file is served at https://your-host/[baseUrl]/sitemap.xml.

Heeya only accepts https:// URLs and refuses private or loopback addresses. docusaurus start on your laptop cannot be imported. Deploy first, then paste the URL visitors use. If the site lives under a GitHub Pages subpath, include that baseUrl.

Checked against Docusaurus 3.10 docs and a live fetch of https://docusaurus.io/sitemap.xml on 7 September 2026: that file is a standard urlset with 1,366 <loc> entries covering docs, blog, and pages. A site that large will not fit in one Heeya scrape job. The default cap is 300 pages. Paste a path such as https://docs.example.com/docs so discovery keeps only URLs under that prefix, then pick from the list.

What Heeya keeps from a Docusaurus page

The crawler identifies itself as HeeyaBot/1.0. It does not run JavaScript. For HTML pages it drops script, style, nav, header, footer, and aside, then stores the remaining text.

That mapping fits the classic Docusaurus layout: navbar and often the sidebar sit in nav / aside, and the article lives in main. A check of https://docusaurus.io/docs shows those landmarks plus theme-doc-markdown. You get the page body without the chrome. You also get every tab panel that was already in the HTML, concatenated, and you do not get diagrams that exist only as canvas after hydration.

Versions, locales, and extra routes

Official versioning puts the latest docs at /docs, work in progress at /docs/next when that version is published, and frozen releases at /docs/1.0.0-style paths. i18n adds locale prefixes or separate hosts. All of those URLs can appear in one sitemap.

Import the version and language your visitors should hear. Skip /tags/, blog posts, and unreleased /docs/next unless the agent should answer from them. Pages marked noindex are omitted from the Docusaurus sitemap; if the whole site sets noIndex: true, no sitemap is generated and discovery has nothing to read unless you maintain llms.txt.

Embed the real Heeya widget

After the agent exists, the connect screen copies this snippet: 

<script async src="https://heeya.fr/agent/YOUR_AGENT_ID/embed.js" data-agent-name="Docs assistant"></script>

Replace YOUR_AGENT_ID with the UUID from that screen. Colors and the logo come from the agent settings, not from an npm prop. The same agent also has a full-page chat at https://heeya.fr/agent/YOUR_AGENT_ID/assistant.

Why Docusaurus cannot paste that tag before </body>

Heeya's loader stores document.currentScript, then does document.body.appendChild for the widget bundle. On a normal HTML page you put the tag at the end of body, which is why the dashboard snippet uses async there.

Docusaurus 3.10's scripts field injects tags into <head>. Their own docs say those tags are render-blocking unless you set async or defer. An async head script can run before body exists. Use defer: true so the loader runs after the document is parsed.

Verified docusaurus.config.js snippet

Object entries besides src become attributes. That is the documented API; extra keys must be booleans or strings. 

export default {
  scripts: [
    {
      src: 'https://heeya.fr/agent/YOUR_AGENT_ID/embed.js',
      defer: true,
      'data-agent-name': 'Docs assistant',
    },
  ],
};

Rebuild and deploy. Confirm in the built HTML that the tag is present and that the floating bubble appears after a full load. Client-side clicks between docs should keep it: the widget mounts on document.body, outside #__docusaurus.

Client module if you want a body inject

If the attribute does not survive your config toolchain, or you would rather insert the official tag into body yourself, use a client module. Client modules are the Docusaurus field for site-wide JavaScript. 

// src/heeya-widget.js
const AGENT_ID = 'YOUR_AGENT_ID';

(function loadHeeyaWidget() {
  if (typeof document === 'undefined') return;
  if (document.getElementById('heeya-embed')) return;

  const script = document.createElement('script');
  script.id = 'heeya-embed';
  script.async = true;
  script.src = 'https://heeya.fr/agent/' + AGENT_ID + '/embed.js';
  script.setAttribute('data-agent-name', 'Docs assistant');

  const inject = function () {
    if (document.body) document.body.appendChild(script);
  };

  if (document.body) inject();
  else document.addEventListener('DOMContentLoaded', inject);
})();
export default {
  clientModules: ['./src/heeya-widget.js'],
};

A navbar link to the hosted assistant is also valid Docusaurus config (href on a navbar item) if you do not want a bubble on every page. That URL still uses the same agent. It is not a second product.

Refresh sources after you ship docs

Shipping a Docusaurus build does not update Heeya. There is no GitHub Action, no webhook, and no nightly crawl in the product. Until you refresh, the agent answers from the last imported snapshot.

  1. Deploy the docs change so the public HTML matches what you want retrieved.
  2. In the agent files screen, choose Update URLs. That loads the website URLs already indexed for this agent.
  3. Heeya re-scrapes those URLs. Review the new text. Empty pages can be dropped or kept; the UI says old versions remain active until indexing completes.
  4. Confirm the replace. New chunks overwrite the selected URLs. Then re-ask the questions that used to fail.

Refresh only works on URLs this agent already trained as website sources. A brand-new page needs a new scrape, not an update of the old list. If a URL's content is gone, delete it so retrieval cannot quote a retired version.

For how to keep a corpus from drifting, use the knowledge base engineering guide. Retrieval still depends on that hygiene. It does not make unsupported answers impossible.

Limitations that matter on Docusaurus

What this path supports

  • Public HTTPS docs sites that emit a sitemap or an llms.txt index.
  • Statically rendered Markdown and MDX whose text is in the HTML.
  • The Heeya website widget, or a link to the hosted assistant URL.
  • Uploading PDF, DOCX, PPTX, or TXT next to the scraped pages, plus question-and-answer pairs.
  • A contact form in the conversation if you enable that tool.

What it does not do

  • No Heeya Docusaurus plugin, npm package, or React component.
  • No import of the git docs/ tree, and no localhost scrape.
  • No authenticated, VPN, or private-network docs.
  • No automatic refresh on git push.
  • No ticket router, Slack/WhatsApp channel, or source-citation panel in the widget.
  • Linked PDFs are not followed during website discovery.

robots.txt is read so Heeya can find Sitemap: declarations. It is not a full robots parser. Only import pages you are allowed to use as chatbot context. If you publish a Docusaurus static/robots.txt, you can point crawlers at the sitemap the plugin already generates.

RAG injects retrieved passages and tells the model to say when the information is missing. That reduces guesses. It does not remove them. Test answers against the current docs, especially after a version cut. Architecture detail lives on RAG expertise.

FAQ about a Docusaurus AI chatbot

Can Heeya import Markdown from my GitHub repo?

No. Heeya scrapes the published website over HTTPS. Point it at the deployed Docusaurus site, not the docs folder in git. docusaurus start on localhost is also blocked because the crawler refuses private addresses.

Is there a Heeya npm package or Docusaurus plugin?

No. The integration is the same script the connect screen gives you. Docusaurus loads it through scripts in docusaurus.config.js or a client module that inserts that script into document.body.

Will the widget disappear when I click another doc?

The widget container is appended to document.body, outside Docusaurus's #__docusaurus root. Client-side route changes replace the docs article, not the body-level bubble, so a first-load inject is enough.

How do I update answers after I edit a page?

There is no git webhook and no scheduled re-ingest. In the agent files screen, use Update URLs. Heeya re-scrapes the indexed pages, you review the new text, then replace. Old chunks stay until that indexing finishes.

Should I import every version and locale?

Only if you want those answers in the chatbot. A versioned sitemap lists /docs/, /docs/next/, and older /docs/1.x/ routes. Mixed versions produce mixed answers. Prefer the latest public version and one language.

Does the scraper execute React?

No. It reads the HTML Docusaurus generated at build time. That is enough for Markdown docs because they are statically rendered. Interactive MDX that only appears after hydration may be missing or incomplete.

Can I load private docs behind login?

No. Discovery and fetch require a public HTTPS URL. Pages behind authentication, VPN, or a private IP are out of scope.

Related reading

Product

AI customer support for SaaS

When a docs-grounded website agent is the right shape of product, including fit and non-fit.

Sources

Knowledge base engineering for AI chatbots

Inventory, hygiene, and drift: the work that makes retrieval usable after the first scrape.

Guide

AI chatbot for SaaS onboarding and support

The informational playbook for activation and CS workflow. Not a second Docusaurus tutorial.

Create a chatbot for the docs you already publish

Deploy the Docusaurus site, import the public pages, test the answers, then add the embed script with defer. Plans are on Heeya pricing.

Create a chatbot for your docs