How to Add AI Chat to Docusaurus Documentation

Docusaurus runs more open source and product documentation than any other framework in its class. Meta built it, the community adopted it, and today it sits under docs for everything from infrastructure tools to developer SaaS products. If your docs are on Docusaurus, adding AI chat to them should feel like dropping a script tag, not rebuilding your site.

This guide walks through the short version: what the pieces are, how to wire them up, and what to check before you let real visitors hit the widget.

What you are adding, in one paragraph

An AI chat widget on Docusaurus is a small floating button that opens a chat panel. The panel accepts questions in natural language, reads content indexed from your docs folder, and writes replies with citations back to the exact pages and sections. The widget is a separate surface from the built-in Docusaurus search. They do not compete. Most visitors use search for page lookups and chat for questions they cannot phrase as keywords.

The pieces:

• A content indexer that reads your docs/ folder
• A hosted service that handles retrieval and the language model call
• A small JavaScript widget that renders the chat panel in your site

If the tool you pick requires you to run the retrieval service yourself, it is a project, not a feature. This post assumes a hosted tool with a CLI for pushing content and a script tag for the widget.

Step 1: Pick a tool that understands Markdown

Docusaurus docs live as Markdown (with MDX extensions) in a docs/ folder. The tool you choose needs to read that folder natively, respect frontmatter, handle MDX components, and chunk content by heading.

What to check before committing to a tool:

• Does it parse MDX or only plain Markdown? If your pages use <Tabs> or custom components, a plain Markdown parser will miss half the content.
• Does it respect the docs sidebar order when displaying citations? Your visitors know your docs by structure, not by filename.
• Does it exclude draft frontmatter automatically? Pages marked draft: true should never be indexed.
• Does it handle versioned docs? If you publish /docs, /docs/1.x, and /docs/2.x, the tool should index them separately.

A tool that fails any of these will produce answers that look right and are subtly wrong. Wrong is worse than missing.

Knoku parses MDX, respects sidebar order, skips drafts by default, and handles versioned docs through separate projects. Start free to see whether the parser handles your docs without custom config.

Step 2: Index your docs folder

Most hosted AI chat tools provide a CLI that reads a local directory and pushes the content. On a Docusaurus project the shape is usually something like:

npx @your-tool/cli init
npx @your-tool/cli push ./docs

The first command connects the project to your account and writes a config. The second reads every .md and .mdx file, chunks them by heading, and uploads the chunks to the index.

A few things to verify in the CLI output:

• The number of pages indexed matches the number of pages in your docs folder
• Nothing important is in the skipped list
• The total chunks is roughly three to ten per page (pages split by headings)
• Re-running the push only uploads changed content, not the whole docs set

If the CLI uploads every page every time, that is a sign of a weak change detector. It works but it wastes API calls and slows down CI.

Add the push command to your existing docs deploy pipeline. A GitHub Action step after the build works well. Every merge to main re-indexes the docs so the chat is always answering from the latest version.

Step 3: Add the widget to your Docusaurus theme

Docusaurus exposes a config for injecting scripts through docusaurus.config.js. The scripts array drops a tag into the site head on every page.

// docusaurus.config.js
module.exports = {
  // ...existing config
  scripts: [
    {
      src: "https://cdn.your-tool.com/widget.js",
      async: true,
      "data-project": "your-project-id",
    },
  ],
};

A few practical notes:

• Use async: true so the widget never blocks the first paint of your docs pages.
• Pass config through data- attributes rather than a separate inline script. Easier to debug, easier to version.
• If your tool uses Shadow DOM for the widget UI, you do not need to worry about style collisions with Docusaurus's Infima CSS. The widget lives in its own encapsulated tree.

Run the site locally (npm run start) and check the widget shows up on every page, renders in the right position, and does not override any Docusaurus keyboard shortcuts.

Step 4: Test against your top ten questions

Before announcing the widget, take the ten questions your support team or community most often answers and ask each of them to the widget.

Score each on:

• Correct. The answer reflects what the docs actually say.
• Cited. The answer links to a real page and section.
• Concise. The answer does not drown the visitor in two paragraphs when one line would do.

If eight or more of ten pass all three, the setup is production ready. If fewer, check the logs. Usually one of three things is happening: the tool skipped some pages, the retrieval is tuned for shorter content, or the docs themselves do not cover the question.

The last case is the most valuable. A question that the docs cannot answer is a page the docs should have. Add it, re-index, ask again.

Step 5: Watch the query log for a week

Once the widget goes live, the single most valuable thing you can do is read the query log daily for the first week and weekly after that.

What to look for:

• Questions that repeat across many visitors
• Questions where the tool returned "I could not find this in the docs"
• Answers where the visitor clicked through to a citation (a strong positive signal)
• Answers that a visitor explicitly flagged as wrong

Every unanswered question is a docs page worth writing. Every flagged answer is either a retrieval bug or an ambiguous docs page. Both feed directly into the docs roadmap.

The teams that treat the log as instrumentation (not noise) end up with better docs and fewer tickets within a month. The teams that install the widget and ignore the log end up roughly where they started.

If you want to try all five steps on your own Docusaurus project, start free on Knoku. The CLI handles MDX, Docusaurus versioning, and sidebar-aware citations. Free tier covers the first 50 messages, enough to validate the top ten question list. Pricing scales from there.