Sphinx

Add the Knoku widget to a Sphinx documentation site.

Before you start

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

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

Sphinx loads custom JavaScript through html_js_files. Put a small loader file under your Sphinx static directory.

Create _static/knoku.js next to conf.py:


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 update conf.py:


html_static_path = ['_static']
html_js_files = [
    'knoku.js',
]

If your project uses docs/source/conf.py, create docs/source/_static/knoku.js and update that conf.py.

Restart your Sphinx dev server or rebuild the HTML output after saving.

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.

Sphinx themes differ, so the safest option is to add a small button through your theme template override and bind it with data-open-selector.

Example markup:


<button id="ask-docs" type="button">Ask Docs</button>

Then update _static/knoku.js:


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

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

If you do not want to override templates, 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 build or serve your Sphinx site and check that:

_static/knoku.js is loaded
https://cdn.knoku.com/widget.js is requested
the widget config request returns 200
answers cite .html URLs that exist in your built docs

If the config request returns 403, add the exact docs host as the project’s allowed domain.

Sphinx

Before you start

Add the widget

Widget attributes in JavaScript

Add an Ask Docs button to the navbar

Index your docs

Customize the widget