Skip to Content
Doc platformsMkDocs

MkDocs

Add the Knoku widget to a MkDocs 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 the folder your generator uses, often docs/) so answers come from your own content.

Add the widget

MkDocs loads custom JavaScript through extra_javascript. Because widget configuration uses data-* attributes, add a small loader file inside your docs directory.

Create docs/javascripts/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)

Then include it in mkdocs.yml:

extra_javascript:
  - javascripts/knoku.js

If your project sets docs_dir, put the loader under that directory instead of docs/.

Restart mkdocs serve after saving.

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.suggestedQuestions = 'Get started|rocket,API reference|code,Pricing|card'
document.head.appendChild(script)

The browser serializes camelCase dataset keys (e.g. dataset.launcherText) as kebab-case data-* attributes (data-launcher-text). 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 navbar

If you use Material for MkDocs, add a custom partial or theme override for the header button, then bind it with data-open-selector.

Example button markup:

<button id="ask-docs" type="button" class="md-header__button md-icon">
  Ask Docs
</button>

Then update the loader:

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

The widget watches the DOM, so it binds after MkDocs renders the theme. See Add an Ask Docs button for the full behavior.

If you do not want to customize the theme, 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 run mkdocs serve or open the deployed site and check that:

  1. javascripts/knoku.js is loaded
  2. https://cdn.knoku.com/widget.js is requested
  3. the widget config request returns 200
  4. answers cite URLs with MkDocs trailing slashes

If the config request returns 403, add the exact production host as the project’s allowed domain. For local mkdocs serve, add the exact origin you use (for example http://127.0.0.1:8000 or http://localhost:8000) to the allowlist — not just any production host.

Customize the widget

Last updated on
VitePressNextra