The scripts array or a client module?

The scripts array for a static tag like this one, because it is a single entry in a file you already maintain. A client module earns its place only when you need to decide at runtime whether to install, on some paths and not others.

Do I need to swizzle a theme component?

No. Swizzling copies a theme component into your project and makes you responsible for it across every upgrade. Nothing here justifies that, since the configuration key already puts a tag into the document.

What should a documentation site index?

Point the crawl at the published docs and let it follow the sitemap Docusaurus generates. Decide deliberately about old versions: an answer sourced from a superseded version is worse than no answer, so keep those out unless you want them.

Will it fight with the search box already on the page?

No, they are independent and most sites keep both. Search returns pages that match words. The assistant answers the question in a sentence and cites the pages it used, which is what the reader who has already failed at search actually wanted.

Install guide

Installing a chat assistant on Docusaurus docs

Docusaurus has a configuration key for exactly this, which means no swizzling and nothing to redo when you upgrade. The detail that decides whether it works is the shape of the entry: a plain string cannot carry the key, and an object can.

The tag

<script src="https://cdn.askably.xyz/w.js" data-key="pk_live_YOUR_KEY" defer></script>

Your own key replaces the placeholder. You will find it on the install tab of the assistant.

The origin the page is served from has to be on the allowlist for that assistant, or nothing renders and the browser console says which origin was refused. An apex domain and its www are two different origins to a browser, so list both, along with any staging or preview host you want it to work on.

Where it goes on Docusaurus

The scripts array in docusaurus.config.js, at the top level of the exported configuration object.

Any Docusaurus site you build yourself. The scripts array is part of the core configuration, so no plugin is involved and nothing has to be swizzled out of the theme.

Step by step

1Open docusaurus.config.js and find the scripts array at the top level of the config object. Add the array if it is not there yet.
2Add an object entry rather than a string. The string form renders a source attribute and nothing else, so it has nowhere to put the key.
3Give the object the loader source, defer set to true, and the data key as its own property. Properties Docusaurus does not recognise are copied straight onto the rendered script tag, which is how the key reaches the loader.
4If you would rather keep it out of the configuration, a client module does the same job by appending the tag once when the site loads. Take one route or the other, never both.
5Rebuild. The scripts array is read at build time and written into the generated HTML, so a running development server has to be restarted before it picks the change up.
6Deploy, then click between two doc pages and confirm the launcher stays put across the route change.

What goes wrong on Docusaurus

A string entry cannot carry the key

The scripts array accepts either a plain string or an object. The string becomes a script tag with only a source on it, so the key never reaches the page. The loader then logs a warning to the console and renders nothing, which looks like a script that failed to load when in fact it loaded and declined to start.

The object form passes arbitrary properties through to the tag, so the key sits there as its own property alongside defer. Use the object form even for the simplest case.

Navigation after the first load never re-parses the document

A Docusaurus site routes in the browser once it has loaded, so moving between doc pages does not reload anything. That works in your favour here: the loader installs once and the launcher persists across every subsequent page, which keeps a conversation open while the reader carries on browsing.

It also means a configuration change is invisible until you do a full reload. Testing by clicking around after a rebuild will show you the old page for as long as the tab stays open.

The hosting preview address is not the docs domain

A docs site published to a hosting subdomain and later pointed at a custom domain answers on both, and a browser treats them as separate origins. Reviewers who open the hosting address see nothing while the custom domain works perfectly, which turns into a bug report about an intermittent widget.

Allowlist every address the site answers on, including the local development port if that is where you check your work.

Origins to allowlist

These are the origins a Docusaurus site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.

http://localhost:3000
https://your-org.github.io
https://docs.yourdomain.com

How the tag behaves, wherever you put it

The rest of this is the same on every platform, so it is worth reading once rather than on each guide.

Loader behaviour
One tag, nothing else	There is no second file, no stylesheet and no package to install. The tag is the whole install.
Where it goes	Immediately before the closing body tag. It works in the head too, because it defers, but the body keeps it out of the way of anything that measures render order.
data-key is required	Without it the loader stops and writes a warning to the browser console rather than rendering anything.
It finds itself	The loader reads the tag it was loaded from, and falls back to the first tag on the page carrying a data-key. Platforms that move or re-inject the tag do not break it.
It installs once	A second copy of the tag on the same page is ignored, so a template that renders twice does not produce two launchers.
Assets follow the tag	Everything else it needs is fetched from the same origin the tag was served from, so a proxy or a private domain needs no extra configuration.
The panel loads late	Only the small launcher is on the page at first. The conversation panel is fetched the first time a visitor opens it, in its own frame.
Styles cannot collide	The launcher renders inside a closed shadow root and the panel inside a frame, so nothing on the host page can restyle either, and neither can restyle the host page.

Set up on Docusaurus for a particular trade

The tag is the same everywhere. What is not the same is which of your pages the assistant can read once it is running, and on Docusaurus that depends on what kind of site this is. These go one level further than this guide.

Taking it off again

Delete the entry from the scripts array, or delete the client module along with its registration, then rebuild and deploy.

Before you remove it

Removing the tag stops the widget on that site. It does not delete the assistant, its material, or the enquiries it has already collected.
If you are moving the widget to a different host rather than retiring it, add the new origin to the allowlist before you remove the old tag, or there is a window where neither works.

Questions

The scripts array or a client module?: The scripts array for a static tag like this one, because it is a single entry in a file you already maintain. A client module earns its place only when you need to decide at runtime whether to install, on some paths and not others.
Do I need to swizzle a theme component?: No. Swizzling copies a theme component into your project and makes you responsible for it across every upgrade. Nothing here justifies that, since the configuration key already puts a tag into the document.
What should a documentation site index?: Point the crawl at the published docs and let it follow the sitemap Docusaurus generates. Decide deliberately about old versions: an answer sourced from a superseded version is worse than no answer, so keep those out unless you want them.
Will it fight with the search box already on the page?: No, they are independent and most sites keep both. Search returns pages that match words. The assistant answers the question in a sentence and cites the pages it used, which is what the reader who has already failed at search actually wanted.

Keep reading

Try it on your own material

Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.

Start free See what it does