Hugo and developer tools company
Versioned documentation on Hugo, where the corpus is whatever the build wrote
The failure that matters on a developer documentation site is an answer drawn from the wrong release, and on a static build the corpus is a build decision more than a crawl decision. Whatever the build wrote into the output directory is public, linked and listed. Archived versions are as reachable as the current one, and nothing in a page from two majors ago says so in a sentence.
Why this pairing is its own job
The Hugo 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.
- Versions here are content directories, and the build writes all of them, complete with a sitemap entry each. A crawl of the built site therefore gets the archived documentation on exactly the same terms as the current documentation, which is the precise shape of the failure the trade page names.
- The install is a commit. The tag lives in a layout template in the repository, so it goes through review and arrives with a deploy, which means the widget's presence is a property of a build rather than of a setting somebody can toggle back.
- Section specific base templates are normal on a documentation site, and the docs section frequently has its own. The launcher can end up present across the marketing pages and absent from the reference, which is the inverse of what you wanted.
- Every pull request on a docs site tends to build to its own hostname. Those are origins, they are not on the allowlist, and a reviewer checking the preview sees nothing rendered.
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 Hugo guide. Everything below is about where it goes on a developer tools company site specifically.
One layout, then check the section that matters actually uses it
Copy the base template out of the theme into your own layouts directory and add the tag there. That much is the platform install. The part specific to a documentation site is verifying afterwards that the reference section renders through that file rather than through its own.
The check is thirty seconds: build, then look at the generated HTML of a reference page and a marketing page and confirm the tag is in both. Reasoning about the lookup order is slower and less reliable than reading the output.
If the docs section has its own base template, add the tag there too, or make both include the same footer partial so there is one line to maintain rather than two that drift.
Decide which built paths the crawl may read
The output directory is the corpus. Archived version directories, unreleased documentation staged in the tree, and any section built for internal use are all in there and all reachable, and they will be read unless something stops them.
The cleanest lever is the build: stop generating versions you no longer support and the question disappears. Where you have to keep them published, keep them out of the generated sitemap and out of the crawl, then confirm it by asking about a method you removed and reading which version the citation points at.
Do that test deliberately rather than assuming. A citation pointing at an archived path is the only observable signal that the corpus still contains it.
Preview builds are separate origins and always will be
A per pull request preview is served from a hostname generated for that build, so it is refused and nothing renders. The console names the origin it rejected, which is the fastest way to tell this apart from a template mistake.
Do not chase it by moving the tag. Either allowlist the preview pattern you actually use, or agree that previews confirm the tag is present in the generated HTML and that the visual check happens on the deployed site.
Where the answerable material lives
| The current release's reference, on its own path prefix | The prefix is what makes exclusion possible later. If supported and archived versions share a path, there is no way to index one and not the other. |
|---|---|
| Migration guides and deprecation notices, with dates | The highest value support material on this kind of site. Every deprecation produces a wave of identical questions from people who did not read the changelog, and the answer is already written. |
| The error and status code reference | Readers paste the error rather than searching a concept. The code, the human explanation and the usual causes, indexed together, is what makes the assistant beat the search box. |
| The changelog the build assembles from dated files | It answers when did this change and was that deliberate, and it gives the assistant a way to distinguish current behaviour from behaviour described in a guide nobody has updated. |
The first thing to get right
Take unsupported version directories out of the build, or out of the sitemap and the crawl, before the first index.
It is the one control that actually enforces the trade's rule, because a page that was never written into the output cannot be reached for on a weak match. A caution setting reduces how often an old page is chosen; not building it removes the possibility.
The failure that belongs to this combination
The preview looked broken, so the tag got moved
A change lands in a pull request, the preview builds to its own hostname, and the reviewer opens it and sees no launcher. The obvious conclusion is that the template edit did not take.
What follows is worse than the original problem. The tag gets moved into a partial that is included somewhere less appropriate, or duplicated into a second template to make it appear, and the change ships. The loader installs once regardless, so the duplicate is dead markup that the next person has to reason about.
The signal that distinguishes the two is in the console on the preview: a refused origin means the tag is present and working correctly. Read that before editing anything, and put the answer in the pull request template so the next reviewer does not repeat it.
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
- How do we stop it answering from documentation for an old release?
- Stop building the releases you do not support, keep the ones you do on distinct paths, and index only those. Then test it: ask about something you removed and read which path the citation points at. That citation is the only observable evidence about what is in the corpus.
- Should the key be committed to the repository?
- It ends up in the page source of every built page either way, so there is nothing to protect by templating it out of the file. What the repository does give you is review: the line is visible in a diff, and its removal is visible too.
- Will it write code examples for our readers?
- It returns the documented example with a citation rather than composing one. On a documentation site that distinction is the whole point, because a composed snippet looks exactly like a copied one and goes straight into an editor.
Keep reading
- Installing on HugoCopy baseof.html out of the theme into your own layouts directory, add the tag there, then rebuild and redeploy the site.
- 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.
- Translated Starlight documentation and the duplicate pages it puts in the corpusUntranslated pages are served in the default language under every locale URL, so one page reaches the index as several near identical documents.
- Documentation you cannot put a launcher on, and two public copies of itThe tag cannot go on a Notion page, so the reader who failed your search box is the one person who cannot reach the assistant.
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.