Can I skip the override and paste the tag into a page?

You can put raw markup in a page if your Markdown configuration allows it, but the widget then exists on that page alone. The override puts the tag in the template every page is built from, which is what you actually want.

Does an override survive a theme upgrade?

The directory does, because it is yours. What can break is the block name, if a major version renames or removes it. If the launcher disappears after an upgrade, open the new base template and check the block still exists before looking anywhere else.

What if my theme has no suitable block?

Copy the theme's base template into the overrides directory under the same name and edit it directly. That works, but you now own a copy of a file the theme will keep changing, so treat it as the last resort it is.

Should I change extra_javascript at all?

No, leave it alone. It stays useful for scripts you genuinely ship with the site, and mixing the two only leaves the next maintainer guessing which one is doing the work.

Install guide

Installing a chat assistant on an MkDocs site

MkDocs looks like it has an obvious key for this, and the obvious key is the wrong one. extra_javascript expects files living under your docs directory and copies them into the build, so it can neither point cleanly at another host nor attach the key the loader needs. Theme overrides are the supported route and take about five minutes.

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 MkDocs

An overrides directory named by custom_dir under the theme key in mkdocs.yml, holding a main.html that extends the theme's base template.

Any MkDocs site whose theme exposes named blocks in its base template, which covers the bundled themes and the widely used third party ones. A theme with no block at the end of the body forces you to override the whole base template instead, and then to maintain it.

Step by step

1Create a directory beside mkdocs.yml, conventionally named overrides. It has to sit outside your docs directory, because everything inside docs is treated as content and copied into the build.
2In mkdocs.yml, under the theme key, add custom_dir pointing at that directory. This path resolves from the location of mkdocs.yml, not from the docs directory.
3Create main.html inside the overrides directory, and make its first line extend the theme's base template.
4Override the block your theme uses for scripts at the end of the body. Call the parent block first so the theme's own scripts survive, then put the tag underneath it.
5Build again. Overrides are read at build time, and a running development server needs a restart before it picks the new template up.
6Deploy the built output, load a page, and confirm the launcher appears.

What goes wrong on MkDocs

extra_javascript is for your own files, not for another host

That key takes paths resolved inside your docs directory, copies the matching files into the build, and writes a bare script tag for each one. There is nowhere in it to put an attribute, so the key cannot travel alongside the source however you write the entry.

What you get is a tag with no key, a warning in the console, and no widget. The block override route exists for exactly this case and is the only one that produces the tag the loader needs.

custom_dir resolves from the configuration file

Paths under the theme key resolve from the directory holding mkdocs.yml, while most other paths in that file resolve from the docs directory. Setting custom_dir to a path inside docs because that felt consistent gives you a directory MkDocs will not find as an override, and whose contents get published as site content instead.

Keep the overrides directory beside mkdocs.yml and point custom_dir at it with a plain relative name.

The block name belongs to your theme, not to MkDocs

Base templates differ in what they call the block at the end of the body. Extending a block name your theme does not define is not an error: the block is simply never rendered, so the build succeeds, the site publishes, and the tag appears nowhere in the source.

Open your theme's base template, find the block that wraps the scripts at the end of the body, and use that exact name. This is also the thing to recheck after a major theme upgrade.

Origins to allowlist

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

http://127.0.0.1:8000
https://docs.yourdomain.com
https://your-team.github.io

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 MkDocs 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 MkDocs that depends on what kind of site this is. These go one level further than this guide.

For a developer tools companyEvery release is deployed as its own static copy. Older ones were built before you added the override, so they carry no tag and cannot get one.

Taking it off again

Delete the block from main.html, or delete main.html entirely and remove the custom_dir line if the override existed only for this. 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

Can I skip the override and paste the tag into a page?: You can put raw markup in a page if your Markdown configuration allows it, but the widget then exists on that page alone. The override puts the tag in the template every page is built from, which is what you actually want.
Does an override survive a theme upgrade?: The directory does, because it is yours. What can break is the block name, if a major version renames or removes it. If the launcher disappears after an upgrade, open the new base template and check the block still exists before looking anywhere else.
What if my theme has no suitable block?: Copy the theme's base template into the overrides directory under the same name and edit it directly. That works, but you now own a copy of a file the theme will keep changing, so treat it as the last resort it is.
Should I change extra_javascript at all?: No, leave it alone. It stays useful for scripts you genuinely ship with the site, and mixing the two only leaves the next maintainer guessing which one is doing the work.

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