.js file in your content directory on each page of your site. That is the supported way to add a third-party script — docs.json has no "scripts" field, so there is nowhere in the config to declare a <script> tag.
Because the widget reads its configuration from the data-* attributes on its own <script> element, the file creates that tag rather than declaring one.
1
Create a JavaScript file
In your content directory — the folder that holds
docs.json — create beforequery-widget.js. Mintlify picks up every .js file it finds there, so the name is yours to choose; this one matches the bundle it loads, which is what makes it recognisable next to your other root scripts.2
Add the widget snippet
beforequery-widget.js
kb_xxx and bq_pk_... with your actual values.3
Preview locally
Run
mint dev and open a page. The launcher should appear in the bottom corner. (The CLI is mint; mintlify dev was the pre-4.0 command.)4
Commit and push
Mintlify rebuilds the site on push, and the file ships with it. Custom JavaScript runs after the page becomes interactive, so the launcher mounts a moment after the content paints.
Match Mintlify’s theme toggle — the widget follows the operating system’s dark mode by default, which leaves a white panel over docs a reader has switched to dark. Mintlify puts
class="dark" on <html>, so point the widget at that instead:Put the button beside the search bar — the topbar is where a reader who has just failed to find something is already looking, and it costs one attribute:Both ids, because Mintlify renders its desktop search pill and its mobile search icon as separate elements — both always in the DOM, each hidden at the other’s breakpoint. Anchoring only the first would leave phones with no way into the widget. The widget mounts a button beside each, and keeps watching for them, since Mint re-renders the header on every client-side navigation.
Get your keys — your knowledge base ID and public client key (
bq_pk_...) are in the BeforeQuery dashboard under Knowledge Base → Integration. Add your Mintlify docs domain (e.g. docs.yourproduct.com) to the key’s origin allowlist.