Skip to Content
Doc platformsMintlify

Mintlify

Add the Knoku widget to a Mintlify site.

Before you start

The widget only works once your project exists and your docs are indexed:

  1. Create a project and add your site’s domain as the allowed domain. See Widget installation.
  2. Connect GitHub repo sync for your docs repository (set Docs directory to your Markdown folder) so answers come from your own content.

Add the widget

Mintlify includes custom JavaScript files from your content directory on every page. Add a small loader file at the same level as docs.json or mint.json:

// knoku.js
const script = document.createElement('script')
script.src = 'https://cdn.knoku.com/widget.js'
script.async = true
script.dataset.projectId = 'YOUR_PROJECT_ID'
document.head.appendChild(script)

Replace YOUR_PROJECT_ID with the Project ID from your dashboard.

Run the Mintlify dev server and confirm knoku.js is included on the page. If your docs live in a monorepo subfolder, put knoku.js in the Mintlify content root, not the repository root.

Widget attributes in JavaScript

For script-tag attributes, set dataset properties in camelCase:

const script = document.createElement('script')
script.src = 'https://cdn.knoku.com/widget.js'
script.async = true
script.dataset.projectId = 'YOUR_PROJECT_ID'
script.dataset.greeting = 'How can I help?'
script.dataset.launcherText = 'Need help?'
script.dataset.primaryColorLight = '#EA580C'
script.dataset.primaryColorDark = '#9A3412'
script.dataset.suggestedQuestions = 'Get started|rocket,API reference|code,Pricing|card'
document.head.appendChild(script)

The browser serializes dataset.primaryColorLight as data-primary-color-light. Full list: Attributes reference. For per-slot visual overrides (data-panel-header-background-color, etc.) see Component Styles.

Add an Ask Docs button to the topbar

The most reliable approach is to add your own button (or React component) with a stable ID and point data-open-selector at it. Mintlify allows custom React components in the topbar.

script.dataset.openSelector = '#ask-docs'
script.dataset.launcherHidden = 'true'

Pair this with a button somewhere in your Mintlify content or layout that carries id="ask-docs". The widget watches the DOM, so it binds the click handler once the element is rendered. See Add an Ask Docs button for the full behavior.

If you do not want to customize the topbar, keep the default floating launcher and skip this section.

Index your docs

Connect the GitHub repository that contains your Markdown. Set Docs directory to the folder your generator uses (often docs/ or src/content). Knoku syncs on each commit and cites files on GitHub. Details: GitHub repo sync.

Alternatively, crawl your deployed site if you do not index from GitHub.

Open the deployed site and ask a question. Then open your Mintlify site and check browser devtools:

  1. knoku.js is loaded by Mintlify.
  2. https://cdn.knoku.com/widget.js is requested.
  3. https://api.knoku.com/api/v1/config/{projectId} returns 200.

If the config request returns 403, add the exact Mintlify domain or custom domain as the project’s allowed domain.

Customize the widget

Last updated on
NextraSphinx