Skip to Content
Doc platformsNextra

Nextra

Add the Knoku widget to a Nextra 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 with App Router

For Nextra v4 and App Router projects, add the script to the root layout with next/script.

// app/layout.tsx or src/app/layout.tsx
import Script from 'next/script'
 
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        {children}
        <Script
          src="https://cdn.knoku.com/widget.js"
          data-project-id="YOUR_PROJECT_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  )
}

If your layout renders the Nextra <Layout> component, keep that unchanged and place <Script /> once inside <body>.

Add the widget with Pages Router

For older Nextra projects using pages/, add the script in _app.tsx or _app.jsx:

// pages/_app.tsx or src/pages/_app.tsx
import Script from 'next/script'
import type { AppProps } from 'next/app'
 
export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://cdn.knoku.com/widget.js"
        data-project-id="YOUR_PROJECT_ID"
        strategy="afterInteractive"
      />
    </>
  )
}

Widget attributes in JSX

Most widget options can be passed as normal data-* props:

<Script
  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-suggested-questions="Get started|rocket,API reference|code,Pricing|card"
  strategy="afterInteractive"
/>

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

Nextra renders the navbar from your root layout configuration. Add a button to the navbar area and point the widget at it with data-open-selector.

One simple option is to add your own button near the layout and style it with your existing classes:

<button id="ask-docs" type="button">
  Ask Docs
</button>
 
<Script
  src="https://cdn.knoku.com/widget.js"
  data-project-id="YOUR_PROJECT_ID"
  data-open-selector="#ask-docs"
  data-launcher-hidden="true"
  strategy="afterInteractive"
/>

For a fully integrated navbar item, render the same button through your Nextra Navbar / layout configuration. The important part is that the element has a stable selector. The widget watches the DOM, so it binds after Nextra hydrates.

See Add an Ask Docs button for custom trigger behavior.

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 Nextra site and check that:

  1. the widget script loads once on every docs page
  2. the config request returns 200
  3. answers include source links that match your Nextra routes

If the widget does not appear, see the Widget installation troubleshooting checklist.

Customize the widget

Last updated on
MkDocsMintlify