Przejdź do głównej treści
ChattyBoxZacznij bezpłatnie

Chatbot AI z cytowaniami dla Docusaurus 3

· 4 minuty czytania
Michael Fisher
Michael Fisher
ChattyBox maintainer and technical writer

Po pierwszym załadowaniu strony Docusaurus zachowuje się jak aplikacja jednostronicowa. Integracja widgetu, która działa tylko w początkowym dokumencie albo dołącza drugi loader przy każdej zmianie trasy, nie jest gotowa do użycia produkcyjnego. Ten przewodnik wykorzystuje stabilną identyfikację skryptu oraz główny komponent motywu, który pozostaje zamontowany na wszystkich trasach dokumentacji.

Autor i recenzent techniczny: Michael Fisher, opiekun ChattyBox. Opublikowano i sprawdzono technicznie 10 lipca 2026 r. Poniższe powtarzalne testy są samouczkiem implementacyjnym, a nie testem porównawczym wydajności ani dokładności.

1. Dodaj główny komponent motywu Root​

Utwórz src/theme/Root.tsx w swojej witrynie Docusaurus:

import React, { useEffect, type ReactNode } from 'react';

const WIDGET_ID = 'chattybox-widget';

export default function Root({ children }: { children: ReactNode }) {
  useEffect(() => {
    if (document.getElementById(WIDGET_ID)) return;

    const script = document.createElement('script');
    script.id = WIDGET_ID;
    script.src = 'https://chattybox.ai/widget.js';
    script.async = true;
    script.dataset.apiKey = 'YOUR_API_KEY';
    script.dataset.apiUrl = 'YOUR_CHAT_API_URL';
    script.dataset.chattyboxWidget = 'true';
    document.body.appendChild(script);
  }, []);

  return <>{children}</>;
}

Stały identyfikator chattybox-widget zabezpiecza to konkretne wstawienie przed ponownym montowaniem w trybie deweloperskim React oraz zmianami tras po stronie klienta. Nie wykrywa jednak osobnego loadera z innym identyfikatorem lub bez niego; używaj tylko jednej integracji na stronie.

Użyj adresu URL API wyświetlanego przez projekt ChattyBox, zamiast kopiować przykładowe wdrożenie. Zobacz dokumentację instalacji widgetu zawierającą aktualne atrybuty oraz przewodnik produktowy Docusaurus dotyczący wyboru źródeł i ewaluacji.

2. Pozostaw loader zamontowany​

Nie umieszczaj tego skryptu na pojedynczej stronie dokumentacji ani w układzie, który Docusaurus zastępuje podczas nawigacji. Zmodyfikowany komponent Root opakowuje aplikację przez cały czas jej działania, dzięki czemu widget pozostaje dostępny, gdy odwiedzający przechodzą między przewodnikami a materiałami referencyjnymi.

Jeśli Twoja witryna ma już src/theme/Root.tsx, połącz efekt z istniejącym komponentem zamiast zastępować uwierzytelnianie, analitykę lub innych dostawców.

3. Uwzględnij Content Security Policy​

Restrykcyjna polityka musi zezwalać na:

  • https://chattybox.ai w script-src dla loadera widgetu.
  • Skonfigurowane źródło API czatu w connect-src.
  • W przypadku loadera z aktualnego kodu źródłowego: https://fonts.googleapis.com w style-src oraz https://fonts.gstatic.com w font-src, gdy wstrzykuje on arkusz stylów czcionki Inter. Pasujący link do arkusza Google Fonts zapobiega temu wstrzyknięciu; sama dostępność czcionki nie wystarcza. Sprawdź działanie wdrożonego loadera.
  • Źródło obrazu każdej skonfigurowanej niestandardowej ikony w img-src.
  • Wbudowane style komponentów w style-src dla bieżącej wersji widgetu.

Zacznij od istniejącej polityki i dodaj tylko te źródła, których faktycznie używasz. Nie zastępuj restrykcyjnej polityki szeroką regułą wieloznaczną.

4. Odtwórz testy integracji​

W projekcie Docusaurus dodaj powyższy wrapper Root i uruchom:

bun install
bun run start

Następnie sprawdź:

  1. Otwórz dwie różne trasy dokumentacji bez pełnego odświeżania przeglądarki.
  2. Po każdej nawigacji uruchom document.querySelectorAll('#chattybox-widget').length. Wynik musi pozostać równy 1.
  3. Zadaj pytanie, na które odpowiada zindeksowana strona, i sprawdź, czy odpowiedź zawiera odnośnik do tej strony.
  4. Zadaj pytania spoza obsługiwanego zakresu i oceń, czy asystent stosuje odpowiedź awaryjną zamiast wymyślać źródło; powtórz test dla reprezentatywnych przypadków, nie zakładając, że zawsze powstrzyma się od odpowiedzi.
  5. Przetestuj launcher w wąskim widoku mobilnym i sprawdź, czy nie zasłania nawigacji ani elementów paginacji.

Test zlicza tylko ten identyfikator; nadal może istnieć osobny loader bez identyfikatora lub z innym identyfikatorem. Sprawdź także wszystkie integracje i wyrenderowany widget. Sam wynik nie potwierdza jakości wyszukiwania. Użyj reprezentatywnego zestawu pytań oraz przewodnika po scrapingu, aby przed uruchomieniem zweryfikować pokrycie źródeł.

Co monitorować po uruchomieniu​

Rejestruj nierozwiązane pytania, nieprawidłowe cytowania, nieaktualne strony źródłowe oraz trasy, na których launcher zasłania elementy sterujące witryny. Ponownie testuj integrację po aktualizacjach motywu Docusaurus, ponieważ zmiany w nawigacji i układzie treści mogą wpłynąć na położenie widgetu, nawet gdy loader nadal działa poprawnie.

W przypadku szerszego wdrożenia skorzystaj z listy kontrolnej implementacji chatbota dla dokumentacji oraz listy kontrolnej uruchomienia.

Źródła​