Install guide
Installing a chat assistant on an Eleventy site
Eleventy lets every page choose its own template language, so the one certainty in the project is the base layout that the rest chain up to. Put the tag there as literal markup, because the moment it travels through a variable the template language gets to decide whether to escape it.
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 Eleventy
The base layout in your includes directory, for example _includes/base.njk, immediately before the closing body tag.
Any Eleventy site, in any of the template languages it supports. If the includes directory has been moved with the dir.includes setting in your configuration file, look there rather than at _includes.
Step by step
- 1Open your configuration file and check dir.includes. It is _includes unless you changed it, and the base layout lives inside.
- 2Open the base layout that your other layouts and pages name in their layout front matter key. Follow the chain up until you reach the file containing the html and body elements.
- 3Paste the tag on its own line immediately before the closing body tag, written out in full as markup.
- 4Do not build it from a variable or a data file value. Several of the template languages Eleventy supports escape interpolated output by default, so the tag arrives as visible text and the fix then differs per language.
- 5Leave the passthrough copy configuration alone. There is no local file involved, because the loader is served from its own address.
- 6Run the development server, confirm the tag is in the source, then build and deploy. Allowlist both origins so the local check is worth something.
What goes wrong on Eleventy
Escaping depends on which language that layout happens to be in
An Eleventy project can hold layouts in several template languages at once, and they do not agree about escaping. Output interpolated into a template is commonly escaped by default, so a tag stored in a data file and printed into the layout lands on the page as text.
Written as literal markup it behaves identically in every language Eleventy supports, and nobody has to remember which filter that particular file needs.
Layout chaining means one file may not cover the site
Eleventy layouts chain: a post layout names a base layout, and an individual page can name either one directly. Pasting into the base covers everything that chains up to it and nothing that does not.
The page that goes missing is always the one off, the landing page or the error page with its own layout in the front matter. Search your includes directory for the closing body tag to find every place a document can end.
The development server injects a script of its own
Eleventy's development server serves on a local port and adds a small live reload client to every page it hands out. The page you are reading locally therefore differs from the built output in two ways: an extra script that will not exist in production, and an origin the allowlist has never seen.
Add the local origin if you want to test there, and when you are checking whether the tag actually shipped, read the file in your output directory rather than the served page.
Origins to allowlist
These are the origins a Eleventy site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.
- http://localhost:8080
- https://yourdomain.com
- https://staging.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.
| 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 Eleventy 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 Eleventy that depends on what kind of site this is. These go one level further than this guide.
Taking it off again
Delete the line from the base layout, rebuild, and deploy. Nothing else in the project refers to it and no configuration needs unwinding.
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
- Which file in the includes directory is the base layout?
- Open any page and read its layout front matter key. That names a file in the includes directory. Follow the chain upward until you reach the one containing the html and body elements: that is the base.
- Can I add it through a shortcode instead?
- You can, and it buys nothing but an escaping question. A shortcode that returns markup has to be trusted by each template language separately, which is exactly the problem writing the tag literally avoids.
- Does passthrough copy need an entry for it?
- No. Passthrough copy exists to move local files into the output directory untouched. The loader is not a local file, so there is nothing to copy and nothing to configure.
- Why do only some pages have the launcher?
- Those pages chain to a different layout. The launcher appears on exactly the pages that render through the file you edited, which on a mature Eleventy site is usually most of them but never all.
Keep reading
- Install on Next.jsapp/layout.tsx in the App Router, or pages/_document.tsx in the Pages Router. Not a client component that can unmount.
- Install on Reactindex.html at the project root for a Vite app, or public/index.html for Create React App. Immediately before the closing body tag.
- Install on Vueindex.html at the project root, after the div the app mounts into and immediately before the closing body tag.
- Every install guideThe same one line of HTML, and where it goes on each platform.
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.