Docusaurus AI support chat widget

Deacon is an AI support chat for your Docusaurus site, added with one plugin. Readers ask in plain words and it answers in seconds from your own docs. If the docs don’t cover something, it says it doesn’t know rather than guess, and gives the reader a box to leave their email. Once they leave it, you’re emailed their address and question, unless you’re already watching the dashboard, and the reply you type there lands in their chat. The free plan has 50 answers a month, and needs no card and has no end date.

The plugin is @heydeacon/docusaurus-plugin on npm, MIT licensed, with its source on GitHub. It’s for Docusaurus 3, which was at 3.10.2 when we read its documentation on 25 October 2026. Coding agents can fetch this page as Markdown.

Before you install

The plugin needs a key, so sign up first and give Deacon your docs’ address. The key is the pk_ value of data-key in the snippet on Deacon’s Install page. That address is already on Install’s list of domains, with its subdomains, which matters because the chat only shows on a listed domain. If the docs also publish to owner.github.io, add that too. The plugin is the only thing to install, and the questions at the end show a way without it.

Would rather hand it over? Install’s Copy the prompt (under My own code, if Install asks what the site runs on) gives Claude Code, Cursor or Codex the tag with your key in it, and the agent adds the code and checks it’s live.

Install the plugin

Add the package with whichever manager your Docusaurus project uses, so you don’t end up with a second lockfile.

npm install @heydeacon/docusaurus-plugin
# or
yarn add @heydeacon/docusaurus-plugin
# or
pnpm add @heydeacon/docusaurus-plugin

Then list it under plugins in docusaurus.config.js, or the .ts version. Keep the rest of your config as it is. The new part is the plugins line, or one entry in it if you already have plugins.

// docusaurus.config.js
export default {
  // ...the rest of your config
  plugins: [['@heydeacon/docusaurus-plugin', { key: 'pk_your_widget_key' }]],
};

The pair of name and options is how Docusaurus’s guide to using plugins passes settings to a plugin. A missing key, or an option of the wrong type, stops the build with a message saying why.

What ends up in your HTML

On every page Docusaurus builds, the plugin adds one tag through the injectHtmlTags hook, as a post-body tag. Docusaurus’s lifecycle API docs say those go “before the closing </body> tag after all child elements”. Without options, it’s exactly the tag Install hands out.

<script src="https://heydeacon.com/widget/v1/loader.js" data-key="pk_your_widget_key" async></script>

The async keeps it from holding up your docs, and on the published site the same script counts visits and their sources on Analytics › Website.

Check the dev server, then the build

Docusaurus gives you two local servers, and both run on port 3000, so one entry on Install’s list covers them.

1. Run npm run start and open http://localhost:3000. The first time, no chat button appears, because localhost isn’t on the list. Deacon’s Install page, opened from the top of the dashboard, then says “Found the code on localhost:3000”. Add it with one click.
2. Reload a docs page. The button appears in the corner, labelled Help unless you changed it in Appearance.
3. Ask something one of your pages answers. Questions on localhost are free and never count towards your plan.
4. Run npm run build, then npm run serve, which Docusaurus’s deployment guide says loads the built site at http://localhost:3000/. The button should be there too, since this is the HTML you’ll deploy.
5. Deploy. Install shows your docs’ domain as Live, with when Deacon was last seen there.

A coding agent can check without a browser, by asking Deacon what it has seen. latest names the address that last loaded Deacon, and refused a development address it turned away, as Deacon’s install guide explains.

curl -s "https://heydeacon.com/api/widget/seen?k=pk_your_widget_key"

Plugin options

Only the key is required.

// docusaurus.config.js, the plugins entry with options
plugins: [
  [
    '@heydeacon/docusaurus-plugin',
    {
      key: 'pk_your_widget_key',
      context: { product: 'api', docsVersion: '3.2' },
      pageViews: false,
    },
  ],
],

Deacon brings its own chat button. To open the chat from a link in your navbar or a page instead, hide that button in Appearance and call window.Deacon.open().

Teaching Deacon every page of your docs

Signing up reads your home page and a few main pages, and a docs site usually has many more. Your Docusaurus content is already Markdown in the repository, so upload the .md files on the Knowledge Sources page, up to 10 MB each. Deacon answers from each one once it has read it, and uploads don’t spend the month’s pages from your website. .mdx files aren’t accepted, so save those as .md first.

A paid plan can crawl the published site instead, up to 100 pages a crawl. For a translated site, Docusaurus’s SEO guide says it adds hreflang alternate links, and Deacon’s crawl skips the translation folders they point to. Old versions live in folders of their own, such as /docs/2.x/, as Docusaurus’s versioning guide shows, so leave those out if readers should only hear about the current one. Free holds about 67 pages of docs and Starter about 1,000, and the pricing page has the rest.

What readers get, and what you learn

Readers stop searching and ask. Deacon finds the passage that answers them and usually links the page it came from. Every question your docs couldn’t answer waits in the dashboard with an Answer this button, and what you write goes into your help document, which Deacon answers from straight away.

That list is also your docs’ to-do list. Topics groups what readers ask and counts how many people asked each thing, so the page you need to write next is the one at the top. Every feature is on every plan, the free one included.

Docusaurus questions

No chat button on my docs. What’s wrong?

Open the browser console on that page and look for a line starting [Deacon]. “Unknown widget key” means the key in your config isn’t the one on Install. “isn’t in your allowed domains” means the address you’re on, perhaps a Netlify or Vercel preview, needs adding on Install. “could not start” ends with the error that stopped it. With no [Deacon] line at all, check the built HTML for loader.js. If it isn’t there, the plugin isn’t in the config you built from, and if it is, see whether the button is hidden in Appearance. A button that shows but opens onto a blank chat, with a console line saying the chat frame “did not load”, means a Content Security Policy without https://heydeacon.com in its frame-src.

Can I add Deacon without installing a package?

Yes. Docusaurus’s own scripts option puts a tag in every page’s <head>, and Deacon’s script works there as well as at the end of the body. The reference says “any other attributes are permitted”, which covers data-key, and suggests async because these tags are otherwise render-blocking.

// docusaurus.config.js
export default {
  // ...the rest of your config
  scripts: [
    {
      src: 'https://heydeacon.com/widget/v1/loader.js',
      'data-key': 'pk_your_widget_key',
      async: true,
    },
  ],
};

You lose the plugin’s check on the key at build time, and its context and pageViews options.

Does the plugin work with Docusaurus 2?

It’s built for Docusaurus 3, and its package lists @docusaurus/core 3 as a peer dependency.

My docs are on GitHub Pages. Anything different?

Only the address. Add owner.github.io, or your custom domain, on Install. Adding an AI chatbot to a GitHub Pages site covers publishing there.