Skip to Content
Doc platformsDocusaurus

Docusaurus

Add the Knoku widget to a Docusaurus 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

Add the script to the top-level scripts field in docusaurus.config.*. Docusaurus injects it on every page.

// docusaurus.config.js
export default {
  // ...
  scripts: [
    {
      src: 'https://cdn.knoku.com/widget.js',
      'data-project-id': 'YOUR_PROJECT_ID',
      async: true,
    },
  ],
}

Restart the dev server after saving.

Widget attributes in scripts

Every data-* attribute from the widget docs goes into the scripts entry as a quoted kebab-case key. Boolean values are passed as strings:

scripts: [
  {
    src: 'https://cdn.knoku.com/widget.js',
    'data-project-id': 'YOUR_PROJECT_ID',
    'data-greeting': 'How can I help?',
    'data-launcher-text': 'Need help?',
    'data-primary-color-light': '#2e8555',
    'data-primary-color-dark': '#25c2a0',
    'data-suggested-questions': 'Get started|rocket,API reference|code,Pricing|card',
    async: true,
  },
],

Same names as the script tag examples in the widget docs, just inside a JS object. 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

Docusaurus renders the navbar with React, so a button has to be a real component, not raw HTML. The idiomatic path is to register a custom navbar item type by swizzling NavbarItem/ComponentTypes.

Create the button component at src/components/AskDocsNavbarItem.jsx:

import React from 'react';
 
export default function AskDocsNavbarItem() {
  return (
    <button
      id="ask-docs"
      type="button"
      className="navbar__item navbar__link"
    >
      Ask Docs
    </button>
  );
}

Register the type at src/theme/NavbarItem/ComponentTypes.js:

import ComponentTypes from '@theme-original/NavbarItem/ComponentTypes';
import AskDocsNavbarItem from '@site/src/components/AskDocsNavbarItem';
 
export default {
  ...ComponentTypes,
  'custom-askDocs': AskDocsNavbarItem,
};

Then add the item to themeConfig.navbar.items and tell the widget script which selector opens it:

// docusaurus.config.js
themeConfig: {
  navbar: {
    items: [
      { type: 'custom-askDocs', position: 'right' },
      // ...
    ],
  },
},
scripts: [
  {
    src: 'https://cdn.knoku.com/widget.js',
    'data-project-id': 'YOUR_PROJECT_ID',
    'data-open-selector': '#ask-docs',
    async: true,
  },
],

The widget watches the DOM, so it binds the click handler once Docusaurus mounts the navbar. To hide the floating launcher and use only this button, add 'data-launcher-hidden': 'true'. See Add an Ask Docs button for the full attribute list.

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 or deploy your Docusaurus site and check that:

  1. the widget script loads once on every docs page
  2. the config request returns 200
  3. answers cite URLs that match your Docusaurus route base path

Customize the widget

Last updated on
OverviewVitePress