MkDocs and developer tools company
What happens to the assistant when each release is its own MkDocs build
MkDocs has no idea that versions exist. Teams that need them solve it by building the site once per release and deploying each build into its own directory or its own subdomain, which works well and produces a consequence nobody plans for: several complete, independent copies of your documentation, each with its own pages, its own sitemap and its own search index, and only the ones built recently carrying the tag at all.
Why this pairing is its own job
The MkDocs install guide covers the tag, and the developer tools company guide covers what the assistant has to know. What follows is the part that belongs to neither.
- Each deployed release is a whole site rather than a subsection of one. Nothing links them except a dropdown added by whatever tool did the deploying, so a crawl treats them as unrelated bodies of material because that is what they are.
- The tag arrives through a build time template override. A directory built last year was built before that file existed, so it has no tag, and giving it one means checking out that release and rebuilding it with whatever toolchain it needed then.
- The current release is usually served at two addresses at once, its own version path and an alias, so the same page is reachable at two URLs and gets read twice.
- Developers pin links. Old issue threads, internal wikis and answers elsewhere point at a specific version path, which means a meaningful share of your documentation traffic lands on exactly the copies that have no widget on them.
What changes about the install here
<script src="https://cdn.askably.xyz/w.js" data-key="pk_live_YOUR_KEY" defer></script>The tag is the same one on the MkDocs guide. Everything below is about where it goes on a developer tools company site specifically.
The override travels with the source, not with the published site
You add the overrides directory and the template on a branch, and only builds made from that branch afterwards contain the tag. Publishing does not reach backwards into directories already sitting on the host.
So the install completes, the current docs show a launcher, and every archived path stays exactly as it was. This is not a caching problem and waiting will not fix it.
Decide deliberately whether old releases get the widget
Rebuilding an archived release means checking out a tag from months or years ago and running a build with the dependencies it wanted at the time. On a project that has moved on, that is real work for a copy of the docs you are trying to persuade people to leave.
The defensible answer for most teams is that they do not get it. Say so out loud rather than leaving it as an unnoticed gap, because otherwise somebody will eventually report the widget as broken from an address where it was never installed.
If you do want coverage there, the cheaper route is usually a redirect from the archived path to the current one for pages that still exist, which moves the reader to the copy you maintain instead of putting an assistant next to material you no longer stand behind.
One release, two addresses
The alias that serves the current release alongside its own version path means the browser can arrive on either. Both are on the same host in the usual setup, so the allowlist is unaffected, but the crawl is not: the same page under two paths becomes two documents saying identical things.
Pick one of the two to index and exclude the other. Which one hardly matters. Indexing both means every answer has a near duplicate competing with it, and the citations start pointing at whichever copy happened to win.
Where the answerable material lives
| The build for the release you support | One directory, crawled from its own sitemap rather than from the host root. Crawling the root walks into every archived directory underneath it, which is the most common way this corpus goes wrong on day one. |
|---|---|
| The archived builds, and the decision to leave them out | They are complete and they are stale in the specific way that hurts on a developer site: old error strings, removed flags, configuration keys that were renamed. Those are the exact phrases people paste, so archived copies match strongly and answer wrongly. |
| The search index each build ships, which is not answerable material | The bundled search plugin writes a JSON index into every build. It is a keyword index for the search box on that page, not a source, and pointing anything at it gets you fragments without the surrounding prose. Index the published pages, the way a reader reads them. |
| Release notes, which usually live outside the docs build entirely | On most projects using this generator the notes are on the code host rather than in the docs tree, which means they are a separate origin and a separate crawl target. They answer when did this change and what replaced it, so leaving them out removes the material that resolves most version confusion. |
The first thing to get right
Point the crawl at the sitemap of one release directory rather than at the site root, and confirm no archived path appears in any citation.
The root walk is silent when it goes wrong. Nothing errors, the corpus simply contains four years of documentation with no way to prefer the current copy, and you find out through an answer that quotes a flag removed in a release nobody is running.
The failure that belongs to this combination
The version everybody links to is the one with no tag on it
Traffic to a documentation site is not evenly spread across its published copies. It concentrates on whichever version path was current when the popular links were written, which is frequently not the one you are maintaining now.
So the install is verified on the current docs, the launcher is there, everything looks finished, and a large share of arriving readers land on an archived directory with no widget in it. There is no error and nothing in a console, because the tag was never in that HTML to begin with.
Check this by opening two or three of the archived paths yourself and viewing source. Then decide: redirect those paths to the current release, rebuild them, or accept the gap knowingly. All three are reasonable. Not knowing which one you chose is not.
Before you go live
- 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.
- Open the site as a visitor would, on the pages a developer tools company visitor actually lands on, and ask it something only your own material could answer. A widget that renders is not the same as a widget that has read anything.
Questions
- Can I add the tag to an already deployed old version without rebuilding?
- Only by editing the published HTML files on the host by hand, which means editing every page in that directory and redoing it if anybody ever republishes. It is not worth it. Either rebuild that release properly or redirect the path to the release you maintain.
- Should each release have its own key?
- If you want any of them answering at all, yes, because a key belongs to one assistant with one body of material. Separate keys keep an archived assistant reading archived docs and the current one reading current docs, which is the only arrangement where a citation means what the reader assumes it means.
- Does the theme override survive when we cut the next release?
- It does, because it is in your source tree and the release is cut from that tree. What can break is the block name if you upgrade the theme at the same time, and a missing block is silent: the build succeeds and the tag simply is not in the output. Check the page source after a theme upgrade rather than assuming.
Keep reading
- Installing on MkDocsextra_javascript takes paths inside your docs directory, so set custom_dir, extend the base template, and put the tag in the scripts block.
- Everything for a developer tools companyOn a docs site an assistant competes with search, not a phone line. Version skew, deprecations and error strings decide whether it earns its place.
- The forum is not your documentation and must not be read as itThe threads are written by your users, not by you. What to index when the documentation and the forum sit on two origins.
- Indexing a versioned Docusaurus site without answering from the wrong releaseVersioned docs put several releases on separate paths. Which of them the crawl reads decides whether an answer is safe or an afternoon lost.
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.