Mintlify includes every .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. The same file works whether Mintlify runs on their cloud or self-hosted in your own cluster: it is the same build either way. Custom JS is a Pro or Enterprise feature — on the Starter plan the file ships and never runs, which looks exactly like a broken install.
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.
2

Add the widget snippet

Because the widget reads its configuration from the data-* attributes on its own <script> element, the file creates that tag rather than declaring one.
beforequery-widget.js
Your knowledge base ID and public client key (bq_pk_...) are in the dashboard under Knowledge Base → Integration. Add your docs domain to the key’s origin allowlist.
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.
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 — where a reader who has just failed to find something is already looking:
Both ids: Mintlify renders its desktop search pill and its mobile search icon as separate elements, each hidden at the other’s breakpoint, so anchoring only the first would leave phones with no way into the widget.
Custom JavaScript cannot be scoped to specific pages — every .js file in the content directory runs on all of them, in no guaranteed order. If you keep a second file that also mounts the widget, guard both so only one tag is created, or you get two launchers:
For all widget options see Widget configuration, and Mintlify’s own Custom scripts. Running behind a firewall? Pointing the widget at a self-hosted API is data-base-url, the origin allowlist is covered in Security, and docs our crawler cannot reach are indexed with a git source.