Install guide
Adding a chat assistant to Starlight documentation
Starlight owns the shell of every documentation page, so you do not edit a layout here. The supported route is the head option on the integration itself, which takes an object with a tag name and an attributes map. A component override is the fallback, and it costs more than it looks.
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 Starlight
The head array passed to the starlight integration in astro.config.mjs, not the top level of the Astro configuration object.
Any Starlight site. The head option is part of the integration's own configuration, so nothing has to be overridden and nothing has to be ejected out of the theme.
Step by step
- 1Open astro.config.mjs and find the call to the starlight integration inside the integrations array.
- 2Add a head array to the options object you pass to starlight, if it is not there already.
- 3Add one entry shaped as an object with a tag property and an attrs property. Set tag to script.
- 4Inside attrs, set src to the loader address, set the data key attribute to your publishable key, and set defer. The attrs map accepts a boolean here, so defer set to true prints correctly as a bare attribute.
- 5Do not paste a plain script element into a documentation page instead. Astro treats script elements in your own source as modules to process, so the attributes do not survive to the page. The head option hands the tag to Starlight already formed, which is why it is the route that works.
- 6Run the development server, open a docs page, and confirm the launcher appears. Then build and deploy, and confirm it on the published site as well.
What goes wrong on Starlight
Frontmatter head is one page, integration head is the site
A Starlight page can declare its own head entries in frontmatter, using the same object shape. It is a genuinely useful feature and a very easy thing to reach for while testing, because it puts the tag on the page you happen to be looking at without touching the build configuration.
The result is a widget on one documentation page and nowhere else, which reads as a broken deploy rather than as a misplaced entry. If the launcher appears on exactly one URL, open that page's frontmatter before you look at anything else.
A component override makes you the maintainer of that component
Starlight accepts a components map that swaps one of its own components for yours. It is the documented escape hatch, and it is the wrong tool for a script tag, because from that point on every Starlight upgrade that changes the component you replaced is a change you have to reconcile by hand.
The head option carries no such cost, since it adds to Starlight's markup rather than replacing any of it. Keep overrides for things that genuinely need different markup.
Plain Astro pages in the same project are outside Starlight
It is common to run a Starlight docs section alongside hand written Astro pages for a home page, a pricing page or a changelog. Those pages use your own layout, not Starlight's, and the head option never touches them.
So the widget covers the documentation and stops at the marketing pages, or the reverse if you installed in your layout first. Decide whether you want one assistant across both, and if so add the tag in both places. The loader ignores a second install on the same page, so an overlap is harmless.
Origins to allowlist
These are the origins a Starlight site is typically served from. List every one you want the assistant to answer on, including the ones only you visit.
- http://localhost:4321
- https://docs.yourdomain.com
- https://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 Starlight 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 Starlight 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 head array in the integration options, then rebuild. If somebody also added it to a page's frontmatter, remove that too.
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
- Does the head option cover the search page and the 404 page?
- It covers every route Starlight builds, which includes the pages it generates for you as well as your own documentation pages. Routes built by your own Astro pages are separate and need the tag in their own layout.
- Can I put the entry in the Astro configuration instead of the integration options?
- No. The head option belongs to Starlight, so it goes in the object you pass to the integration. An entry placed at the top level of the Astro configuration is not read by Starlight and the tag never reaches the page.
- Do I need a client directive on it?
- No. Client directives apply to components that hydrate in the browser. This is a script tag placed in the document head, and defer is the only behaviour it needs.
- What should the assistant read on a Starlight site?
- The published documentation, crawled from the sitemap Starlight generates. If you keep several versions of the docs online, decide deliberately which ones the crawl may read, because an answer taken from a superseded version is worse than no answer.
Keep reading
- Install on DocusaurusThe scripts array in docusaurus.config.js, at the top level of the exported configuration object.
- Install on MkDocsAn overrides directory named by custom_dir under the theme key in mkdocs.yml, holding a main.html that extends the theme's base template.
- Install on Zendesk GuideGuide admin, then Customize design, then Edit code on your live theme, then footer.hbs.
- 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.